Relax warmup command availability check

* Add Connection scene migration tool

* Copy connection UI into split scene

.bazelrc

@@ -1,4 +1,4 @@
-bazel-1.0.0.bazelrc
+# bazel-1.0.0.bazelrc
 
 # for now: filter out annoying TASTY warnings
 common --ui_event_filters=-INFO
@@ -29,6 +29,10 @@ common --host_cxxopt="--std=c++23"
 
 common --javacopt="-Xlint:-options"
 
+# std::filesystem and other modern C++ deps require macOS 10.15+.
+common:macos --macos_minimum_os=10.15
+common:macos --host_macos_minimum_os=10.15
+
 # suppress warnings due to https://developer.apple.com/forums/thread/733317
 # Use host_linkopt for macOS-specific flags to avoid passing them to Linux cross-compilation
 common:macos --host_linkopt=-Wl,-no_warn_duplicate_libraries
@@ -37,9 +41,20 @@ common:macos --host_linkopt=-Wl,-no_warn_duplicate_libraries
 # See: https://github.com/grpc/grpc/issues/37619
 common:macos --features=-module_maps
 
-# Fix Xcode version caching issue - avoids need for `bazel clean --expunge` after Xcode updates
+# Pin DEVELOPER_DIR so Apple repo rules use full Xcode instead of Command Line
+# Tools. The sync script writes .bazelrc.xcode with an Xcode build-version
+# marker so in-place Xcode updates refresh Bazel's generated Apple toolchains.
 common:macos --repo_env=DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
 
+# Local machine or CI overrides. This lets Bazel-only runners use Command Line
+# Tools without installing full Xcode. This must stay before .bazelrc.xcode so
+# generated Xcode settings win when both files exist.
+try-import %workspace%/.bazelrc.local
+
+# Xcode config for macOS builds. Generated by scripts/sync_bazel_xcode.sh.
+# Bakes the Xcode build version into action cache keys and sets DEVELOPER_DIR.
+try-import %workspace%/.bazelrc.xcode
+
 common --java_language_version=25
 common --java_runtime_version=remotejdk_25
 common --tool_java_language_version=25

.gitattributes

@@ -14,6 +14,17 @@ src/main/csharp/**/GUI[[:space:]]Pro[[:space:]]Kit*/**/*.ttf !filter !diff !merg
 src/main/csharp/**/Modern[[:space:]]UI[[:space:]]Pack/**/*.ttf !filter !diff !merge
 *.herodata filter=lfs diff=lfs merge=lfs -text
 *.ogg filter=lfs diff=lfs merge=lfs -text
+*.tga filter=lfs diff=lfs merge=lfs -text
+*.fbx filter=lfs diff=lfs merge=lfs -text
+*.FBX filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+# Third-party asset packs: track all files via LFS (never manually edited)
+src/main/csharp/**/DungeonMonsters2D/** filter=lfs diff=lfs merge=lfs -text
+src/main/csharp/**/Raccoon/** filter=lfs diff=lfs merge=lfs -text
+src/main/csharp/**/Polytope[[:space:]]Studio/** filter=lfs diff=lfs merge=lfs -text
+src/main/csharp/**/RRFreelance-Characters/** filter=lfs diff=lfs merge=lfs -text
+src/main/csharp/**/Dragon/** filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
 
 # Unity Smart Merge - use UnityYAMLMerge for Unity files
 # Requires configuring unityyamlmerge in ~/.gitconfig:

.github/workflows/artifact_storage_check.yml

@@ -6,8 +6,44 @@ on:
     - cron: '0 */6 * * *'
   workflow_dispatch:
 
+permissions:
+  contents: read
+  actions: write
+
 jobs:
+  cleanup-expired:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Delete expired artifacts and artifacts older than 3 days
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "Fetching all artifacts..."
+          gh api "repos/${{ github.repository }}/actions/artifacts" \
+            --paginate -q '.artifacts[] | "\(.id)\t\(.created_at)\t\(.expired)\t\(.name)"' > /tmp/all_artifacts.txt
+
+          total=$(wc -l < /tmp/all_artifacts.txt)
+          echo "Found $total total artifacts"
+
+          cutoff=$(date -u -d '3 days ago' '+%Y-%m-%dT%H:%M:%SZ')
+          echo "Deleting expired artifacts and artifacts created before $cutoff"
+
+          deleted=0
+          while IFS=$'\t' read -r id created_at expired name; do
+            if [[ "$expired" == "true" || "$created_at" < "$cutoff" ]]; then
+              gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$id" 2>/dev/null && deleted=$((deleted + 1))
+              if [ $((deleted % 50)) -eq 0 ]; then
+                echo "Deleted $deleted artifacts so far..."
+              fi
+            fi
+          done < /tmp/all_artifacts.txt
+
+          echo "Cleanup complete. Deleted $deleted artifacts out of $total total."
+          rm -f /tmp/all_artifacts.txt
+
   check-storage:
+    needs: cleanup-expired
     runs-on: ubuntu-latest
 
     steps:
@@ -15,11 +51,12 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          # Calculate total artifact storage
+          # Calculate active artifact storage. The artifacts API can list expired
+          # artifacts until they are explicitly deleted, so do not count them.
           total_bytes=$(gh api "repos/${{ github.repository }}/actions/artifacts" \
-            --paginate -q '.artifacts[].size_in_bytes' | awk '{sum+=$1} END {print sum}')
+            --paginate -q '.artifacts[] | select(.expired == false) | .size_in_bytes' | awk '{sum+=$1} END {print sum}')
 
-          total_mb=$((total_bytes / 1024 / 1024))
+          total_mb=$(( ${total_bytes:-0} / 1024 / 1024 ))
           echo "Total artifact storage: ${total_mb} MB"
 
           # Fail if over 500MB
@@ -29,7 +66,7 @@ jobs:
             echo "Largest artifacts:"
             # Save to temp file to avoid SIGPIPE/broken pipe errors with head
             gh api "repos/${{ github.repository }}/actions/artifacts" \
-              --paginate -q '.artifacts[] | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' > /tmp/artifacts.txt
+              --paginate -q '.artifacts[] | select(.expired == false) | "\(.size_in_bytes)\t\(.name)\t\(.created_at)"' > /tmp/artifacts.txt
             sort -rn /tmp/artifacts.txt | head -20 | \
               awk -F'\t' '{printf "%d MB\t%s\t%s\n", $1/1024/1024, $2, $3}'
             rm -f /tmp/artifacts.txt

.github/workflows/auth_build.yml

@@ -11,6 +11,7 @@ on:
       - 'src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto'
       - 'src/main/resources/net/eagle0/attributions.json'
       - 'ci/BUILD.bazel'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - '.bazelrc'
       - '.github/workflows/auth_build.yml'
   workflow_dispatch:
@@ -24,17 +25,25 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: auth-build-deploy
+  cancel-in-progress: false
+
 jobs:
   build-auth:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
     outputs:
       image_tag: ${{ steps.push-auth.outputs.image_tag }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
       - name: Build Auth Server Docker image
         id: build-auth
         run: |
@@ -127,10 +136,12 @@ jobs:
       FASTMAIL_FROM_NAME: ${{ secrets.FASTMAIL_FROM_NAME }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Deploy auth service to production
-        uses: appleboy/ssh-action@v1.0.3
+        uses: appleboy/ssh-action@v1.2.5
         with:
           host: ${{ secrets.DO_DROPLET_IP }}
           username: deploy
@@ -138,7 +149,7 @@ jobs:
           script_stop: true
           envs: AUTH_IMAGE,DISCORD_CLIENT_ID,DISCORD_CLIENT_SECRET,GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET,GH_OAUTH_CLIENT_ID,GH_OAUTH_CLIENT_SECRET,APPLE_SIGNIN_CLIENT_ID,APPLE_TEAM_ID,APPLE_SIGNIN_KEY_ID,APPLE_SIGNIN_PRIVATE_KEY,TWITCH_CLIENT_ID,TWITCH_CLIENT_SECRET,JWT_PRIVATE_KEY,FASTMAIL_API_TOKEN,FASTMAIL_FROM_EMAIL,FASTMAIL_FROM_NAME
           script: |
-            set -x
+            set -e
             cd /opt/eagle0
 
             # Export env vars for docker compose (appleboy/ssh-action sets them but doesn't export)

.github/workflows/bazel_cache_cleanup.yml

@@ -1,19 +1,22 @@
 name: Bazel Cache Cleanup
 
 on:
-  schedule:
-    # Run weekly on Sunday at 00:00 UTC
-    - cron: '0 0 * * 0'
+  # Disabled: bazel clean fails when another runner shares the output_base
+  # on /Volumes/remote_cache (unlinkat "Directory not empty" race).
+  # See https://github.com/nolen777/eagle0/issues/TBD for details.
+  # schedule:
+  #   - cron: '0 0 * * 0'
   workflow_dispatch:  # Allow manual trigger
 
 jobs:
   cleanup:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
 
       - name: Show disk usage before cleanup

.github/workflows/bazel_test.yml

@@ -9,6 +9,7 @@ on:
       - 'MODULE.bazel'
       - 'BUILD.bazel'
       - '.bazelrc'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
@@ -19,6 +20,7 @@ on:
       - 'MODULE.bazel'
       - 'BUILD.bazel'
       - '.bazelrc'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - '.github/workflows/bazel_test.yml'
       - '!src/main/csharp/**'
       - '!src/test/csharp/**'
@@ -40,14 +42,32 @@ jobs:
         git config --local core.sparseCheckout false 2>/dev/null || true
         git config --local --unset extensions.worktreeConfig 2>/dev/null || true
         rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
+    - name: Ensure Git LFS available for checkout
+      run: |
+        COMMON_PATHS=(/opt/homebrew/bin /usr/local/bin)
+        for path in "${COMMON_PATHS[@]}"; do
+          if [ -d "$path" ]; then
+            echo "$path" >> "$GITHUB_PATH"
+            export PATH="$path:$PATH"
+          fi
+        done
+
+        if command -v git-lfs >/dev/null 2>&1; then
+          git-lfs version
+          exit 0
+        fi
+
+        brew install git-lfs
+        git-lfs version
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
+        persist-credentials: false
         lfs: false
     - name: Check BUILD.bazel dependencies
       run: ./scripts/check_build_deps.sh --strict
     - name: Set up Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: 'lts/*'
     - name: Check JavaScript syntax
@@ -62,10 +82,30 @@ jobs:
         git config --local core.sparseCheckout false 2>/dev/null || true
         git config --local --unset extensions.worktreeConfig 2>/dev/null || true
         rm -f .git/info/sparse-checkout .git/config.worktree 2>/dev/null || true
+    - name: Ensure Git LFS available for checkout
+      run: |
+        COMMON_PATHS=(/opt/homebrew/bin /usr/local/bin)
+        for path in "${COMMON_PATHS[@]}"; do
+          if [ -d "$path" ]; then
+            echo "$path" >> "$GITHUB_PATH"
+            export PATH="$path:$PATH"
+          fi
+        done
+
+        if command -v git-lfs >/dev/null 2>&1; then
+          git-lfs version
+          exit 0
+        fi
+
+        brew install git-lfs
+        git-lfs version
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
+        persist-credentials: false
         lfs: false
+    - name: Ensure Bazel installed
+      run: ./ci/github_actions/ensure_bazel_installed.sh
     - name: Run tests
       run: bazel test --build_event_json_file=test.json //src/test/... //src/main/go/...
     - name: Collect failed test logs
@@ -102,16 +142,16 @@ jobs:
         ls -lh failed_test_logs/ 2>/dev/null || echo "No logs collected"
     - name: Archive test results
       if: always()
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: test.json
         path: test.json
-        retention-days: 5
+        retention-days: 3
     - name: Archive failed test logs
       if: always()
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: failed-test-logs
         path: failed_test_logs/
         if-no-files-found: ignore
-        retention-days: 5
+        retention-days: 3

.github/workflows/blob_cleanup.yml

@@ -11,14 +11,18 @@ permissions:
 
 jobs:
   cleanup:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
           clean: false
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
       - name: Clean up unreferenced blobs
         env:
           ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}

.github/workflows/build_sysroot.yml

@@ -27,13 +27,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Build sysroot
         run: ./tools/sysroot/build_sysroot.sh
 
       - name: Upload sysroot artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ubuntu-noble-sysroot-amd64
           path: tools/sysroot/output/
@@ -81,21 +83,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Set up QEMU for ARM64 emulation
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
         with:
           platforms: arm64
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Build ARM64 sysroot
         run: ./tools/sysroot/build_sysroot_arm64.sh
 
       - name: Upload sysroot artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ubuntu-noble-sysroot-arm64
           path: tools/sysroot/output/

.github/workflows/docker_build.yml

@@ -18,6 +18,7 @@ on:
       - '!src/main/protobuf/net/eagle0/eagle/internal/auth_internal.proto'
       - 'src/main/resources/**'
       - 'ci/BUILD.bazel'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - 'MODULE.bazel'
       - '.bazelrc'
       - 'docker-compose.prod.yml'
@@ -40,14 +41,14 @@ concurrency:
 
 permissions:
   contents: read
-  actions: read
+  actions: write  # Required to delete artifacts after deploy
 
 jobs:
   # Single consolidated build job - builds all images with one bazel invocation
   # This uses 1 runner slot instead of 4, and Bazel parallelizes internally
   # NOTE: Must run on a runner with the bazel label to ensure consistent Bazel cache
   build-all:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
     outputs:
       eagle_image_tag: ${{ steps.push-images.outputs.eagle_image_tag }}
       admin_image_tag: ${{ steps.push-images.outputs.admin_image_tag }}
@@ -68,15 +69,39 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
 
+      - name: Ensure Git LFS available for checkout
+        if: steps.check-latest.outputs.skip != 'true'
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
       - name: Checkout repository
         if: steps.check-latest.outputs.skip != 'true'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           lfs: false
 
+      - name: Ensure Bazel installed
+        if: steps.check-latest.outputs.skip != 'true'
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
       - name: Fetch LFS files needed for admin server
         if: steps.check-latest.outputs.skip != 'true'
-        run: git lfs pull --include="src/main/go/net/eagle0/admin_server/static/tiles/*"
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ./ci/github_actions/fetch_lfs.sh --include="src/main/go/net/eagle0/admin_server/static/tiles/*"
 
       - name: Build all Docker images
         if: steps.check-latest.outputs.skip != 'true'
@@ -117,7 +142,7 @@ jobs:
 
       - name: Upload warmup binary
         if: steps.check-latest.outputs.skip != 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: warmup-binary
           path: scripts/bin/warmup
@@ -202,7 +227,7 @@ jobs:
           echo "=== All images pushed successfully ==="
 
   deploy:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
     needs: [build-all]
     if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
     environment: production
@@ -244,9 +269,26 @@ jobs:
       NOTIFY_SECRET: ${{ secrets.EAGLE_NOTIFY_SECRET }}
       GITHUB_TOKEN_FOR_ADMIN: ${{ secrets.ADMIN_GITHUB_TOKEN }}
     steps:
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           lfs: false
 
       - name: Setup SSH key
@@ -257,11 +299,25 @@ jobs:
           ssh-keyscan -H "$DO_DROPLET_IP" >> ~/.ssh/known_hosts 2>/dev/null || true
 
       - name: Download warmup binary
-        uses: actions/download-artifact@v4
+        id: download-warmup
+        continue-on-error: true
+        uses: actions/download-artifact@v8
         with:
           name: warmup-binary
           path: scripts/bin/
 
+      - name: Build warmup binary fallback
+        if: steps.download-warmup.outcome != 'success'
+        run: |
+          echo "::warning::warmup-binary artifact was unavailable; rebuilding warmup binary before deploy"
+          ./ci/github_actions/ensure_bazel_installed.sh
+          bazel build \
+            --platforms=//:linux_x86_64 \
+            --extra_toolchains=@llvm_toolchain_linux//:all \
+            //ci:warmup_tar
+          mkdir -p scripts/bin
+          tar -xf bazel-bin/ci/warmup_tar.tar -C scripts/bin --strip-components=1
+
       - name: Copy config files to droplet
         run: |
           # Create directory structure on remote
@@ -280,7 +336,7 @@ jobs:
       - name: Deploy to production droplet
         run: |
           ssh -i ~/.ssh/deploy_key deploy@"$DO_DROPLET_IP" bash -s << DEPLOY_SCRIPT
-          set -ex
+          set -e
           cd /opt/eagle0
 
           # =================================================================
@@ -471,3 +527,19 @@ jobs:
           # Remove images older than 24h (keeps recent images for rollback)
           docker image prune -a -f --filter "until=24h" || true
           DEPLOY_SCRIPT
+
+  cleanup:
+    needs: [build-all, deploy]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delete warmup-binary artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ARTIFACT_ID=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts" \
+            -q '.artifacts[] | select(.name == "warmup-binary") | .id')
+          if [ -n "$ARTIFACT_ID" ]; then
+            echo "Deleting warmup-binary artifact (ID: $ARTIFACT_ID)"
+            gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$ARTIFACT_ID" || true
+          fi

.github/workflows/eagle_build.yml

@@ -11,6 +11,7 @@ on:
       - 'MODULE.bazel'
       - 'BUILD.bazel'
       - '.bazelrc'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - '.github/workflows/eagle_build.yml'
 
 concurrency:
@@ -25,9 +26,29 @@ jobs:
     runs-on: [self-hosted, bazel]
 
     steps:
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS=(/opt/homebrew/bin /usr/local/bin)
+          for path in "${COMMON_PATHS[@]}"; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+              export PATH="$path:$PATH"
+            fi
+          done
+
+          if command -v git-lfs >/dev/null 2>&1; then
+            git-lfs version
+            exit 0
+          fi
+
+          brew install git-lfs
+          git-lfs version
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
       - name: Build Eagle server
         run: bazel build //src/main/scala/net/eagle0/eagle:eagle_server

.github/workflows/installer_build.yml

@@ -5,10 +5,12 @@ on:
     branches: [ "main" ]
     paths:
       - ".github/workflows/installer_build.yml"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "src/main/go/net/eagle0/clients/win/installer/**"
   pull_request:
     paths:
       - ".github/workflows/installer_build.yml"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "src/main/go/net/eagle0/clients/win/installer/**"
   workflow_dispatch:
 
@@ -21,11 +23,32 @@ jobs:
     runs-on: [self-hosted, bazel]
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS=(/opt/homebrew/bin /usr/local/bin)
+          for path in "${COMMON_PATHS[@]}"; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+              export PATH="$path:$PATH"
+            fi
+          done
+
+          if command -v git-lfs >/dev/null 2>&1; then
+            git-lfs version
+            exit 0
+          fi
+
+          brew install git-lfs
+          git-lfs version
+      - uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
           clean: false
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
       - name: Build Go installer for Windows
         env:
           MANIFEST_PUBLIC_KEY: ${{ secrets.MANIFEST_PUBLIC_KEY }}
@@ -50,7 +73,7 @@ jobs:
 
       - name: Archive installer binary
         if: success() || failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: eagle-installer
           path: ./installer-output/

.github/workflows/ios_addressables_build.yml

@@ -1,98 +0,0 @@
-name: iOS Addressables Build
-
-on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - ".github/workflows/ios_addressables_build.yml"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/AddressableAssetsData/**"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Music/**"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Editor/BuildScript.cs"
-      - "ci/github_actions/build_ios_addressables.sh"
-      - "ci/github_actions/upload_addressables.sh"
-  pull_request:
-    paths:
-      - ".github/workflows/ios_addressables_build.yml"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/AddressableAssetsData/**"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Music/**"
-      - "src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Editor/BuildScript.cs"
-      - "ci/github_actions/build_ios_addressables.sh"
-      - "ci/github_actions/upload_addressables.sh"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-permissions:
-  contents: read
-
-env:
-  # Runner-specific build directory to allow parallel builds on multiple runners
-  EAGLE0_BUILD_DIR: /tmp/eagle0-${{ github.run_id }}
-
-jobs:
-  build-ios-addressables:
-    runs-on: [self-hosted, macOS, unity-mac]
-
-    steps:
-      - name: Prune stale PR refs
-        run: |
-          # Self-hosted runners persist .git between runs. When a PR is updated,
-          # old local refs (refs/remotes/pull/*/merge) may point to commits whose
-          # objects were never fetched or have been pruned. Remove these stale refs
-          # before checkout to prevent "missing object" errors.
-          if [ -d ".git" ]; then
-            echo "Pruning stale PR refs..."
-            git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
-              xargs -r git update-ref -d 2>/dev/null || true
-          fi
-      - uses: actions/checkout@v4
-        with:
-          lfs: false  # Fetch LFS after checkout to avoid stale ref issues
-          clean: false  # Library/ persists between runs on self-hosted runners
-
-      - name: Clean stale files
-        run: |
-          git clean -ffd
-          rm -rf src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee/
-
-      - name: Fetch LFS files
-        run: |
-          git lfs install
-          git lfs pull
-
-      - name: Ensure Unity version installed
-        run: ./ci/github_actions/ensure_unity_installed.sh ios
-
-      - name: Build iOS Addressables
-        run: ./ci/github_actions/build_ios_addressables.sh "$EAGLE0_BUILD_DIR/editor_ios_addressables.log"
-
-      - name: Upload Addressables to CDN
-        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-        env:
-          ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY_ID }}
-          SECRET_KEY: ${{ secrets.SECRET_KEY }}
-        run: ./ci/github_actions/upload_addressables.sh iOS
-
-      - name: Purge CDN cache for iOS addressables
-        if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-        env:
-          DO_CDN_PAT: ${{ secrets.DO_CDN_PAT }}
-        run: |
-          curl -s -X DELETE "https://api.digitalocean.com/v2/cdn/endpoints/8c98df29-6f0c-4704-8e82-ca40a2b81aa8/cache" \
-            -H "Authorization: Bearer $DO_CDN_PAT" \
-            -H "Content-Type: application/json" \
-            -d '{"files": ["addressables/iOS/*"]}' \
-            --fail || echo "Warning: CDN purge failed (non-fatal)"
-
-      - name: Archive Build Log
-        if: success() || failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: editor_ios_addressables.log
-          path: ${{ env.EAGLE0_BUILD_DIR }}/editor_ios_addressables.log
-          retention-days: 5
-      - name: Cleanup build directory
-        if: always()
-        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"

.github/workflows/ios_testflight.yml

@@ -1,6 +1,8 @@
 name: iOS TestFlight
 
 on:
+  schedule:
+    - cron: '0 5 * * *'  # 9 PM Pacific (UTC-8) / 10 PM PDT (UTC-7)
   workflow_dispatch:
     inputs:
       skip_upload:
@@ -11,6 +13,7 @@ on:
 
 permissions:
   contents: read
+  actions: write
 
 env:
   # Runner-specific build directory to allow parallel builds on multiple runners
@@ -19,8 +22,93 @@ env:
   KEYCHAIN_NAME: ios-build-${{ github.run_id }}.keychain
 
 jobs:
+  check-changes:
+    # Skip nightly builds when nothing has changed since the last successful
+    # scheduled run. Manual workflow_dispatch always builds.
+    runs-on: ubuntu-latest
+    outputs:
+      should_build: ${{ steps.check.outputs.should_build }}
+    steps:
+      - name: Check for relevant changes since last successful run
+        id: check
+        uses: actions/github-script@v8
+        with:
+          script: |
+            if (context.eventName === 'workflow_dispatch') {
+              core.setOutput('should_build', 'true');
+              console.log('Manual trigger — building');
+              return;
+            }
+
+            const { data: { workflow_runs: runs } } = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'ios_testflight.yml',
+              status: 'success',
+              event: 'schedule',
+              per_page: 1,
+            });
+
+            if (runs.length === 0) {
+              core.setOutput('should_build', 'true');
+              console.log('No previous successful scheduled run — building');
+              return;
+            }
+
+            const lastSha = runs[0].head_sha;
+            console.log(`Last successful scheduled run: ${lastSha}`);
+            console.log(`Current SHA: ${context.sha}`);
+
+            if (lastSha === context.sha) {
+              core.setOutput('should_build', 'false');
+              console.log('No changes since last successful run — skipping');
+              return;
+            }
+
+            // Paths that can affect the iOS Unity build.
+            const relevantPrefixes = [
+              'src/main/csharp/',     // Unity project
+              'src/main/protobuf/',   // Generates C# code
+              'src/main/resources/',  // Game data & maps
+              'scripts/',             // Build scripts
+              'ci/',                  // CI scripts & workflows
+              '.github/workflows/ios_testflight.yml',
+              'MODULE.bazel',
+              '.bazelrc',
+            ];
+
+            const { data: comparison } = await github.rest.repos.compareCommitsWithBasehead({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              basehead: `${lastSha}...${context.sha}`,
+              per_page: 1,  // We only need the file list, not patches
+            });
+
+            // If the diff is too large, build to be safe
+            if (comparison.files === undefined) {
+              core.setOutput('should_build', 'true');
+              console.log('Could not retrieve file list — building to be safe');
+              return;
+            }
+
+            const relevant = comparison.files.filter(f =>
+              relevantPrefixes.some(p => f.filename.startsWith(p))
+            );
+
+            if (relevant.length > 0) {
+              core.setOutput('should_build', 'true');
+              console.log(`${relevant.length} relevant file(s) changed:`);
+              relevant.slice(0, 20).forEach(f => console.log(`  ${f.filename}`));
+              if (relevant.length > 20) console.log(`  ... and ${relevant.length - 20} more`);
+            } else {
+              core.setOutput('should_build', 'false');
+              console.log(`${comparison.files.length} file(s) changed, none in relevant paths — skipping`);
+            }
+
   build-unity:
-    runs-on: [self-hosted, macOS, testflight]
+    needs: check-changes
+    if: needs.check-changes.outputs.should_build == 'true'
+    runs-on: [self-hosted, macOS, testflight, halfdan]
 
     steps:
       - name: Prune stale PR refs
@@ -34,8 +122,26 @@ jobs:
             git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
               xargs -r git update-ref -d 2>/dev/null || true
           fi
-      - uses: actions/checkout@v4
+
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           lfs: false  # Fetch LFS after checkout to avoid stale ref issues
           clean: false  # Library/ persists between runs on self-hosted runners
           fetch-depth: 0
@@ -46,9 +152,9 @@ jobs:
           rm -rf src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee/
 
       - name: Fetch LFS files
-        run: |
-          git lfs install
-          git lfs pull
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ./ci/github_actions/fetch_lfs.sh
 
       - name: Ensure Unity version installed
         run: ./ci/github_actions/ensure_unity_installed.sh ios
@@ -78,17 +184,81 @@ jobs:
 
       - name: Archive Build Log
         if: success() || failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: editor_ios.log
           path: ${{ env.EAGLE0_BUILD_DIR }}/editor_ios.log
-          retention-days: 5
+          retention-days: 3
+
+      - name: Package generated iOS project
+        if: success()
+        run: |
+          tar -czf "$RUNNER_TEMP/eagle0-ios-project.tar.gz" -C "$EAGLE0_BUILD_DIR" eagle0iOS
+
+      - name: Upload generated iOS project
+        if: success()
+        uses: actions/upload-artifact@v7
+        with:
+          name: eagle0-ios-project-${{ github.run_id }}
+          path: ${{ runner.temp }}/eagle0-ios-project.tar.gz
+          retention-days: 1
+
+      - name: Cleanup build directory
+        if: always()
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
 
   archive-and-upload:
     needs: build-unity
-    runs-on: [self-hosted, macOS, testflight]
+    runs-on: [self-hosted, macOS, testflight, halfdan]
 
     steps:
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
+        with:
+          persist-credentials: false
+          lfs: false
+
+      - name: Clean build directory
+        run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
+
+      - name: Download generated iOS project
+        uses: actions/download-artifact@v8
+        with:
+          name: eagle0-ios-project-${{ github.run_id }}
+          path: ${{ runner.temp }}
+
+      - name: Extract generated iOS project
+        run: |
+          mkdir -p "$EAGLE0_BUILD_DIR"
+          tar -xzf "$RUNNER_TEMP/eagle0-ios-project.tar.gz" -C "$EAGLE0_BUILD_DIR"
+
+      - name: Delete generated iOS project artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          artifact_id=$(gh api "repos/${{ github.repository }}/actions/artifacts" \
+            --paginate \
+            --jq '.artifacts[] | select(.name == "eagle0-ios-project-${{ github.run_id }}") | .id')
+
+          if [ -n "$artifact_id" ]; then
+            gh api -X DELETE "repos/${{ github.repository }}/actions/artifacts/$artifact_id"
+          fi
+
       - name: Install Signing Certificate
         env:
           IOS_CERTIFICATE: ${{ secrets.IOS_CERTIFICATE }}
@@ -140,10 +310,20 @@ jobs:
       - name: Archive and Export IPA
         env:
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
+          APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
+          APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
         run: |
+          # Write API key to file for xcodebuild
+          API_KEY_PATH=$(mktemp)
+          echo "$APP_STORE_CONNECT_API_KEY" > "$API_KEY_PATH"
+          export APP_STORE_CONNECT_API_KEY_PATH="$API_KEY_PATH"
+
           chmod +x ./ci/github_actions/archive_ios.sh
           ./ci/github_actions/archive_ios.sh "$EAGLE0_BUILD_DIR/eagle0iOS" "$EAGLE0_BUILD_DIR/archive" "$APPLE_TEAM_ID" "$PROFILE_UUID"
 
+          rm -f "$API_KEY_PATH"
+
       - name: Upload to TestFlight
         if: ${{ github.event.inputs.skip_upload != 'true' }}
         env:
@@ -168,7 +348,7 @@ jobs:
       - name: Upload IPA artifact
         # Only keep artifact if we skipped TestFlight upload (for debugging)
         if: success() && github.event.inputs.skip_upload == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: eagle0-ios-${{ github.run_id }}
           path: ${{ env.EAGLE0_BUILD_DIR }}/archive/eagle0.ipa

.github/workflows/mac_build.yml

@@ -20,6 +20,7 @@ on:
       - "scripts/notarize_wait.sh"
       - "ci/github_actions/build_mac.sh"
       - "ci/github_actions/build_unity_mac.sh"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "ci/github_actions/upload_addressables.sh"
       - "ci/github_actions/ensure_unity_installed.sh"
       - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
@@ -32,12 +33,14 @@ on:
       - "src/main/go/net/eagle0/build/mac_build_handler/**"
       - "scripts/build_mac_plugin.sh"
       - "scripts/build_sparkle_plugin.sh"
+      - "src/main/objc/net/eagle0/clients/unity/sparkle/**"
       - "scripts/inject_sparkle.sh"
       - "scripts/codesign_mac_app.sh"
       - "scripts/notarize_submit.sh"
       - "scripts/notarize_wait.sh"
       - "ci/github_actions/build_mac.sh"
       - "ci/github_actions/build_unity_mac.sh"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "ci/mac/**"
   workflow_dispatch:
     inputs:
@@ -63,7 +66,7 @@ env:
 
 jobs:
   build-and-sign:
-    runs-on: [self-hosted, macOS, unity-mac]
+    runs-on: [self-hosted, macOS, unity-mac, halfdan]
     outputs:
       submission_id: ${{ steps.notarize-submit.outputs.submission_id }}
       should_deploy: ${{ steps.check-deploy.outputs.should_deploy }}
@@ -80,8 +83,26 @@ jobs:
             git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
               xargs -r git update-ref -d 2>/dev/null || true
           fi
-      - uses: actions/checkout@v4
+
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           lfs: false  # Fetch LFS after checkout to avoid stale ref issues
           clean: false  # Library/ persists between runs on self-hosted runners
           fetch-depth: 0  # For version numbering from git history
@@ -108,19 +129,27 @@ jobs:
           fi
 
       - name: Fetch LFS files
-        run: |
-          git lfs install
-          git lfs pull
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ./ci/github_actions/fetch_lfs.sh
 
       - name: Ensure Unity version installed
         run: ./ci/github_actions/ensure_unity_installed.sh mac
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
+      - name: Sync Bazel Xcode config
+        run: ./scripts/sync_bazel_xcode.sh
+
       - name: Build Mac Unity
         run: ./ci/github_actions/build_unity_mac.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC"
 
       - name: Save build SHA for Bee/ cache invalidation
         if: success()
-        run: git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
+        run: |
+          mkdir -p src/main/csharp/net/eagle0/clients/unity/eagle0/Library
+          git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
 
       - name: Upload Addressables to CDN
         if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
@@ -225,7 +254,7 @@ jobs:
 
       - name: Upload signed app
         if: success() && steps.check-deploy.outputs.should_deploy == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: signed-mac-app-${{ github.run_id }}
           path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app.zip
@@ -233,11 +262,11 @@ jobs:
 
       - name: Archive Build Log
         if: success() || failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: editor_mac.log
           path: ${{ env.EAGLE0_BUILD_DIR }}/editor_mac.log
-          retention-days: 5
+          retention-days: 3
       - name: Cleanup build directory
         if: always()
         run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
@@ -245,18 +274,35 @@ jobs:
   wait-notarization:
     needs: build-and-sign
     if: needs.build-and-sign.outputs.should_deploy == 'true'
-    runs-on: [self-hosted, macOS, notarize]
+    runs-on: [self-hosted, macOS, notarize, halfdan]
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           sparse-checkout: scripts
 
       - name: Clean download directory
         run: rm -rf ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Download signed app
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: signed-mac-app-${{ github.run_id }}
           path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
@@ -284,7 +330,7 @@ jobs:
           ditto -c -k --keepParent eagle0.app eagle0.app.zip
 
       - name: Upload notarized app
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: notarized-mac-app-${{ github.run_id }}
           path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC/eagle0.app.zip
@@ -296,20 +342,37 @@ jobs:
   deploy:
     needs: [build-and-sign, wait-notarization]
     if: needs.build-and-sign.outputs.should_deploy == 'true'
-    runs-on: [self-hosted, macOS, unity-mac]
+    runs-on: [self-hosted, macOS, notarize, halfdan]
     outputs:
       deployed_version: ${{ steps.deploy-mac.outputs.deployed_version }}
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           fetch-depth: 0  # For version numbering
 
       - name: Clean download directory
         run: rm -rf ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
 
       - name: Download notarized app
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: notarized-mac-app-${{ github.run_id }}
           path: ${{ env.EAGLE0_BUILD_DIR }}/eagle0MAC
@@ -320,6 +383,12 @@ jobs:
           ditto -x -k eagle0.app.zip .
           rm eagle0.app.zip
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
+      - name: Sync Bazel Xcode config
+        run: ./scripts/sync_bazel_xcode.sh
+
       - name: Deploy Mac Build
         id: deploy-mac
         env:

.github/workflows/registry_cleanup.yml

@@ -39,9 +39,9 @@ jobs:
           echo "Dry run: ${DRY_RUN}"
           echo ""
 
-          # List of repositories to clean
-          # Use tail to skip header row in case --no-header doesn't work
-          REPOS=$(doctl registry repository list-v2 --format Name --no-header | grep -v '^Name$' | grep -v '^$')
+          # List repositories via JSON. Text output can wrap table rows and make
+          # headers/tags/digests look like repository names.
+          REPOS=$(doctl registry repository list-v2 "${REGISTRY}" --output json | jq -r '.[] | .name // .Name // empty')
 
           for REPO in $REPOS; do
             echo "=== Processing repository: ${REPO} ==="
@@ -88,5 +88,20 @@ jobs:
         if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'false')
         run: |
           echo "Starting garbage collection..."
-          doctl registry garbage-collection start --force
-          echo "Garbage collection started. It may take a few minutes to complete."
+          set +e
+          GC_OUTPUT=$(doctl registry garbage-collection start --force 2>&1)
+          GC_STATUS=$?
+          set -e
+
+          echo "$GC_OUTPUT"
+          if [ "$GC_STATUS" -eq 0 ]; then
+            echo "Garbage collection started. It may take a few minutes to complete."
+            exit 0
+          fi
+
+          if echo "$GC_OUTPUT" | grep -q "automated garbage collection is enabled"; then
+            echo "Automated garbage collection is enabled for this registry; skipping manual garbage collection."
+            exit 0
+          fi
+
+          exit "$GC_STATUS"

.github/workflows/s3_archive_cleanup.yml

@@ -0,0 +1,86 @@
+name: S3 Archive Cleanup
+
+on:
+  schedule:
+    # Run weekly on Sunday at 05:00 UTC
+    - cron: '0 5 * * 0'
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: read
+
+jobs:
+  cleanup:
+    runs-on: [self-hosted, bazel, halfdan]
+
+    steps:
+      - name: Ensure AWS CLI is available
+        run: |
+          if ! command -v aws &> /dev/null; then
+            brew install awscli
+          fi
+
+      - name: Delete old archived game folders
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.DO_SPACES_ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.DO_SPACES_SECRET_KEY }}
+        run: |
+          set -euo pipefail
+
+          S3_ENDPOINT="https://sfo3.digitaloceanspaces.com"
+          BUCKET="s3://eagle0/eagle/archived/"
+
+          # macOS date syntax
+          CUTOFF=$(date -v-1m +%s)
+          DELETED=0
+          SKIPPED=0
+          NO_DIR_FILE=0
+
+          echo "Cutoff date: $(date -r ${CUTOFF} '+%Y-%m-%dT%H:%M:%S')"
+          echo ""
+
+          FOLDERS=$(aws s3 ls "$BUCKET" --endpoint-url "$S3_ENDPOINT" \
+            | awk '/PRE/{gsub(/\/$/,"",$2); print $2}')
+
+          if [ -z "$FOLDERS" ]; then
+            echo "No archived folders found."
+            exit 0
+          fi
+
+          TOTAL=$(echo "$FOLDERS" | wc -l | tr -d ' ')
+          CURRENT=0
+
+          for game_id in $FOLDERS; do
+            CURRENT=$((CURRENT + 1))
+
+            DIR_INFO=$(aws s3 ls "${BUCKET}${game_id}/directory.e0i" \
+              --endpoint-url "$S3_ENDPOINT" 2>/dev/null || true)
+
+            if [ -z "$DIR_INFO" ]; then
+              echo "[$CURRENT/$TOTAL] DELETE $game_id (no directory.e0i)"
+              aws s3 rm --recursive "${BUCKET}${game_id}/" \
+                --endpoint-url "$S3_ENDPOINT" > /dev/null 2>&1
+              DELETED=$((DELETED + 1))
+              NO_DIR_FILE=$((NO_DIR_FILE + 1))
+              continue
+            fi
+
+            FILE_DATE=$(echo "$DIR_INFO" | awk '{print $1 " " $2}')
+            FILE_EPOCH=$(date -j -f '%Y-%m-%d %H:%M:%S' "$FILE_DATE" +%s 2>/dev/null || echo "0")
+
+            if [ "$FILE_EPOCH" -lt "$CUTOFF" ]; then
+              echo "[$CURRENT/$TOTAL] DELETE $game_id (directory.e0i from $FILE_DATE)"
+              aws s3 rm --recursive "${BUCKET}${game_id}/" \
+                --endpoint-url "$S3_ENDPOINT" > /dev/null 2>&1
+              DELETED=$((DELETED + 1))
+            else
+              echo "[$CURRENT/$TOTAL] KEEP $game_id (directory.e0i from $FILE_DATE)"
+              SKIPPED=$((SKIPPED + 1))
+            fi
+          done
+
+          echo ""
+          echo "=== Summary ==="
+          echo "Total folders: $TOTAL"
+          echo "Deleted: $DELETED"
+          echo "Kept (recent): $SKIPPED"

.github/workflows/shardok_arm64_build.yml

@@ -9,6 +9,7 @@ on:
       - 'src/main/protobuf/net/eagle0/common/**'
       - 'src/main/resources/net/eagle0/shardok/**'
       - 'ci/BUILD.bazel'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - 'MODULE.bazel'
       - '.bazelrc'
       - '.github/workflows/shardok_arm64_build.yml'
@@ -29,15 +30,19 @@ permissions:
 
 jobs:
   build-shardok-arm64:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
     outputs:
       image_tag: ${{ steps.push-shardok.outputs.image_tag }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
 
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+
       - name: Build Shardok ARM64 binary (cross-compile for Linux ARM64)
         run: |
           set -ex
@@ -165,7 +170,7 @@ jobs:
           echo "Also tagged as: registry.digitalocean.com/eagle0/shardok-server:arm64-latest"
 
   deploy-hetzner:
-    runs-on: [self-hosted, bazel]
+    runs-on: [self-hosted, bazel, halfdan]
     needs: [build-shardok-arm64]
     if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.push_images == 'true')
     environment: production
@@ -180,33 +185,55 @@ jobs:
           # Add host key to known_hosts to avoid prompt
           ssh-keyscan -H ${{ secrets.HETZNER_IP }} >> ~/.ssh/known_hosts 2>/dev/null || true
 
+      - name: Pull Shardok image tarball for Hetzner
+        env:
+          DO_REGISTRY_TOKEN: ${{ secrets.DO_REGISTRY_TOKEN }}
+        run: |
+          set -ex
+
+          # Hetzner is IPv6-only, while Docker can be redirected to IPv4-only
+          # DigitalOcean registry/blob endpoints. Pull on the runner and copy
+          # the Docker-loadable tarball over SSH instead.
+          CRANE_VERSION="v0.20.2"
+          CRANE_DIR="${HOME}/.local/bin"
+          CRANE="${CRANE_DIR}/crane"
+          if [ ! -x "$CRANE" ] || ! "$CRANE" version 2>/dev/null | grep -q "0.20.2"; then
+            echo "Installing crane ${CRANE_VERSION}..."
+            mkdir -p "$CRANE_DIR"
+            curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Darwin_arm64.tar.gz" | tar xzf - -C "$CRANE_DIR" crane
+            chmod +x "$CRANE"
+          else
+            echo "Using cached crane at $CRANE"
+          fi
+
+          AUTH=$(echo -n "${DO_REGISTRY_TOKEN}:${DO_REGISTRY_TOKEN}" | base64)
+          mkdir -p ~/.docker
+          echo "{\"auths\":{\"registry.digitalocean.com\":{\"auth\":\"${AUTH}\"}}}" > ~/.docker/config.json
+
+          IMAGE_TAR="${RUNNER_TEMP}/shardok-arm64-image.tar"
+          "$CRANE" pull "${SHARDOK_IMAGE}" "$IMAGE_TAR"
+          echo "SHARDOK_IMAGE_TAR=$IMAGE_TAR" >> "$GITHUB_ENV"
+
+      - name: Copy Shardok image tarball to Hetzner
+        run: |
+          set -ex
+          ssh -i ~/.ssh/hetzner_deploy -o StrictHostKeyChecking=accept-new deploy@${{ secrets.HETZNER_IP }} \
+            "cat > /tmp/shardok-arm64-image.tar" < "$SHARDOK_IMAGE_TAR"
+
       - name: Deploy to Hetzner
         run: |
           ssh -i ~/.ssh/hetzner_deploy -o StrictHostKeyChecking=accept-new deploy@${{ secrets.HETZNER_IP }} << 'ENDSSH'
           set -ex
           cd /opt/eagle0
 
-          # Login to registry
-          echo "${{ secrets.DO_REGISTRY_TOKEN }}" | docker login registry.digitalocean.com -u "${{ secrets.DO_REGISTRY_TOKEN }}" --password-stdin
-
-          echo "Deploying Shardok ARM64: ${{ needs.build-shardok-arm64.outputs.image_tag }}"
-
-          # Pre-warm NAT64 path to DigitalOcean registry (IPv6-only Hetzner → IPv4 registry)
-          curl -sf --max-time 10 https://registry.digitalocean.com/v2/ > /dev/null 2>&1 || true
-
-          # Pull the new image (retry up to 3 times for NAT64 connectivity flakiness)
-          for attempt in 1 2 3; do
-            echo "Pull attempt $attempt..."
-            if docker pull "${{ needs.build-shardok-arm64.outputs.image_tag }}"; then
-              break
-            fi
-            if [ "$attempt" -eq 3 ]; then
-              echo "ERROR: docker pull failed after 3 attempts"
-              exit 1
-            fi
-            echo "Pull failed, retrying in 10s..."
-            sleep 10
-          done
+          SHARDOK_IMAGE="${{ needs.build-shardok-arm64.outputs.image_tag }}"
+          echo "Loading Shardok ARM64 image: $SHARDOK_IMAGE"
+          docker load -i /tmp/shardok-arm64-image.tar
+          rm -f /tmp/shardok-arm64-image.tar
+          docker image inspect "$SHARDOK_IMAGE" > /dev/null
+          echo "Loaded image ID: $(docker image inspect --format '{{.Id}}' "$SHARDOK_IMAGE")"
+          echo "Shardok binary SHA256:"
+          docker run --rm --entrypoint sha256sum "$SHARDOK_IMAGE" /app/shardok-server
 
           # Stop and remove any container using port 40042 or named shardok*
           docker ps -q --filter "publish=40042" | xargs -r docker stop
@@ -224,11 +251,12 @@ jobs:
             -v /usr/local/share/eagle0:/usr/local/share/eagle0:ro \
             -e SHARDOK_RESOURCES_PATH=/app/resources \
             -e SHARDOK_MAPS_PATH=/app/resources/maps \
-            "${{ needs.build-shardok-arm64.outputs.image_tag }}"
+            "$SHARDOK_IMAGE"
 
           # Wait and verify
           sleep 5
           docker ps | grep shardok-ai
+          echo "Running container image ID: $(docker inspect --format '{{.Image}}' shardok-ai)"
 
           # Cleanup old images
           docker image prune -f

.github/workflows/shardok_build.yml

@@ -5,13 +5,14 @@ on:
   pull_request:
     paths:
       - 'src/main/cpp/**'
-      - 'src/main/proto/net/eagle0/shardok/**'
-      - 'src/main/proto/net/eagle0/common/**'
+      - 'src/main/protobuf/net/eagle0/shardok/**'
+      - 'src/main/protobuf/net/eagle0/common/**'
       - 'src/main/go/net/eagle0/build/**'
       - 'WORKSPACE'
       - 'MODULE.bazel'
       - 'BUILD.bazel'
       - '.bazelrc'
+      - 'ci/github_actions/ensure_bazel_installed.sh'
       - '.github/workflows/shardok_build.yml'
 
 concurrency:
@@ -26,9 +27,29 @@ jobs:
     runs-on: [self-hosted, bazel]
 
     steps:
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS=(/opt/homebrew/bin /usr/local/bin)
+          for path in "${COMMON_PATHS[@]}"; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+              export PATH="$path:$PATH"
+            fi
+          done
+
+          if command -v git-lfs >/dev/null 2>&1; then
+            git-lfs version
+            exit 0
+          fi
+
+          brew install git-lfs
+          git-lfs version
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
+          persist-credentials: false
           lfs: false
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
       - name: Build Shardok server
         run: bazel build -c opt //src/main/cpp/net/eagle0/shardok:shardok-server

.github/workflows/unity_build.yml

@@ -15,6 +15,8 @@ on:
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
       - "ci/github_actions/build_unity.sh"
+      - "ci/github_actions/test_unity_editmode.sh"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "ci/github_actions/upload_addressables.sh"
       - "ci/github_actions/ensure_unity_installed.sh"
       - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
@@ -34,6 +36,8 @@ on:
       - "scripts/build_plugins.sh"
       - "scripts/build_windows_plugin.sh"
       - "ci/github_actions/build_unity.sh"
+      - "ci/github_actions/test_unity_editmode.sh"
+      - "ci/github_actions/ensure_bazel_installed.sh"
       - "ci/github_actions/upload_addressables.sh"
       - "ci/github_actions/ensure_unity_installed.sh"
       - "src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
@@ -53,7 +57,7 @@ env:
 
 jobs:
   windows-unity:
-    runs-on: [self-hosted, macOS, unity-windows]
+    runs-on: [self-hosted, macOS, unity-windows, halfdan]
     outputs:
       deployed_version: ${{ steps.get-version.outputs.deployed_version }}
 
@@ -69,44 +73,88 @@ jobs:
             git for-each-ref --format='%(refname)' refs/remotes/pull/ 2>/dev/null | \
               xargs -r git update-ref -d 2>/dev/null || true
           fi
-      - uses: actions/checkout@v4
+
+      - name: Ensure Git LFS available for checkout
+        run: |
+          COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+          export PATH="${COMMON_PATHS}:${PATH}"
+          for path in /opt/homebrew/bin /usr/local/bin; do
+            if [ -d "$path" ]; then
+              echo "$path" >> "$GITHUB_PATH"
+            fi
+          done
+          if ! command -v git-lfs >/dev/null 2>&1; then
+            brew install git-lfs
+          fi
+          git-lfs --version
+
+      - uses: actions/checkout@v6
+        env:
+          GIT_LFS_SKIP_SMUDGE: 1
         with:
+          persist-credentials: false
           lfs: false  # Fetch LFS after checkout to avoid stale ref issues
           clean: false  # Library/ persists between runs on self-hosted runners
 
       - name: Clean stale files
         run: |
           git clean -ffd
+          LIBRARY_DIR="src/main/csharp/net/eagle0/clients/unity/eagle0/Library"
+          VERSION_CACHE="$LIBRARY_DIR/.last_unity_version"
+          PROJECT_VERSION_FILE="src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt"
+          CURRENT_VERSION=$(grep "m_EditorVersion:" "$PROJECT_VERSION_FILE" | head -1 | sed 's/m_EditorVersion: //')
+
+          # Nuke Library/ when Unity version changes to avoid import loops
+          if [ -f "$VERSION_CACHE" ]; then
+            CACHED_VERSION=$(cat "$VERSION_CACHE")
+            if [ "$CACHED_VERSION" != "$CURRENT_VERSION" ]; then
+              echo "Unity version changed ($CACHED_VERSION -> $CURRENT_VERSION) -- clearing Library/"
+              rm -rf "$LIBRARY_DIR"
+            fi
+          fi
+
           # Only clear Bee/ when C# files were added/deleted/renamed (structural
           # changes that stale the DAG). Content-only modifications are handled by
           # Bee's incremental compilation. See persist_library.sh for background.
-          BEE_DIR="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/Bee"
-          SHA_FILE="src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha"
+          BEE_DIR="$LIBRARY_DIR/Bee"
+          SHA_FILE="$LIBRARY_DIR/.last_built_sha"
           if [ -f "$SHA_FILE" ] && [ -d "$BEE_DIR" ]; then
             LAST_SHA=$(cat "$SHA_FILE")
             if git diff --diff-filter=ADR --name-only "$LAST_SHA" HEAD -- '*.cs' '*.csproj' '*.asmdef' 2>/dev/null | grep -q .; then
-              echo "C# files added/deleted/renamed since $LAST_SHA — clearing Bee/"
+              echo "C# files added/deleted/renamed since $LAST_SHA -- clearing Bee/"
               rm -rf "$BEE_DIR"
             else
-              echo "No structural C# changes since $LAST_SHA — keeping Bee/"
+              echo "No structural C# changes since $LAST_SHA -- keeping Bee/"
             fi
           else
-            echo "No previous build SHA or no Bee/ — clearing Bee/ as safe default"
+            echo "No previous build SHA or no Bee/ -- clearing Bee/ as safe default"
             rm -rf "$BEE_DIR"
           fi
 
       - name: Fetch LFS files
-        run: |
-          git lfs install
-          git lfs pull
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ./ci/github_actions/fetch_lfs.sh
       - name: Ensure Unity version installed
         run: ./ci/github_actions/ensure_unity_installed.sh windows
+      - name: Ensure Bazel installed
+        run: ./ci/github_actions/ensure_bazel_installed.sh
+      - name: Run Unity EditMode tests
+        run: ./ci/github_actions/test_unity_editmode.sh
       - name: Build Windows unity
         run: ./ci/github_actions/build_unity.sh "${{ env.EAGLE0_BUILD_DIR }}/eagle0WIN"
 
       - name: Save build SHA for Bee/ cache invalidation
         if: success()
-        run: git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
+        run: |
+          mkdir -p src/main/csharp/net/eagle0/clients/unity/eagle0/Library
+          git rev-parse HEAD > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_built_sha
+
+      - name: Save Unity version for Library/ cache invalidation
+        if: success()
+        run: |
+          mkdir -p src/main/csharp/net/eagle0/clients/unity/eagle0/Library
+          grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //' > src/main/csharp/net/eagle0/clients/unity/eagle0/Library/.last_unity_version
 
       - name: Upload Addressables to CDN
         if: success() && github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
@@ -154,11 +202,20 @@ jobs:
 
       - name: Archive build log
         if: success() || failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: editor_win.log
           path: ${{ env.EAGLE0_BUILD_DIR }}/editor_win.log
-          retention-days: 5
+          retention-days: 3
+      - name: Archive EditMode test artifacts
+        if: success() || failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: unity_editmode_tests
+          path: |
+            ${{ env.EAGLE0_BUILD_DIR }}/editor_editmode_tests.log
+            ${{ env.EAGLE0_BUILD_DIR }}/editmode-test-results.xml
+          retention-days: 3
       - name: Cleanup build directory
         if: always()
         run: rm -rf "${{ env.EAGLE0_BUILD_DIR }}"
@@ -174,4 +231,4 @@ jobs:
         run: |
           curl -X POST "https://admin.eagle0.net/notify-update?platform=windows&version=${{ needs.windows-unity.outputs.deployed_version }}&required=false" \
             -H "X-Notify-Secret: $NOTIFY_SECRET" \
-            --fail --silent --show-error || echo "Warning: Failed to notify clients (non-fatal)"
+            --fail --silent --show-error || echo "Warning: Failed to notify clients (non-fatal)"

.gitignore

@@ -23,6 +23,8 @@ bazel-bin
 bazel-eagle0*
 bazel-out
 bazel-testlogs
+.bazelrc.local
+.bazelrc.xcode
 .ijwb
 .clwb
 buildWin.sh
@@ -42,3 +44,5 @@ src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/Eagle0Protos/
 src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/Packages/com.unity.dedicated-server/
 node_modules/
 tools/map_generator/output/
+src/main/csharp/net/eagle0/clients/unity/eagle0/docs/generated/unity_asset_usage_audit_files.csv
+src/main/csharp/net/eagle0/clients/unity/eagle0/docs/generated/unity_lfs_asset_audit.csv

.pre-commit-config.yaml

@@ -14,7 +14,16 @@ repos:
     -   id: clang-format
         args: [-i, --no-diff]
         types_or: ["c++", "c#"]
-        exclude: ^src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins
+        exclude: >-
+          (?x)^src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/(
+            Plugins|
+            DungeonMonsters2D|
+            Dragon|
+            ithappy|
+            Polytope\ Studio|
+            RRFreelance-Characters|
+            Raccoon
+          )/
 -   repo: https://github.com/yoheimuta/protolint
     rev: v0.42.2
     hooks:
@@ -25,8 +34,8 @@ repos:
     hooks:
     -   id: scalafmt
         name: scalafmt
-        language: system 
-        entry: scalafmt -i -f 
+        language: system
+        entry: ./scripts/pre-commit-scalafmt.sh
         types_or: ["scala"]
 - repo: local
   hooks:

AGENTS.md

@@ -0,0 +1,380 @@
+# AGENTS.md
+
+## CRITICAL BASH RULES (NEVER VIOLATE)
+
+**NEVER chain bash commands.** Do not use `&&`, `||`, or `;` to combine commands. Each command must be a separate Bash tool call. Use parallel tool calls when commands are independent.
+
+**NEVER prefix a command with `cd`.** Run `git`, `gh`, `bazel`, etc. directly from whatever the cwd already is. The cwd is a subdirectory of the worktree; `git`/`gh` find the repo via `.git` discovery and `bazel` finds the workspace via MODULE.bazel discovery — walking up from a subdir works fine. The shell resets cwd after every command anyway, so a `cd` never persists. (And `cd <dir> && <cmd>` violates the no-chaining rule above and forces an approval prompt every time.) Only `cd` in the rare case a tool genuinely cannot locate its root, and even then as its own Bash call, never a chain.
+
+## CRITICAL GIT RULES (NEVER VIOLATE)
+
+**NEVER use `git -C`.** Just run `git` directly from the cwd — it finds the repo via `.git` discovery. Do not `cd` to the repo root either (see the no-`cd` bash rule above).
+
+**NEVER push directly to main/master.** No exceptions. Not for "small changes." Not for docs. Not ever.
+
+**NEVER merge PRs.** You create PRs. The user merges them. No exceptions.
+
+**ALWAYS use this workflow:**
+1. Create a feature branch from origin/main
+2. Commit to that branch
+3. Create a PR with `gh pr create`
+4. Wait for user to merge (DO NOT run `gh pr merge`)
+
+If you catch yourself about to run `git push origin main` or `git push origin <branch>:main`, STOP. You are about to violate a critical rule. Create a PR instead.
+
+If you catch yourself about to run `gh pr merge`, STOP. Only the user merges PRs.
+
+## Worktree Usage
+
+Prefer using the current worktree for small requested fixes. Create a separate worktree only when the user asks for one,
+when the current branch/state would make the change unsafe, or when isolating a large/risky change is clearly beneficial.
+
+**NEVER leave the current worktree without explicit user approval.** Do not create, switch to, edit, commit in, or run
+git commands from another worktree unless the user has specifically asked for that worktree or approved the move. If the
+current worktree is unsafe because of dirty state, report that and ask before using a different worktree.
+
+Codex may edit code and run git commands in the current worktree, even when unrelated files are dirty, as long as it:
+- does not revert, reset, clean, or overwrite unrelated changes
+- stages only the files relevant to the requested change
+- verifies the staged diff before committing
+- creates feature branches and PRs as usual
+- does not push to main/master or merge PRs
+
+When the user says a Codex-created PR has been merged, delete the corresponding local branch and temporary worktree
+automatically, unless there is uncommitted work that would make cleanup unsafe.
+
+## PR Timing
+
+When code changes appear correct locally, create the PR promptly even if long-running builds or tests are still running.
+Opening the PR starts CI on the build machines, uploads results to the Bazel remote cache, and can speed up subsequent
+local validation. Continue monitoring any already-started local and CI validation after opening the PR.
+
+---
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Eagle0 is a multi-language gaming system combining strategic turn-based gameplay (Eagle) with tactical hex-based
+combat (Shardok). The system integrates LLM-based narrative generation and supports both human and AI players.
+
+## Architecture
+
+**Three-Tier Game System:**
+
+- **Unity Client (C#)**: Real-time strategy game client with integrated tactical combat UI
+- **Eagle (Scala)**: Strategic layer managing turn-based gameplay, diplomacy, hero progression, and province control
+- **Shardok (C++)**: Tactical layer handling real-time hex-based combat simulation with performance-critical battle
+  resolution
+
+**Communication Flow:**
+
+```
+Unity Client ↔ Eagle (gRPC streaming) ↔ Shardok (internal gRPC) 
+```
+
+**Key Entry Points:**
+
+- `/src/main/csharp/net/eagle0/clients/unity/eagle0/` - Unity C# game client
+- `/src/main/scala/net/eagle0/eagle/Main.scala` - Eagle strategic game server
+- `/src/main/cpp/net/eagle0/shardok/shardok_server_main.cpp` - Shardok tactical server
+
+**Protocol Buffer Architecture:**
+
+- Extensive use of protobuf for type-safe communication
+- Separate packages: `api/` (client-facing), `internal/` (server state), `views/` (client projections)
+- Event sourcing pattern with immutable action history
+
+## Essential Commands
+
+### Building
+
+```bash
+# Build Eagle server (Scala strategic layer)
+bazel build //src/main/scala/net/eagle0/eagle:eagle_server_deploy.jar
+
+# Build Shardok server (C++ tactical layer)
+bazel build -c opt //src/main/cpp/net/eagle0/shardok:shardok-server
+
+# Shardok server includes both AI algorithms
+bazel build //src/main/cpp/net/eagle0/shardok:shardok-server
+
+# Build Unity/C# client
+./scripts/build_protos.sh         # Protocol buffer generation for Unity
+./scripts/build_plugins.sh        # Native plugins for all platforms  
+./scripts/build_windows_plugin.sh # Windows-specific plugin build
+# Unity builds via CI: ci/github_actions/build_unity.sh
+```
+
+### Running Services
+
+```bash
+# Eagle server (port 40032)
+bazel run //src/main/scala/net/eagle0/eagle:eagle_server -- --eagle-grpc-port 40032
+# Or: ./scripts/eagle_run.sh
+
+# Shardok server  
+bazel run //src/main/cpp/net/eagle0/shardok:shardok-server --compilation_mode=opt
+# Or: ./scripts/shardok_run.sh
+```
+
+### Testing
+
+```bash
+# Run all tests
+bazel test //src/test/... //src/main/go/...
+
+# Component-specific tests
+bazel test //src/test/scala/...  # Scala Eagle tests
+bazel test //src/test/cpp/...    # C++ Shardok tests
+```
+
+### Code Generation
+
+```bash
+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
+4. **ALWAYS run the full test suite for your language changes before pushing:**
+   - For Scala changes: `bazel test //src/test/scala/...`
+   - For C++ changes: `bazel test //src/test/cpp/...`
+   - This catches exhaustive pattern match errors and other compile-time failures that single-target builds miss
+
+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
+# ALWAYS run clang-format after making any C++ or C# code changes
+clang-format -i <modified_files>
+
+# Format all C++ files in a directory:
+find . -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i
+
+# Format all C# files in a directory:
+find . -name "*.cs" | xargs clang-format -i
+```
+
+### Static Analysis
+
+```bash
+# Run clang-tidy static analysis on C++ files
+# Note: This may show some header include errors but will still analyze the main file
+bazel run @llvm_toolchain//:clang-tidy -- --checks='readability-*,bugprone-*,clang-analyzer-*' <file_path> -- -I/Users/dancrosby/CodingProjects/github/eagle0 -std=c++23
+
+# Example for AI files:
+bazel run @llvm_toolchain//:clang-tidy -- --checks='readability-*,bugprone-*,clang-analyzer-*' /Users/dancrosby/CodingProjects/github/eagle0/src/main/cpp/net/eagle0/shardok/ai/AIUnitScoreCalculator.cpp -- -I/Users/dancrosby/CodingProjects/github/eagle0 -std=c++23
+```
+
+## AI Algorithm Selection
+
+Eagle0 supports two AI algorithms for tactical combat decision-making:
+
+### Iterative Deepening AI (Default)
+
+The original minimax-based AI with sophisticated randomness handling:
+
+- **Advantages**: Proven, sophisticated randomness evaluation, comprehensive lookahead
+- **Use cases**: Production builds, scenarios requiring precise evaluation
+- **Performance**: Single-threaded, thorough evaluation
+
+### Monte Carlo Tree Search AI (MCTS)
+
+Modern MCTS-based AI with multithreading support:
+
+- **Advantages**: Multithreaded, better performance on modern CPUs, anytime algorithm
+- **Use cases**: Performance testing, scenarios requiring fast decisions
+- **Performance**: Multithreaded, adaptive depth based on time budget
+
+### Switching Between Algorithms
+
+The algorithm is selected at **runtime** via the ShardokAIClient constructor:
+
+```cpp
+// Using Iterative Deepening AI (default)
+ShardokAIClient client(playerId, isDefender, hexMap, settings);
+// OR explicitly:
+ShardokAIClient client(playerId, isDefender, hexMap, settings, AIAlgorithmType::ITERATIVE_DEEPENING);
+
+// Using MCTS AI
+ShardokAIClient client(playerId, isDefender, hexMap, settings, AIAlgorithmType::MCTS);
+```
+
+```bash
+# Build the server (includes both AI algorithms)
+bazel build //src/main/cpp/net/eagle0/shardok:shardok-server
+
+# Test both algorithms
+bazel test //src/test/cpp/net/eagle0/shardok/ai:ai_iterative_deepening_test
+bazel test //src/test/cpp/net/eagle0/shardok/ai:ai_mcts_test  # If available
+
+# Performance tests
+./scripts/ai_perf_test.sh  # Uses whatever algorithm the server is configured to use
+```
+
+Both implementations are compatible with all existing interfaces and produce the same `SearchResult` structure.
+
+**Note**: Both implementations are documented in `src/main/cpp/net/eagle0/shardok/ai/AI_SCORING_SYSTEM.md`, including
+recommendations for improving MCTS randomness handling.
+
+The AI algorithm selection is made at runtime when creating ShardokAIClient instances, allowing different AI strategies
+to be used for different players or game situations within the same server process.
+
+## Language-Specific Patterns
+
+**Scala (Strategic Layer):**
+
+- Use `EngineImpl.scala` for core game logic modifications
+- Follow event sourcing pattern - all changes through immutable actions
+- gRPC streaming for real-time client updates via `EagleServiceImpl.scala`
+- LLM integration in `/common/llm_integration/` for narrative generation
+
+**C++ (Tactical Layer):**
+
+- Performance-critical combat in `ShardokEngine.hpp/.cpp`
+- FlatBuffers for efficient serialization in `/flatbuffer/` directory
+- AI systems in `/ai/` subdirectory with pluggable strategy selectors
+- Extensive unit testing with Google Test framework
+
+**Protocol Buffers:**
+
+- Three-layer structure: `api/` (client), `internal/` (server), `views/` (projections)
+- Use `shardok_internal_interface.proto` for Eagle-Shardok communication
+- Maintain backward compatibility when modifying existing messages
+
+**C# (Unity Client):**
+
+- Located in `/src/main/csharp/net/eagle0/clients/unity/eagle0/`
+- Uses Unity 6 (6000.4.9f1) with comprehensive protobuf integration (100+ .proto files)
+- Key components: `EagleConnection.cs` (gRPC client), `EagleGameController.cs` (main game logic)
+- Real-time bidirectional streaming with server via `PersistentClientConnection.cs`
+- Strategic map UI in `Assets/Eagle/`, tactical battle UI in `Assets/Shardok/`
+- Seamless transition between strategic gameplay and hex-based tactical combat
+- **NEVER add defensive null checks on Unity Inspector fields** - these hide configuration bugs. If a field isn't
+  linked in the editor, it should throw a NullReferenceException so the problem is immediately obvious. Silently
+  skipping code when a required field is null makes bugs harder to find.
+
+**Go (Build Tools):**
+
+- Build automation and code generation utilities
+- AWS S3 integration for deployment artifacts
+
+## Testing Strategy
+
+- Comprehensive unit tests for both Scala and C++ components
+- Integration tests for Eagle-Shardok communication
+- 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:
+
+```bash
+# 1. Commit your changes to a feature branch
+git checkout -b performance-improvement-feature
+git add . && git commit -m "Implement performance improvement"
+
+# 2. Run performance tests multiple times on your branch to reduce noise
+for i in 1 2 3; do 
+    echo "=== Run $i ===" 
+    ./scripts/ai_perf_test.sh 2>&1 | grep -A 20 "AI Search Performance Summary" 
+done
+# Save or note the results
+
+# 3. Switch to main branch and run the same tests
+git checkout main
+for i in 1 2 3; do 
+    echo "=== Run $i ===" 
+    ./scripts/ai_perf_test.sh 2>&1 | grep -A 20 "AI Search Performance Summary" 
+done
+
+# 4. Compare the results between your branch and main
+# Key metrics to compare:
+# - Commands evaluated at each depth (e.g., "Depth 3: 169/523 commands")
+# - Average search depth achieved
+# - Completion rates at each depth
+```
+
+**Important notes:**
+
+- Run tests multiple times (3-5) to account for performance variance
+- Focus on commands evaluated at each depth rather than total commands
+- Commands at different depths aren't directly comparable (depth 3 is more valuable than depth 2)
+- **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/`
+**Configuration:** Game parameters in `/src/main/resources/net/eagle0/eagle/game_parameters.json`
+**Data Files:** TSV format for battalions, heroes, and other game data
+
+**NEVER modify hero names.** Do not change names in `heroes.tsv`, `generated_heroes`, or any other hero data files. The names are carefully chosen and are not to be altered.
+
+## Deployment
+
+- Bazel handles multi-language builds and dependencies
+- CI/CD via GitHub Actions with platform-specific build scripts in `/ci/github_actions/`
+- Docker containerization available via `ci/eagle_run.Dockerfile`
+- Always run "bazel run //:gazelle" after editing any BUILD.bazel files
+- *ALWAYS ALWAYS* run "bazel run gazelle" after any change that modifies a BUILD.bazel file

CLAUDE.md

@@ -1,7 +1,15 @@
 # CLAUDE.md
 
+## CRITICAL BASH RULES (NEVER VIOLATE)
+
+**NEVER chain bash commands.** Do not use `&&`, `||`, or `;` to combine commands. Each command must be a separate Bash tool call. Use parallel tool calls when commands are independent.
+
+**NEVER prefix a command with `cd`.** Run `git`, `gh`, `bazel`, etc. directly from whatever the cwd already is. The cwd is a subdirectory of the worktree; `git`/`gh` find the repo via `.git` discovery and `bazel` finds the workspace via MODULE.bazel discovery — walking up from a subdir works fine. The shell resets cwd after every command anyway, so a `cd` never persists. (And `cd <dir> && <cmd>` violates the no-chaining rule above and forces an approval prompt every time.) Only `cd` in the rare case a tool genuinely cannot locate its root, and even then as its own Bash call, never a chain.
+
 ## CRITICAL GIT RULES (NEVER VIOLATE)
 
+**NEVER use `git -C`.** Just run `git` directly from the cwd — it finds the repo via `.git` discovery. Do not `cd` to the repo root either (see the no-`cd` bash rule above).
+
 **NEVER push directly to main/master.** No exceptions. Not for "small changes." Not for docs. Not ever.
 
 **NEVER merge PRs.** You create PRs. The user merges them. No exceptions.
@@ -220,7 +228,7 @@ to be used for different players or game situations within the same server proce
 **C# (Unity Client):**
 
 - Located in `/src/main/csharp/net/eagle0/clients/unity/eagle0/`
-- Uses Unity 6 (6000.0.32f1) with comprehensive protobuf integration (100+ .proto files)
+- Uses Unity 6 (6000.4.9f1) with comprehensive protobuf integration (100+ .proto files)
 - Key components: `EagleConnection.cs` (gRPC client), `EagleGameController.cs` (main game logic)
 - Real-time bidirectional streaming with server via `PersistentClientConnection.cs`
 - Strategic map UI in `Assets/Eagle/`, tactical battle UI in `Assets/Shardok/`
@@ -344,4 +352,4 @@ dotty.tools.dotc.core.MissingType: Cannot resolve reference to type net.eagle0.e
 - CI/CD via GitHub Actions with platform-specific build scripts in `/ci/github_actions/`
 - Docker containerization available via `ci/eagle_run.Dockerfile`
 - Always run "bazel run //:gazelle" after editing any BUILD.bazel files
-- *ALWAYS ALWAYS* run "bazel run gazelle" after any change that modifies a BUILD.bazel file
+- *ALWAYS ALWAYS* run "bazel run gazelle" after any change that modifies a BUILD.bazel file

MODULE.bazel

@@ -149,38 +149,54 @@ use_repo(crate, "map_generator_crates")
 #
 # Platform Support - Apple/iOS
 #
-# Note: rules_apple is NOT included in the main workspace due to rules_swift
-# version conflicts with grpc. SparklePlugin (which needs rules_apple) is built
-# in a separate workspace at sparkle_workspace/ to isolate the conflict.
-#
 
 bazel_dep(name = "apple_support", version = "1.24.1", repo_name = "build_bazel_apple_support")
-
-# rules_swift is a transitive dep of grpc and flatbuffers with conflicting versions:
-# - grpc 1.76.0.bcr.1 requires rules_swift 3.x (compatibility level 3)
-# - flatbuffers requires rules_swift 2.x (compatibility level 2)
-# We don't use Swift directly, but we need to force a single version.
-# Force 3.x since grpc is more complex and harder to downgrade.
-single_version_override(
-    module_name = "rules_swift",
-    version = "3.1.2",
-)
+bazel_dep(name = "rules_apple", version = "4.3.3", repo_name = "build_bazel_rules_apple")
 
 # Register Apple CC toolchain for Objective-C compilation
 apple_cc_configure = use_extension(
     "@build_bazel_apple_support//crosstool:setup.bzl",
     "apple_cc_configure_extension",
 )
-use_repo(apple_cc_configure, "local_config_apple_cc")
+use_repo(apple_cc_configure, "local_config_apple_cc", "local_config_apple_cc_toolchains")
 
 #
 # Protocol Buffers & RPC
 #
 
 bazel_dep(name = "protobuf", version = "33.5", repo_name = "com_google_protobuf")
+
+# Use pre-built protoc binaries instead of compiling from source.
+# See: https://protobuf.dev/reference/cpp/cpp-generated/#invocation
+prebuilt_protoc = use_extension("@com_google_protobuf//bazel/private:prebuilt_protoc_extension.bzl", "protoc")
+use_repo(
+    prebuilt_protoc,
+    "prebuilt_protoc.linux_aarch_64",
+    "prebuilt_protoc.linux_ppcle_64",
+    "prebuilt_protoc.linux_s390_64",
+    "prebuilt_protoc.linux_x86_32",
+    "prebuilt_protoc.linux_x86_64",
+    "prebuilt_protoc.osx_aarch_64",
+    "prebuilt_protoc.osx_x86_64",
+    "prebuilt_protoc.win32",
+    "prebuilt_protoc.win64",
+)
+
 bazel_dep(name = "rules_proto", version = "7.1.0")
 bazel_dep(name = "rules_cc", version = "0.2.14")
-bazel_dep(name = "grpc", version = "1.74.1")
+bazel_dep(name = "grpc", version = "1.78.0")
+
+# Patch grpc 1.78.0 to fix rules_python incompatibility: grpc requests Python
+# 3.14.0b2 toolchain but rules_python >= 1.6.0 removed it in favor of 3.14.
+# Upstream fix: https://github.com/grpc/grpc/commit/459279b
+# TODO: Remove this override once a fixed grpc version is published to BCR.
+single_version_override(
+    module_name = "grpc",
+    patch_strip = 1,
+    patches = ["//third_party/patches:grpc_fix_python_version.patch"],
+    version = "1.78.0",
+)
+
 bazel_dep(name = "grpc-java", version = "1.78.0")
 bazel_dep(name = "rules_proto_grpc_csharp", version = "5.8.0")
 bazel_dep(name = "flatbuffers", version = "25.12.19")
@@ -279,6 +295,9 @@ maven.install(
         # Testing
         "org.scalamock:scalamock_3:7.4.1",
 
+        # Developer tools
+        "org.scalameta:scalafmt-cli_2.13:3.9.9",
+
         # AWS SDK
         "software.amazon.awssdk:s3-transfer-manager:%s" % AWS_SDK_VERSION,
         "software.amazon.awssdk:s3:%s" % AWS_SDK_VERSION,
@@ -321,6 +340,15 @@ maven.install(
     ],
 )
 
+# json4s' Scala 3 reflection path can load scala.quoted.staging at runtime, but
+# its Maven metadata does not bring the staging jar transitively.
+maven.artifact(
+    artifact = "scala3-staging_3",
+    exclusions = ["org.scala-lang:scala3-compiler_3"],
+    group = "org.scala-lang",
+    version = "3.3.6",
+)
+
 # Force specific versions for dependencies with conflicts between grpc-java and protobuf
 maven.artifact(
     artifact = "gson",
@@ -384,8 +412,16 @@ http_archive(
     ],
 )
 
-# Note: Sparkle framework is defined in sparkle_workspace/MODULE.bazel
-# (not in main workspace due to rules_swift version conflicts)
+# Sparkle framework for macOS auto-updates
+SPARKLE_VERSION = "2.6.4"
+
+http_archive(
+    name = "sparkle",
+    build_file = "//src/main/objc/net/eagle0/clients/unity/sparkle/external:BUILD.sparkle",
+    sha256 = "50612a06038abc931f16011d7903b8326a362c1074dabccb718404ce8e585f0b",
+    strip_prefix = "",
+    url = "https://github.com/sparkle-project/Sparkle/releases/download/%s/Sparkle-%s.tar.xz" % (SPARKLE_VERSION, SPARKLE_VERSION),
+)
 
 # Busybox static binary for Docker health checks (provides nc, wget, etc.)
 # Primary: DigitalOcean Spaces (public, reliable)
@@ -475,6 +511,11 @@ register_toolchains(
     "@rules_scala//testing:scalatest_toolchain",
 )
 
+# Apple CC toolchain for Objective-C compilation (SparklePlugin).
+# Registered before LLVM so it has higher priority; Apple constraint matching
+# ensures it's only used for Apple-platform targets (objc_library, macos_bundle).
+register_toolchains("@local_config_apple_cc_toolchains//:all")
+
 # Set dev_dependency so we can turn this off for swift MacOS builds
 register_toolchains(
     "@llvm_toolchain//:all",

MODULE.bazel.lock

@@ -4,15 +4,12 @@
     "https://bcr.bazel.build/bazel_registry.json": "8a28e4aff06ee60aed2a8c281907fb8bcbf3b753c91fb5a5c57da3215d5b3497",
     "https://bcr.bazel.build/modules/abseil-cpp/20210324.2/MODULE.bazel": "7cd0312e064fde87c8d1cd79ba06c876bd23630c83466e9500321be55c96ace2",
     "https://bcr.bazel.build/modules/abseil-cpp/20211102.0/MODULE.bazel": "70390338f7a5106231d20620712f7cccb659cd0e9d073d1991c038eb9fc57589",
-    "https://bcr.bazel.build/modules/abseil-cpp/20220623.1/MODULE.bazel": "73ae41b6818d423a11fd79d95aedef1258f304448193d4db4ff90e5e7a0f076c",
     "https://bcr.bazel.build/modules/abseil-cpp/20230125.1/MODULE.bazel": "89047429cb0207707b2dface14ba7f8df85273d484c2572755be4bab7ce9c3a0",
     "https://bcr.bazel.build/modules/abseil-cpp/20230802.0.bcr.1/MODULE.bazel": "1c8cec495288dccd14fdae6e3f95f772c1c91857047a098fad772034264cc8cb",
     "https://bcr.bazel.build/modules/abseil-cpp/20230802.0/MODULE.bazel": "d253ae36a8bd9ee3c5955384096ccb6baf16a1b1e93e858370da0a3b94f77c16",
     "https://bcr.bazel.build/modules/abseil-cpp/20230802.1/MODULE.bazel": "fa92e2eb41a04df73cdabeec37107316f7e5272650f81d6cc096418fe647b915",
-    "https://bcr.bazel.build/modules/abseil-cpp/20240116.0/MODULE.bazel": "98dc378d64c12a4e4741ad3362f87fb737ee6a0886b2d90c3cdbb4d93ea3e0bf",
     "https://bcr.bazel.build/modules/abseil-cpp/20240116.1/MODULE.bazel": "37bcdb4440fbb61df6a1c296ae01b327f19e9bb521f9b8e26ec854b6f97309ed",
     "https://bcr.bazel.build/modules/abseil-cpp/20240116.2/MODULE.bazel": "73939767a4686cd9a520d16af5ab440071ed75cec1a876bf2fcfaf1f71987a16",
-    "https://bcr.bazel.build/modules/abseil-cpp/20240722.0/MODULE.bazel": "88668a07647adbdc14cb3a7cd116fb23c9dda37a90a1681590b6c9d8339a5b84",
     "https://bcr.bazel.build/modules/abseil-cpp/20250127.0/MODULE.bazel": "d1086e248cda6576862b4b3fe9ad76a214e08c189af5b42557a6e1888812c5d5",
     "https://bcr.bazel.build/modules/abseil-cpp/20250127.1/MODULE.bazel": "c4a89e7ceb9bf1e25cf84a9f830ff6b817b72874088bf5141b314726e46a57c1",
     "https://bcr.bazel.build/modules/abseil-cpp/20250512.0/MODULE.bazel": "c4d02dd22cd87458516655a45512060246ee2a4732f1fbe948a5bd9eb614e626",
@@ -25,7 +22,7 @@
     "https://bcr.bazel.build/modules/apple_support/1.13.0/MODULE.bazel": "7c8cdea7e031b7f9f67f0b497adf6d2c6a2675e9304ca93a9af6ed84eef5a524",
     "https://bcr.bazel.build/modules/apple_support/1.15.1/MODULE.bazel": "a0556fefca0b1bb2de8567b8827518f94db6a6e7e7d632b4c48dc5f865bc7c85",
     "https://bcr.bazel.build/modules/apple_support/1.17.1/MODULE.bazel": "655c922ab1209978a94ef6ca7d9d43e940cd97d9c172fb55f94d91ac53f8610b",
-    "https://bcr.bazel.build/modules/apple_support/1.21.0/MODULE.bazel": "ac1824ed5edf17dee2fdd4927ada30c9f8c3b520be1b5fd02a5da15bc10bff3e",
+    "https://bcr.bazel.build/modules/apple_support/1.21.1/MODULE.bazel": "5809fa3efab15d1f3c3c635af6974044bac8a4919c62238cce06acee8a8c11f1",
     "https://bcr.bazel.build/modules/apple_support/1.23.0/MODULE.bazel": "317d47e3f65b580e7fb4221c160797fda48e32f07d2dfff63d754ef2316dcd25",
     "https://bcr.bazel.build/modules/apple_support/1.23.1/MODULE.bazel": "53763fed456a968cf919b3240427cf3a9d5481ec5466abc9d5dc51bc70087442",
     "https://bcr.bazel.build/modules/apple_support/1.24.1/MODULE.bazel": "f46e8ddad60aef170ee92b2f3d00ef66c147ceafea68b6877cb45bd91737f5f8",
@@ -67,6 +64,7 @@
     "https://bcr.bazel.build/modules/bazel_features/1.23.0/MODULE.bazel": "fd1ac84bc4e97a5a0816b7fd7d4d4f6d837b0047cf4cbd81652d616af3a6591a",
     "https://bcr.bazel.build/modules/bazel_features/1.27.0/MODULE.bazel": "621eeee06c4458a9121d1f104efb80f39d34deff4984e778359c60eaf1a8cb65",
     "https://bcr.bazel.build/modules/bazel_features/1.28.0/MODULE.bazel": "4b4200e6cbf8fa335b2c3f43e1d6ef3e240319c33d43d60cc0fbd4b87ece299d",
+    "https://bcr.bazel.build/modules/bazel_features/1.3.0/MODULE.bazel": "cdcafe83ec318cda34e02948e81d790aab8df7a929cec6f6969f13a489ccecd9",
     "https://bcr.bazel.build/modules/bazel_features/1.30.0/MODULE.bazel": "a14b62d05969a293b80257e72e597c2da7f717e1e69fa8b339703ed6731bec87",
     "https://bcr.bazel.build/modules/bazel_features/1.32.0/MODULE.bazel": "095d67022a58cb20f7e20e1aefecfa65257a222c18a938e2914fd257b5f1ccdc",
     "https://bcr.bazel.build/modules/bazel_features/1.33.0/MODULE.bazel": "8b8dc9d2a4c88609409c3191165bccec0e4cb044cd7a72ccbe826583303459f6",
@@ -102,7 +100,6 @@
     "https://bcr.bazel.build/modules/bazel_worker_api/0.0.4/MODULE.bazel": "460aa12d01231a80cce03c548287b433b321d205b0028ae596728c35e5ee442e",
     "https://bcr.bazel.build/modules/bazel_worker_java/0.0.4/MODULE.bazel": "82494a01018bb7ef06d4a17ec4cd7a758721f10eb8b6c820a818e70d669500db",
     "https://bcr.bazel.build/modules/bazel_worker_java/0.0.4/source.json": "a2d30458fd86cf022c2b6331e652526fa08e17573b2f5034a9dbcacdf9c2583c",
-    "https://bcr.bazel.build/modules/boringssl/0.0.0-20211025-d4f1ab9/MODULE.bazel": "6ee6353f8b1a701fe2178e1d925034294971350b6d3ac37e67e5a7d463267834",
     "https://bcr.bazel.build/modules/boringssl/0.0.0-20230215-5c22014/MODULE.bazel": "4b03dc0d04375fa0271174badcd202ed249870c8e895b26664fd7298abea7282",
     "https://bcr.bazel.build/modules/boringssl/0.0.0-20240530-2db0eb3/MODULE.bazel": "d0405b762c5e87cd445b7015f2b8da5400ef9a8dbca0bfefa6c1cea79d528a97",
     "https://bcr.bazel.build/modules/boringssl/0.20240913.0/MODULE.bazel": "fcaa7503a5213290831a91ed1eb538551cf11ac0bc3a6ad92d0fef92c5bd25fb",
@@ -110,14 +107,12 @@
     "https://bcr.bazel.build/modules/boringssl/0.20241024.0/source.json": "d843092e682b84188c043ac742965d7f96e04c846c7e338187e03238674909a9",
     "https://bcr.bazel.build/modules/buildozer/7.1.2/MODULE.bazel": "2e8dd40ede9c454042645fd8d8d0cd1527966aa5c919de86661e62953cd73d84",
     "https://bcr.bazel.build/modules/buildozer/7.1.2/source.json": "c9028a501d2db85793a6996205c8de120944f50a0d570438fcae0457a5f9d1f8",
-    "https://bcr.bazel.build/modules/c-ares/1.15.0/MODULE.bazel": "ba0a78360fdc83f02f437a9e7df0532ad1fbaa59b722f6e715c11effebaa0166",
     "https://bcr.bazel.build/modules/c-ares/1.19.1/MODULE.bazel": "73bca21720772370ff91cc8e88bbbaf14897720c6473e87c1ddc0f848284c313",
     "https://bcr.bazel.build/modules/c-ares/1.19.1/source.json": "56bfa95b01e4e0012e90eaa9f1bab823c48c3af4454286b889b9cc74f5098da1",
     "https://bcr.bazel.build/modules/cel-spec/0.15.0/MODULE.bazel": "e1eed53d233acbdcf024b4b0bc1528116d92c29713251b5154078ab1348cb600",
     "https://bcr.bazel.build/modules/cel-spec/0.15.0/source.json": "ab7dccdf21ea2261c0f809b5a5221a4d7f8b580309f285fdf1444baaca75d44a",
     "https://bcr.bazel.build/modules/civetweb/1.16/MODULE.bazel": "46a38f9daeb57392e3827fce7d40926be0c802bd23cdd6bfd3a96c804de42fae",
     "https://bcr.bazel.build/modules/civetweb/1.16/source.json": "ba8b9585adb8355cb51b999d57172fd05e7a762c56b8d4bac6db42c99de3beb7",
-    "https://bcr.bazel.build/modules/curl/8.4.0/MODULE.bazel": "0bc250aa1cb69590049383df7a9537c809591fcf876c620f5f097c58fdc9bc10",
     "https://bcr.bazel.build/modules/curl/8.7.1/MODULE.bazel": "088221c35a2939c555e6e47cb31a81c15f8b59f4daa8009b1e9271a502d33485",
     "https://bcr.bazel.build/modules/curl/8.8.0/MODULE.bazel": "7da3b3e79b0b4ee8f8c95d640bc6ad7b430ce66ef6e9c9d2bc29b3b5ef85f6fe",
     "https://bcr.bazel.build/modules/curl/8.8.0/source.json": "d7d138b6878cf38891692fee0649ace35357fd549b425614d571786f054374d4",
@@ -142,36 +137,33 @@
     "https://bcr.bazel.build/modules/gazelle/0.47.0/source.json": "aeb2e5df14b7fb298625d75d08b9c65bdb0b56014c5eb89da9e5dd0572280ae6",
     "https://bcr.bazel.build/modules/google_benchmark/1.8.2/MODULE.bazel": "a70cf1bba851000ba93b58ae2f6d76490a9feb74192e57ab8e8ff13c34ec50cb",
     "https://bcr.bazel.build/modules/google_benchmark/1.8.4/MODULE.bazel": "c6d54a11dcf64ee63545f42561eda3fd94c1b5f5ebe1357011de63ae33739d5e",
-    "https://bcr.bazel.build/modules/google_benchmark/1.8.5/MODULE.bazel": "9ba9b31b984022828a950e3300410977eda2e35df35584c6b0b2d0c2e52766b7",
-    "https://bcr.bazel.build/modules/google_benchmark/1.8.5/source.json": "2c9c685f9b496f125b9e3a9c696c549d1ed2f33b75830a2fb6ac94fab23c0398",
+    "https://bcr.bazel.build/modules/google_benchmark/1.8.4/source.json": "84590f7bc5a1fd99e1ef274ee16bb41c214f705e62847b42e705010dfa81fe53",
+    "https://bcr.bazel.build/modules/googleapis-cc/1.0.0/MODULE.bazel": "cf01757e7590c56140a4b81638ff2b3e7074769e6271720bbf738fcda25b6fc2",
+    "https://bcr.bazel.build/modules/googleapis-cc/1.0.0/source.json": "ab0e3a2ee9968a8848f59872fbbfa3e1f768597d71d2229e6caa319d357967c7",
+    "https://bcr.bazel.build/modules/googleapis-grpc-cc/1.0.0/MODULE.bazel": "3553358a9d8d96026c9e28d9fb6c268574950d0be7fa9b4c0aeaf3c37c73f2d3",
+    "https://bcr.bazel.build/modules/googleapis-grpc-cc/1.0.0/source.json": "fa7b79043b3c82bf74f1f2fa45af289e19b247375868d0752db2c114a1c7366c",
+    "https://bcr.bazel.build/modules/googleapis-python/1.0.0/MODULE.bazel": "0ccd1614a914fb524b3ac267f9c97f9a5cd5412b027f0176b81a725882ec42ff",
+    "https://bcr.bazel.build/modules/googleapis-python/1.0.0/source.json": "24364f075ec5e6d5e0cfc5d651bd833b119e0cea1a45d51330c93461e3586e42",
+    "https://bcr.bazel.build/modules/googleapis-rules-registry/1.0.0/MODULE.bazel": "97c6a4d413b373d4cc97065da3de1b2166e22cbbb5f4cc9f05760bfa83619e24",
+    "https://bcr.bazel.build/modules/googleapis-rules-registry/1.0.0/source.json": "cf611c836a60e98e2e2ab2de8004f119e9f06878dcf4ea2d95a437b1b7a89fe9",
     "https://bcr.bazel.build/modules/googleapis/0.0.0-20240326-1c8d509c5/MODULE.bazel": "a4b7e46393c1cdcc5a00e6f85524467c48c565256b22b5fae20f84ab4a999a68",
     "https://bcr.bazel.build/modules/googleapis/0.0.0-20240819-fe8ba054a/MODULE.bazel": "117b7c7be7327ed5d6c482274533f2dbd78631313f607094d4625c28203cacdf",
-    "https://bcr.bazel.build/modules/googleapis/0.0.0-20240819-fe8ba054a/source.json": "b31fc7eb283a83f71d2e5bfc3d1c562d2994198fa1278409fbe8caec3afc1d3e",
+    "https://bcr.bazel.build/modules/googleapis/0.0.0-20241220-5e258e33.bcr.1/MODULE.bazel": "ee6c30f82ecd476e61f019fb1151aaab380ea419958ff274ef2f0efca7969f5c",
+    "https://bcr.bazel.build/modules/googleapis/0.0.0-20241220-5e258e33.bcr.1/source.json": "d6f66e3d95ec52821e994015e83ed194f8888c655068e192659e55a8987dfe77",
     "https://bcr.bazel.build/modules/googletest/1.11.0/MODULE.bazel": "3a83f095183f66345ca86aa13c58b59f9f94a2f81999c093d4eeaa2d262d12f4",
     "https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/MODULE.bazel": "22c31a561553727960057361aa33bf20fb2e98584bc4fec007906e27053f80c6",
     "https://bcr.bazel.build/modules/googletest/1.14.0/MODULE.bazel": "cfbcbf3e6eac06ef9d85900f64424708cc08687d1b527f0ef65aa7517af8118f",
     "https://bcr.bazel.build/modules/googletest/1.15.2/MODULE.bazel": "6de1edc1d26cafb0ea1a6ab3f4d4192d91a312fd2d360b63adaa213cd00b2108",
-    "https://bcr.bazel.build/modules/googletest/1.16.0/MODULE.bazel": "a175623c69e94fca4ca7acbc12031e637b0c489318cd4805606981d4d7adb34a",
     "https://bcr.bazel.build/modules/googletest/1.17.0/MODULE.bazel": "dbec758171594a705933a29fcf69293d2468c49ec1f2ebca65c36f504d72df46",
     "https://bcr.bazel.build/modules/googletest/1.17.0/source.json": "38e4454b25fc30f15439c0378e57909ab1fd0a443158aa35aec685da727cd713",
     "https://bcr.bazel.build/modules/grpc-java/1.62.2/MODULE.bazel": "99b8771e8c7cacb130170fed2a10c9e8fed26334a93e73b42d2953250885a158",
     "https://bcr.bazel.build/modules/grpc-java/1.66.0/MODULE.bazel": "86ff26209fac846adb89db11f3714b3dc0090fb2fb81575673cc74880cda4e7e",
-    "https://bcr.bazel.build/modules/grpc-java/1.69.0/MODULE.bazel": "53887af6a00b3b406d70175d3d07e84ea9362016ff55ea90b9185f0227bfaf98",
     "https://bcr.bazel.build/modules/grpc-java/1.78.0/MODULE.bazel": "48f790fbb95625245295df1283e0dba344a4e30b4a9a9cefbabfa92bd84f3691",
     "https://bcr.bazel.build/modules/grpc-java/1.78.0/source.json": "36c3a83c5ddeb864d7a4b97801456c464077f80a8216354ac1a71f7ce8699771",
     "https://bcr.bazel.build/modules/grpc-proto/0.0.0-20240627-ec30f58/MODULE.bazel": "88de79051e668a04726e9ea94a481ec6f1692086735fd6f488ab908b3b909238",
     "https://bcr.bazel.build/modules/grpc-proto/0.0.0-20240627-ec30f58/source.json": "5035d379c61042930244ab59e750106d893ec440add92ec0df6a0098ca7f131d",
-    "https://bcr.bazel.build/modules/grpc/1.41.0/MODULE.bazel": "5bcbfc2b274dabea628f0649dc50c90cf36543b1cfc31624832538644ad1aae8",
-    "https://bcr.bazel.build/modules/grpc/1.56.3.bcr.1/MODULE.bazel": "cd5b1eb276b806ec5ab85032921f24acc51735a69ace781be586880af20ab33f",
-    "https://bcr.bazel.build/modules/grpc/1.62.1/MODULE.bazel": "2998211594b8a79a6b459c4e797cfa19f0fb8b3be3149760ec7b8c99abfd426f",
-    "https://bcr.bazel.build/modules/grpc/1.63.1.bcr.1/MODULE.bazel": "d7b9fef03bd175e6825237b521b18a3c29f1ac15f8aa52c8a1a0f3bd8f33d54b",
-    "https://bcr.bazel.build/modules/grpc/1.66.0.bcr.2/MODULE.bazel": "0fa2b0fd028ce354febf0fe90f1ed8fecfbfc33118cddd95ac0418cc283333a0",
-    "https://bcr.bazel.build/modules/grpc/1.66.0.bcr.3/MODULE.bazel": "f6047e89faf488f5e3e65cb2594c6f5e86992abec7487163ff6b623526e543b0",
-    "https://bcr.bazel.build/modules/grpc/1.69.0/MODULE.bazel": "4e26e05c9e1ef291ccbc96aad8e457b1b8abedbc141623831629da2f8168eef6",
-    "https://bcr.bazel.build/modules/grpc/1.70.1/MODULE.bazel": "b800cd8e3e7555c1e61cba2e02d3a2fcf0e91f66e800db286d965d3b7a6a721a",
-    "https://bcr.bazel.build/modules/grpc/1.71.0/MODULE.bazel": "7fcab2c05530373f1a442c362b17740dd0c75b6a2a975eec8f5bf4c70a37928a",
-    "https://bcr.bazel.build/modules/grpc/1.74.1/MODULE.bazel": "09523be10ba2bfd999683671d0f8f22fb5b20ec77ad89b05ef58ff19a1b65c82",
-    "https://bcr.bazel.build/modules/grpc/1.74.1/source.json": "8508bcf9bae1b7c647a594e13461ce192240fcdbb409c2741444322d47d01f98",
+    "https://bcr.bazel.build/modules/grpc/1.78.0/MODULE.bazel": "6a72f0b2fe950342fe63b231c76197df6d117a8ea1ac338dac40b053020f586a",
+    "https://bcr.bazel.build/modules/grpc/1.78.0/source.json": "c988abfe519ef5ace8cd27c80c0a66e68e501e5902b623722fcbf6694b355693",
     "https://bcr.bazel.build/modules/helly25_bzl/0.3.1/MODULE.bazel": "3a4be20f6fc13be32ad44643b8252ef5af09eee936f1d943cd4fd7867fa92826",
     "https://bcr.bazel.build/modules/helly25_bzl/0.3.1/source.json": "b129ab1828492de2c163785bbeb4065c166de52d932524b4317beb5b7f917994",
     "https://bcr.bazel.build/modules/jq.bzl/0.1.0/MODULE.bazel": "2ce69b1af49952cd4121a9c3055faa679e748ce774c7f1fda9657f936cae902f",
@@ -188,18 +180,13 @@
     "https://bcr.bazel.build/modules/nlohmann_json/3.6.1/MODULE.bazel": "6f7b417dcc794d9add9e556673ad25cb3ba835224290f4f848f8e2db1e1fca74",
     "https://bcr.bazel.build/modules/opencensus-cpp/0.0.0-20230502-50eb5de.bcr.2/MODULE.bazel": "cc18734138dd18c912c6ce2a59186db28f85d8058c99c9f21b46ca3e0aba0ebe",
     "https://bcr.bazel.build/modules/opencensus-cpp/0.0.0-20230502-50eb5de.bcr.2/source.json": "7c135f9d42bb3b045669c3c6ab3bb3c208e00b46aca4422eea64c29811a5b240",
-    "https://bcr.bazel.build/modules/opencensus-cpp/0.0.0-20230502-50eb5de/MODULE.bazel": "02201d2921dadb4ec90c4980eca4b2a02904eddcf6fa02f3da7594fb7b0d821c",
     "https://bcr.bazel.build/modules/opencensus-proto/0.4.1.bcr.2/MODULE.bazel": "789706a714855f92c5c8cfcf1ef32bbb64dcd3b7c9066756ad7986ec59709d29",
     "https://bcr.bazel.build/modules/opencensus-proto/0.4.1.bcr.2/source.json": "aadf3f53e08b72376506b7c4ea3d167010c9efb160d7d6e1e304ed646bac1b36",
     "https://bcr.bazel.build/modules/opencensus-proto/0.4.1/MODULE.bazel": "4a2e8b4d0b544002502474d611a5a183aa282251e14f6a01afe841c0c1b10372",
     "https://bcr.bazel.build/modules/openssl/3.3.1.bcr.1/MODULE.bazel": "49c0c07e8fb87b480bccb842cfee1b32617f11dac590f732573c69058699a3d1",
     "https://bcr.bazel.build/modules/openssl/3.3.1.bcr.1/source.json": "0c0872e048bbea052a9c541fb47019481a19201ba5555a71d762ad591bf94e1f",
-    "https://bcr.bazel.build/modules/opentelemetry-cpp/1.14.2/MODULE.bazel": "089a5613c2a159c7dfde098dabfc61e966889c7d6a81a98422a84c51535ed17d",
-    "https://bcr.bazel.build/modules/opentelemetry-cpp/1.16.0/MODULE.bazel": "b7379a140f538cea3f749179a2d481ed81942cc6f7b05a6113723eb34ac3b3e7",
     "https://bcr.bazel.build/modules/opentelemetry-cpp/1.19.0/MODULE.bazel": "3455326c08b28415648a3d60d8e3c811847ebdbe64474f75b25878f25585aea1",
     "https://bcr.bazel.build/modules/opentelemetry-cpp/1.19.0/source.json": "4e48137e4c3ecb99401ff99876df8fa330598d7da051869bec643446e8a8ff95",
-    "https://bcr.bazel.build/modules/opentelemetry-proto/1.1.0/MODULE.bazel": "a49f406e99bf05ab43ed4f5b3322fbd33adfd484b6546948929d1316299b68bf",
-    "https://bcr.bazel.build/modules/opentelemetry-proto/1.3.1/MODULE.bazel": "0141a50e989576ee064c11ce8dd5ec89993525bd9f9a09c5618e4dacc8df9352",
     "https://bcr.bazel.build/modules/opentelemetry-proto/1.4.0.bcr.1/MODULE.bazel": "5ceaf25e11170d22eded4c8032728b4a3f273765fccda32f9e94f463755c4167",
     "https://bcr.bazel.build/modules/opentelemetry-proto/1.5.0/MODULE.bazel": "7543d91a53b98e7b5b37c5a0865b93bff12c1ee022b1e322cd236b968894b030",
     "https://bcr.bazel.build/modules/opentelemetry-proto/1.5.0/source.json": "046b721ce203e88cdaad44d7dd17a86b7200eab9388b663b234e72e13ff7b143",
@@ -219,7 +206,6 @@
     "https://bcr.bazel.build/modules/platforms/0.0.9/MODULE.bazel": "4a87a60c927b56ddd67db50c89acaa62f4ce2a1d2149ccb63ffd871d5ce29ebc",
     "https://bcr.bazel.build/modules/platforms/1.0.0/MODULE.bazel": "f05feb42b48f1b3c225e4ccf351f367be0371411a803198ec34a389fb22aa580",
     "https://bcr.bazel.build/modules/platforms/1.0.0/source.json": "f4ff1fd412e0246fd38c82328eb209130ead81d62dcd5a9e40910f867f733d96",
-    "https://bcr.bazel.build/modules/prometheus-cpp/1.2.4/MODULE.bazel": "0fbe5dcff66311947a3f6b86ebc6a6d9328e31a28413ca864debc4a043f371e5",
     "https://bcr.bazel.build/modules/prometheus-cpp/1.3.0.bcr.1/MODULE.bazel": "116ad46e97c1d2aeb020fe2899a342a7e703574ce7c0faf7e4810f938c974a9a",
     "https://bcr.bazel.build/modules/prometheus-cpp/1.3.0.bcr.1/source.json": "e813cce2d450708cfcb26e309c5172583a7440776edf354e83e6788c768e5cca",
     "https://bcr.bazel.build/modules/prometheus-cpp/1.3.0/MODULE.bazel": "ce82e086bbc0b60267e970f6a54b2ca6d0f22d3eb6633e00e2cc2899c700f3d8",
@@ -227,8 +213,6 @@
     "https://bcr.bazel.build/modules/protobuf/23.1/MODULE.bazel": "88b393b3eb4101d18129e5db51847cd40a5517a53e81216144a8c32dfeeca52a",
     "https://bcr.bazel.build/modules/protobuf/24.4/MODULE.bazel": "7bc7ce5f2abf36b3b7b7c8218d3acdebb9426aeb35c2257c96445756f970eb12",
     "https://bcr.bazel.build/modules/protobuf/25.6/MODULE.bazel": "fc0ae073b47c7ede88b825ff79e64f1c058967c7a87a86cdf4abecd9e0516625",
-    "https://bcr.bazel.build/modules/protobuf/26.0.bcr.1/MODULE.bazel": "8f04d38c2da40a3715ff6bdce4d32c5981e6432557571482d43a62c31a24c2cf",
-    "https://bcr.bazel.build/modules/protobuf/26.0.bcr.2/MODULE.bazel": "62e0b84ca727bdeb55a6fe1ef180e6b191bbe548a58305ea1426c158067be534",
     "https://bcr.bazel.build/modules/protobuf/26.0/MODULE.bazel": "8402da964092af40097f4a205eec2a33fd4a7748dc43632b7d1629bfd9a2b856",
     "https://bcr.bazel.build/modules/protobuf/27.0-rc2/MODULE.bazel": "b2b0dbafd57b6bec0ca9b251da02e628c357dab53a097570aa7d79d020f107cf",
     "https://bcr.bazel.build/modules/protobuf/27.0/MODULE.bazel": "7873b60be88844a0a1d8f80b9d5d20cfbd8495a689b8763e76c6372998d3f64c",
@@ -252,7 +236,6 @@
     "https://bcr.bazel.build/modules/protoc-gen-validate/1.0.4/MODULE.bazel": "b8913c154b16177990f6126d2d2477d187f9ddc568e95ee3e2d50fc65d2c494a",
     "https://bcr.bazel.build/modules/protoc-gen-validate/1.2.1.bcr.1/MODULE.bazel": "4bf09676b62fa587ae07e073420a76ec8766dcce7545e5f8c68cfa8e484b5120",
     "https://bcr.bazel.build/modules/protoc-gen-validate/1.2.1.bcr.1/source.json": "c19071ebc4b53b5f1cfab9c66eefaf6e4179eb8a998970d07b1077687e777f29",
-    "https://bcr.bazel.build/modules/protoc-gen-validate/1.2.1/MODULE.bazel": "52b51f50533ec4fbd5d613cd093773f979ac2e035d954e02ca11de383f502505",
     "https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/MODULE.bazel": "88af1c246226d87e65be78ed49ecd1e6f5e98648558c14ce99176da041dc378e",
     "https://bcr.bazel.build/modules/pybind11_bazel/2.12.0/MODULE.bazel": "e6f4c20442eaa7c90d7190d8dc539d0ab422f95c65a57cc59562170c58ae3d34",
     "https://bcr.bazel.build/modules/pybind11_bazel/2.12.0/source.json": "6900fdc8a9e95866b8c0d4ad4aba4d4236317b5c1cd04c502df3f0d33afed680",
@@ -269,8 +252,8 @@
     "https://bcr.bazel.build/modules/rules_android/0.6.6/source.json": "a9d8dc2d5a102dc03269a94acc886a4cab82cdcb9ccbc77b0f665d6d17a6ae09",
     "https://bcr.bazel.build/modules/rules_apple/3.13.0/MODULE.bazel": "b4559a2c6281ca3165275bb36c1f0ac74666632adc5bdb680e366de7ce845f43",
     "https://bcr.bazel.build/modules/rules_apple/3.16.0/MODULE.bazel": "0d1caf0b8375942ce98ea944be754a18874041e4e0459401d925577624d3a54a",
-    "https://bcr.bazel.build/modules/rules_apple/3.16.0/source.json": "d8b5fe461272018cc07cfafce11fe369c7525330804c37eec5a82f84cd475366",
-    "https://bcr.bazel.build/modules/rules_apple/3.5.1/MODULE.bazel": "3d1bbf65ad3692003d36d8a29eff54d4e5c1c5f4bfb60f79e28646a924d9101c",
+    "https://bcr.bazel.build/modules/rules_apple/4.3.3/MODULE.bazel": "c5c2c4adeeac5f3f2f9b7f16abfa8be7ffefa596171d0d92bed4cae9ade0a498",
+    "https://bcr.bazel.build/modules/rules_apple/4.3.3/source.json": "3cb1d69c8243ffcc42ecbf84ae8b9cccd7b1e2f091b0aee5a3e9c9a45267f312",
     "https://bcr.bazel.build/modules/rules_buf/0.1.1/MODULE.bazel": "6189aec18a4f7caff599ad41b851ab7645d4f1e114aa6431acf9b0666eb92162",
     "https://bcr.bazel.build/modules/rules_cc/0.0.1/MODULE.bazel": "cb2aa0747f84c6c3a78dad4e2049c154f08ab9d166b1273835a8174940365647",
     "https://bcr.bazel.build/modules/rules_cc/0.0.10/MODULE.bazel": "ec1705118f7eaedd6e118508d3d26deba2a4e76476ada7e0e3965211be012002",
@@ -313,7 +296,6 @@
     "https://bcr.bazel.build/modules/rules_go/0.59.0/MODULE.bazel": "b7e43e7414a3139a7547d1b4909b29085fbe5182b6c58cbe1ed4c6272815aeae",
     "https://bcr.bazel.build/modules/rules_go/0.59.0/source.json": "1df17bb7865cfc029492c30163cee891d0dd8658ea0d5bfdf252c4b6db5c1ef6",
     "https://bcr.bazel.build/modules/rules_java/4.0.0/MODULE.bazel": "5a78a7ae82cd1a33cef56dc578c7d2a46ed0dca12643ee45edbb8417899e6f74",
-    "https://bcr.bazel.build/modules/rules_java/5.1.0/MODULE.bazel": "324b6478b0343a3ce7a9add8586ad75d24076d6d43d2f622990b9c1cfd8a1b15",
     "https://bcr.bazel.build/modules/rules_java/5.3.5/MODULE.bazel": "a4ec4f2db570171e3e5eb753276ee4b389bae16b96207e9d3230895c99644b86",
     "https://bcr.bazel.build/modules/rules_java/5.5.0/MODULE.bazel": "486ad1aa15cdc881af632b4b1448b0136c76025a1fe1ad1b65c5899376b83a50",
     "https://bcr.bazel.build/modules/rules_java/6.0.0/MODULE.bazel": "8a43b7df601a7ec1af61d79345c17b31ea1fedc6711fd4abfd013ea612978e39",
@@ -391,18 +373,18 @@
     "https://bcr.bazel.build/modules/rules_python/0.23.1/MODULE.bazel": "49ffccf0511cb8414de28321f5fcf2a31312b47c40cc21577144b7447f2bf300",
     "https://bcr.bazel.build/modules/rules_python/0.25.0/MODULE.bazel": "72f1506841c920a1afec76975b35312410eea3aa7b63267436bfb1dd91d2d382",
     "https://bcr.bazel.build/modules/rules_python/0.28.0/MODULE.bazel": "cba2573d870babc976664a912539b320cbaa7114cd3e8f053c720171cde331ed",
-    "https://bcr.bazel.build/modules/rules_python/0.29.0/MODULE.bazel": "2ac8cd70524b4b9ec49a0b8284c79e4cd86199296f82f6e0d5da3f783d660c82",
     "https://bcr.bazel.build/modules/rules_python/0.31.0/MODULE.bazel": "93a43dc47ee570e6ec9f5779b2e64c1476a6ce921c48cc9a1678a91dd5f8fd58",
-    "https://bcr.bazel.build/modules/rules_python/0.32.2/MODULE.bazel": "01052470fc30b49de91fb8483d26bea6f664500cfad0b078d4605b03e3a83ed4",
     "https://bcr.bazel.build/modules/rules_python/0.33.2/MODULE.bazel": "3e036c4ad8d804a4dad897d333d8dce200d943df4827cb849840055be8d2e937",
     "https://bcr.bazel.build/modules/rules_python/0.37.1/MODULE.bazel": "3faeb2d9fa0a81f8980643ee33f212308f4d93eea4b9ce6f36d0b742e71e9500",
     "https://bcr.bazel.build/modules/rules_python/0.37.2/MODULE.bazel": "b5ffde91410745750b6c13be1c5dc4555ef5bc50562af4a89fd77807fdde626a",
     "https://bcr.bazel.build/modules/rules_python/0.4.0/MODULE.bazel": "9208ee05fd48bf09ac60ed269791cf17fb343db56c8226a720fbb1cdf467166c",
     "https://bcr.bazel.build/modules/rules_python/0.40.0/MODULE.bazel": "9d1a3cd88ed7d8e39583d9ffe56ae8a244f67783ae89b60caafc9f5cf318ada7",
     "https://bcr.bazel.build/modules/rules_python/1.0.0/MODULE.bazel": "898a3d999c22caa585eb062b600f88654bf92efb204fa346fb55f6f8edffca43",
+    "https://bcr.bazel.build/modules/rules_python/1.3.0/MODULE.bazel": "8361d57eafb67c09b75bf4bbe6be360e1b8f4f18118ab48037f2bd50aa2ccb13",
     "https://bcr.bazel.build/modules/rules_python/1.4.1/MODULE.bazel": "8991ad45bdc25018301d6b7e1d3626afc3c8af8aaf4bc04f23d0b99c938b73a6",
     "https://bcr.bazel.build/modules/rules_python/1.6.0/MODULE.bazel": "7e04ad8f8d5bea40451cf80b1bd8262552aa73f841415d20db96b7241bd027d8",
-    "https://bcr.bazel.build/modules/rules_python/1.6.0/source.json": "e980f654cf66ec4928672f41fc66c4102b5ea54286acf4aecd23256c84211be6",
+    "https://bcr.bazel.build/modules/rules_python/1.6.3/MODULE.bazel": "a7b80c42cb3de5ee2a5fa1abc119684593704fcd2fec83165ebe615dec76574f",
+    "https://bcr.bazel.build/modules/rules_python/1.6.3/source.json": "f0be74977e5604a6526c8a416cda22985093ff7d5d380d41722d7e44015cc419",
     "https://bcr.bazel.build/modules/rules_robolectric/4.14.1.2/MODULE.bazel": "d44fec647d0aeb67b9f3b980cf68ba634976f3ae7ccd6c07d790b59b87a4f251",
     "https://bcr.bazel.build/modules/rules_robolectric/4.14.1.2/source.json": "37c10335f2361c337c5c1f34ed36d2da70534c23088062b33a8bdaab68aa9dea",
     "https://bcr.bazel.build/modules/rules_rust/0.45.1/MODULE.bazel": "a69d0db3a958fab2c6520961e1b2287afcc8b36690fd31bbc4f6f7391397150d",
@@ -420,8 +402,10 @@
     "https://bcr.bazel.build/modules/rules_shell/0.5.0/MODULE.bazel": "8c8447370594d45539f66858b602b0bb2cb2d3401a4ebb9ad25830c59c0f366d",
     "https://bcr.bazel.build/modules/rules_shell/0.6.1/MODULE.bazel": "72e76b0eea4e81611ef5452aa82b3da34caca0c8b7b5c0c9584338aa93bae26b",
     "https://bcr.bazel.build/modules/rules_shell/0.6.1/source.json": "20ec05cd5e592055e214b2da8ccb283c7f2a421ea0dc2acbf1aa792e11c03d0c",
-    "https://bcr.bazel.build/modules/rules_swift/3.1.2/MODULE.bazel": "72c8f5cf9d26427cee6c76c8e3853eb46ce6b0412a081b2b6db6e8ad56267400",
-    "https://bcr.bazel.build/modules/rules_swift/3.1.2/source.json": "e85761f3098a6faf40b8187695e3de6d97944e98abd0d8ce579cb2daf6319a66",
+    "https://bcr.bazel.build/modules/rules_swift/1.16.0/MODULE.bazel": "4a09f199545a60d09895e8281362b1ff3bb08bbde69c6fc87aff5b92fcc916ca",
+    "https://bcr.bazel.build/modules/rules_swift/2.1.1/MODULE.bazel": "494900a80f944fc7aa61500c2073d9729dff0b764f0e89b824eb746959bc1046",
+    "https://bcr.bazel.build/modules/rules_swift/2.4.0/MODULE.bazel": "1639617eb1ede28d774d967a738b4a68b0accb40650beadb57c21846beab5efd",
+    "https://bcr.bazel.build/modules/rules_swift/2.4.0/source.json": "a6577f57f9febbdc015a01f2a8f3487422032f134d6c61d18ed8e8ca3b9acc7c",
     "https://bcr.bazel.build/modules/stardoc/0.5.0/MODULE.bazel": "f9f1f46ba8d9c3362648eea571c6f9100680efc44913618811b58cc9c02cd678",
     "https://bcr.bazel.build/modules/stardoc/0.5.1/MODULE.bazel": "1a05d92974d0c122f5ccf09291442580317cdd859f07a8655f1db9a60374f9f8",
     "https://bcr.bazel.build/modules/stardoc/0.5.3/MODULE.bazel": "c7f6948dae6999bf0db32c1858ae345f112cacf98f174c7a8bb707e41b974f1c",
@@ -432,8 +416,8 @@
     "https://bcr.bazel.build/modules/stardoc/0.7.1/MODULE.bazel": "3548faea4ee5dda5580f9af150e79d0f6aea934fc60c1cc50f4efdd9420759e7",
     "https://bcr.bazel.build/modules/stardoc/0.7.2/MODULE.bazel": "fc152419aa2ea0f51c29583fab1e8c99ddefd5b3778421845606ee628629e0e5",
     "https://bcr.bazel.build/modules/stardoc/0.7.2/source.json": "58b029e5e901d6802967754adf0a9056747e8176f017cfe3607c0851f4d42216",
-    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.2/MODULE.bazel": "75aab2373a4bbe2a1260b9bf2a1ebbdbf872d3bd36f80bff058dccd82e89422f",
-    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.2/source.json": "5fba48bbe0ba48761f9e9f75f92876cafb5d07c0ce059cc7a8027416de94a05b",
+    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/MODULE.bazel": "5e463fbfba7b1701d957555ed45097d7f984211330106ccd1352c6e0af0dcf91",
+    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/source.json": "32bd87e5f4d7acc57c5b2ff7c325ae3061d5e242c0c4c214ae87e0f1c13e54cb",
     "https://bcr.bazel.build/modules/tar.bzl/0.2.1/MODULE.bazel": "52d1c00a80a8cc67acbd01649e83d8dd6a9dc426a6c0b754a04fe8c219c76468",
     "https://bcr.bazel.build/modules/tar.bzl/0.5.1/MODULE.bazel": "7c2eb3dcfc53b0f3d6f9acdfd911ca803eaf92aadf54f8ca6e4c1f3aee288351",
     "https://bcr.bazel.build/modules/tar.bzl/0.6.0/MODULE.bazel": "a3584b4edcfafcabd9b0ef9819808f05b372957bbdff41601429d5fd0aac2e7c",
@@ -442,23 +426,18 @@
     "https://bcr.bazel.build/modules/toolchains_llvm/1.6.0/source.json": "6bd3ef95a288dd2bb1582eca332af850c9a5428a23bb92cb1c57c2dfe6cb7369",
     "https://bcr.bazel.build/modules/toolchains_protoc/0.5.0/MODULE.bazel": "e649dcd74790d8b186517588c827a777dfa67acfc4cbd733721c4be143ea107f",
     "https://bcr.bazel.build/modules/toolchains_protoc/0.5.0/source.json": "9152bf33827a44f796f94f486252fc0128d9efc2413246ebb09a234bb628a846",
-    "https://bcr.bazel.build/modules/upb/0.0.0-20211020-160625a/MODULE.bazel": "6cced416be2dc5b9c05efd5b997049ba795e5e4e6fafbe1624f4587767638928",
     "https://bcr.bazel.build/modules/upb/0.0.0-20220923-a547704/MODULE.bazel": "7298990c00040a0e2f121f6c32544bab27d4452f80d9ce51349b1a28f3005c43",
     "https://bcr.bazel.build/modules/upb/0.0.0-20230516-61a97ef/MODULE.bazel": "c0df5e35ad55e264160417fd0875932ee3c9dda63d9fccace35ac62f45e1b6f9",
-    "https://bcr.bazel.build/modules/upb/0.0.0-20230907-e7430e6/MODULE.bazel": "3a7dedadf70346e678dc059dbe44d05cbf3ab17f1ce43a1c7a42edc7cbf93fd9",
     "https://bcr.bazel.build/modules/xds/0.0.0-20240423-555b57e/MODULE.bazel": "cea509976a77e34131411684ef05a1d6ad194dd71a8d5816643bc5b0af16dc0f",
     "https://bcr.bazel.build/modules/xds/0.0.0-20240423-555b57e/source.json": "7227e1fcad55f3f3cab1a08691ecd753cb29cc6380a47bc650851be9f9ad6d20",
     "https://bcr.bazel.build/modules/yq.bzl/0.1.1/MODULE.bazel": "9039681f9bcb8958ee2c87ffc74bdafba9f4369096a2b5634b88abc0eaefa072",
     "https://bcr.bazel.build/modules/yq.bzl/0.1.1/source.json": "2d2bad780a9f2b9195a4a370314d2c17ae95eaa745cefc2e12fbc49759b15aa3",
     "https://bcr.bazel.build/modules/zlib/1.2.11/MODULE.bazel": "07b389abc85fdbca459b69e2ec656ae5622873af3f845e1c9d80fe179f3effa0",
     "https://bcr.bazel.build/modules/zlib/1.2.12/MODULE.bazel": "3b1a8834ada2a883674be8cbd36ede1b6ec481477ada359cd2d3ddc562340b27",
-    "https://bcr.bazel.build/modules/zlib/1.2.13/MODULE.bazel": "aa6deb1b83c18ffecd940c4119aff9567cd0a671d7bba756741cb2ef043a29d5",
     "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.1/MODULE.bazel": "6a9fe6e3fc865715a7be9823ce694ceb01e364c35f7a846bf0d2b34762bc066b",
-    "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.3/MODULE.bazel": "af322bc08976524477c79d1e45e241b6efbeb918c497e8840b8ab116802dda79",
     "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.5/MODULE.bazel": "eec517b5bbe5492629466e11dae908d043364302283de25581e3eb944326c4ca",
     "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.5/source.json": "22bc55c47af97246cfc093d0acf683a7869377de362b5d1c552c2c2e16b7a806",
-    "https://bcr.bazel.build/modules/zlib/1.3.1/MODULE.bazel": "751c9940dcfe869f5f7274e1295422a34623555916eb98c174c1e945594bf198",
-    "https://bcr.bazel.build/modules/zlib/1.3/MODULE.bazel": "6a9c02f19a24dcedb05572b2381446e27c272cd383aed11d41d99da9e3167a72"
+    "https://bcr.bazel.build/modules/zlib/1.3.1/MODULE.bazel": "751c9940dcfe869f5f7274e1295422a34623555916eb98c174c1e945594bf198"
   },
   "selectedYankedVersions": {},
   "moduleExtensions": {
@@ -1159,168 +1138,12 @@
     },
     "@@googleapis+//:extensions.bzl%switched_rules": {
       "general": {
-        "bzlTransitiveDigest": "vG6fuTzXD8MMvHWZEQud0MMH7eoC4GXY0va7VrFFh04=",
-        "usagesDigest": "tB2/BAROtqvrfaBweAJxJpqqnx85mOx/aupy9bEK4Ss=",
+        "bzlTransitiveDigest": "liqpEiZfQn8ycdEspyJt6J+baY9GQOl+9/prJJz2wTA=",
+        "usagesDigest": "AtKnJVSfl4DFbEt1Zhzwc971VYZMgmyRYK8WMKrwA7o=",
         "recordedFileInputs": {},
         "recordedDirentsInputs": {},
         "envVariables": {},
-        "generatedRepoSpecs": {
-          "com_google_googleapis_imports": {
-            "repoRuleId": "@@googleapis+//:repository_rules.bzl%switched_rules",
-            "attributes": {
-              "rules": {
-                "proto_library_with_info": [
-                  "",
-                  ""
-                ],
-                "moved_proto_library": [
-                  "",
-                  ""
-                ],
-                "java_proto_library": [
-                  "",
-                  ""
-                ],
-                "java_grpc_library": [
-                  "",
-                  ""
-                ],
-                "java_gapic_library": [
-                  "",
-                  ""
-                ],
-                "java_gapic_test": [
-                  "",
-                  ""
-                ],
-                "java_gapic_assembly_gradle_pkg": [
-                  "",
-                  ""
-                ],
-                "py_proto_library": [
-                  "",
-                  ""
-                ],
-                "py_grpc_library": [
-                  "",
-                  ""
-                ],
-                "py_gapic_library": [
-                  "",
-                  ""
-                ],
-                "py_test": [
-                  "",
-                  ""
-                ],
-                "py_gapic_assembly_pkg": [
-                  "",
-                  ""
-                ],
-                "py_import": [
-                  "",
-                  ""
-                ],
-                "go_proto_library": [
-                  "",
-                  ""
-                ],
-                "go_grpc_library": [
-                  "",
-                  ""
-                ],
-                "go_library": [
-                  "",
-                  ""
-                ],
-                "go_test": [
-                  "",
-                  ""
-                ],
-                "go_gapic_library": [
-                  "",
-                  ""
-                ],
-                "go_gapic_assembly_pkg": [
-                  "",
-                  ""
-                ],
-                "cc_proto_library": [
-                  "",
-                  ""
-                ],
-                "cc_grpc_library": [
-                  "",
-                  ""
-                ],
-                "cc_gapic_library": [
-                  "",
-                  ""
-                ],
-                "php_proto_library": [
-                  "",
-                  "php_proto_library"
-                ],
-                "php_grpc_library": [
-                  "",
-                  "php_grpc_library"
-                ],
-                "php_gapic_library": [
-                  "",
-                  "php_gapic_library"
-                ],
-                "php_gapic_assembly_pkg": [
-                  "",
-                  "php_gapic_assembly_pkg"
-                ],
-                "nodejs_gapic_library": [
-                  "",
-                  "typescript_gapic_library"
-                ],
-                "nodejs_gapic_assembly_pkg": [
-                  "",
-                  "typescript_gapic_assembly_pkg"
-                ],
-                "ruby_proto_library": [
-                  "",
-                  ""
-                ],
-                "ruby_grpc_library": [
-                  "",
-                  ""
-                ],
-                "ruby_ads_gapic_library": [
-                  "",
-                  ""
-                ],
-                "ruby_cloud_gapic_library": [
-                  "",
-                  ""
-                ],
-                "ruby_gapic_assembly_pkg": [
-                  "",
-                  ""
-                ],
-                "csharp_proto_library": [
-                  "",
-                  ""
-                ],
-                "csharp_grpc_library": [
-                  "",
-                  ""
-                ],
-                "csharp_gapic_library": [
-                  "",
-                  ""
-                ],
-                "csharp_gapic_assembly_pkg": [
-                  "",
-                  ""
-                ]
-              }
-            }
-          }
-        },
+        "generatedRepoSpecs": {},
         "recordedRepoMappingEntries": []
       }
     },
@@ -1420,34 +1243,6 @@
         "recordedRepoMappingEntries": []
       }
     },
-    "@@rules_apple+//apple:extensions.bzl%non_module_deps": {
-      "general": {
-        "bzlTransitiveDigest": "UsflLeiazyu2v5pvibcvOeIdDV95S25rT96h4XU1nhY=",
-        "usagesDigest": "M3VqFpeTCo4qmrNKGZw0dxBHvTYDrfV3cscGzlSAhQ4=",
-        "recordedFileInputs": {},
-        "recordedDirentsInputs": {},
-        "envVariables": {},
-        "generatedRepoSpecs": {
-          "xctestrunner": {
-            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/google/xctestrunner/archive/b7698df3d435b6491b4b4c0f9fc7a63fbed5e3a6.tar.gz"
-              ],
-              "strip_prefix": "xctestrunner-b7698df3d435b6491b4b4c0f9fc7a63fbed5e3a6",
-              "sha256": "ae3a063c985a8633cb7eb566db21656f8db8eb9a0edb8c182312c7f0db53730d"
-            }
-          }
-        },
-        "recordedRepoMappingEntries": [
-          [
-            "rules_apple+",
-            "bazel_tools",
-            "bazel_tools"
-          ]
-        ]
-      }
-    },
     "@@rules_dotnet+//dotnet:extensions.bzl%dotnet": {
       "general": {
         "bzlTransitiveDigest": "fd+R6GHICVvxgxz6YGDAcp7EbUx26nq9MWH1unOHz9I=",
@@ -2398,7 +2193,7 @@
     "@@rules_python+//python/uv:uv.bzl%uv": {
       "general": {
         "bzlTransitiveDigest": "8vT1ddXtljNxYD0tJkksqzeKE6xqx4Ix+tXthAppjTI=",
-        "usagesDigest": "p80sy6cYQuWxx5jhV3fOTu+N9EyIUFG9+F7UC/nhXic=",
+        "usagesDigest": "icnInV8HDGrRQf9x8RMfxWfBHgT3OgRlYovS/9POEJw=",
         "recordedFileInputs": {},
         "recordedDirentsInputs": {},
         "envVariables": {},
@@ -3733,6 +3528,160 @@
           ]
         ]
       }
+    },
+    "@@rules_swift+//swift:extensions.bzl%non_module_deps": {
+      "general": {
+        "bzlTransitiveDigest": "gITmwZkwiDAjxHDTZA8AxJiD5JGajyGl/ExE3dyszB0=",
+        "usagesDigest": "9w18ec4dj90mX/JqpR2tBU2YVc1GU9yNxi/d7q6lLVA=",
+        "recordedFileInputs": {},
+        "recordedDirentsInputs": {},
+        "envVariables": {},
+        "generatedRepoSpecs": {
+          "com_github_apple_swift_protobuf": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-protobuf/archive/1.20.2.tar.gz"
+              ],
+              "sha256": "3fb50bd4d293337f202d917b6ada22f9548a0a0aed9d9a4d791e6fbd8a246ebb",
+              "strip_prefix": "swift-protobuf-1.20.2/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_protobuf/BUILD.overlay"
+            }
+          },
+          "com_github_grpc_grpc_swift": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/grpc/grpc-swift/archive/1.16.0.tar.gz"
+              ],
+              "sha256": "58b60431d0064969f9679411264b82e40a217ae6bd34e17096d92cc4e47556a5",
+              "strip_prefix": "grpc-swift-1.16.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_grpc_grpc_swift/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_docc_symbolkit": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-docc-symbolkit/archive/refs/tags/swift-5.10-RELEASE.tar.gz"
+              ],
+              "sha256": "de1d4b6940468ddb53b89df7aa1a81323b9712775b0e33e8254fa0f6f7469a97",
+              "strip_prefix": "swift-docc-symbolkit-swift-5.10-RELEASE",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_docc_symbolkit/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio/archive/2.42.0.tar.gz"
+              ],
+              "sha256": "e3304bc3fb53aea74a3e54bd005ede11f6dc357117d9b1db642d03aea87194a0",
+              "strip_prefix": "swift-nio-2.42.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_nio/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_http2": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-http2/archive/1.26.0.tar.gz"
+              ],
+              "sha256": "f0edfc9d6a7be1d587e5b403f2d04264bdfae59aac1d74f7d974a9022c6d2b25",
+              "strip_prefix": "swift-nio-http2-1.26.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_nio_http2/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_transport_services": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-transport-services/archive/1.15.0.tar.gz"
+              ],
+              "sha256": "f3498dafa633751a52b9b7f741f7ac30c42bcbeb3b9edca6d447e0da8e693262",
+              "strip_prefix": "swift-nio-transport-services-1.15.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_nio_transport_services/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_extras": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-extras/archive/1.4.0.tar.gz"
+              ],
+              "sha256": "4684b52951d9d9937bb3e8ccd6b5daedd777021ef2519ea2f18c4c922843b52b",
+              "strip_prefix": "swift-nio-extras-1.4.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_nio_extras/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_log": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-log/archive/1.4.4.tar.gz"
+              ],
+              "sha256": "48fe66426c784c0c20031f15dc17faf9f4c9037c192bfac2f643f65cb2321ba0",
+              "strip_prefix": "swift-log-1.4.4/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_log/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_nio_ssl": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-nio-ssl/archive/2.23.0.tar.gz"
+              ],
+              "sha256": "4787c63f61dd04d99e498adc3d1a628193387e41efddf8de19b8db04544d016d",
+              "strip_prefix": "swift-nio-ssl-2.23.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_nio_ssl/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_collections": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-collections/archive/1.0.4.tar.gz"
+              ],
+              "sha256": "d9e4c8a91c60fb9c92a04caccbb10ded42f4cb47b26a212bc6b39cc390a4b096",
+              "strip_prefix": "swift-collections-1.0.4/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_collections/BUILD.overlay"
+            }
+          },
+          "com_github_apple_swift_atomics": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "urls": [
+                "https://github.com/apple/swift-atomics/archive/1.1.0.tar.gz"
+              ],
+              "sha256": "1bee7f469f7e8dc49f11cfa4da07182fbc79eab000ec2c17bfdce468c5d276fb",
+              "strip_prefix": "swift-atomics-1.1.0/",
+              "build_file": "@@rules_swift+//third_party:com_github_apple_swift_atomics/BUILD.overlay"
+            }
+          },
+          "build_bazel_rules_swift_index_import": {
+            "repoRuleId": "@@bazel_tools//tools/build_defs/repo:http.bzl%http_archive",
+            "attributes": {
+              "build_file": "@@rules_swift+//third_party:build_bazel_rules_swift_index_import/BUILD.overlay",
+              "canonical_id": "index-import-5.8",
+              "urls": [
+                "https://github.com/MobileNativeFoundation/index-import/releases/download/5.8.0.1/index-import.tar.gz"
+              ],
+              "sha256": "28c1ffa39d99e74ed70623899b207b41f79214c498c603915aef55972a851a15"
+            }
+          },
+          "build_bazel_rules_swift_local_config": {
+            "repoRuleId": "@@rules_swift+//swift/internal:swift_autoconfiguration.bzl%swift_autoconfiguration",
+            "attributes": {}
+          }
+        },
+        "recordedRepoMappingEntries": [
+          [
+            "rules_swift+",
+            "bazel_tools",
+            "bazel_tools"
+          ]
+        ]
+      }
     }
   },
   "facts": {

ci/BUILD.bazel

@@ -1,5 +1,6 @@
 load("@rules_oci//oci:defs.bzl", "oci_image", "oci_load", "oci_push")
 load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
+load("//ci:jar_split.bzl", "jar_split")
 
 #
 # Deployment artifacts (tools needed on the host, not in containers)
@@ -50,11 +51,37 @@ pkg_tar(
 # Push:  bazel run //ci:eagle_server_push
 #
 
-# Package the deploy JAR
+# Split the Eagle server runtime classpath into a stable third-party layer
+# (Scala stdlib, gRPC, Netty, ScalaPB, AWS SDK, ...) and a small first-party
+# layer that changes every commit. Most pushes then only re-upload the small
+# app layer instead of the whole ~150-300MB fat JAR.
+jar_split(
+    name = "eagle_server_jars",
+    binary = "//src/main/scala/net/eagle0/eagle:eagle_server",
+)
+
+filegroup(
+    name = "eagle_server_deps_jars",
+    srcs = [":eagle_server_jars"],
+    output_group = "deps",
+)
+
+filegroup(
+    name = "eagle_server_app_jars",
+    srcs = [":eagle_server_jars"],
+    output_group = "app",
+)
+
 pkg_tar(
-    name = "eagle_server_jar_layer",
-    srcs = ["//src/main/scala/net/eagle0/eagle:eagle_server_deploy.jar"],
-    package_dir = "/app",
+    name = "eagle_server_deps_layer",
+    srcs = [":eagle_server_deps_jars"],
+    package_dir = "/app/lib/deps",
+)
+
+pkg_tar(
+    name = "eagle_server_app_layer",
+    srcs = [":eagle_server_app_jars"],
+    package_dir = "/app/lib/app",
 )
 
 # Package the game resources needed at runtime
@@ -82,8 +109,11 @@ oci_image(
         "-XX:+UnlockDiagnosticVMOptions",
         "-XX:+DebugNonSafepoints",  # Required for JFR to see through inlined methods
         "-XX:FlightRecorderOptions=stackdepth=256",
-        "-jar",
-        "/app/eagle_server_deploy.jar",
+        # Classpath glob is expanded by the JVM itself (exec-form, no shell).
+        # Deps dir first keeps third-party precedence; app last shadows nothing.
+        "-cp",
+        "/app/lib/deps/*:/app/lib/app/*",
+        "net.eagle0.eagle.Main",
     ],
     env = {
         "JAVA_OPTS": "-Xmx2g -XX:+UseG1GC",
@@ -91,7 +121,8 @@ oci_image(
     exposed_ports = ["40032/tcp"],
     tars = [
         ":busybox_layer",
-        ":eagle_server_jar_layer",
+        ":eagle_server_deps_layer",
+        ":eagle_server_app_layer",
         ":eagle_resources_layer",
     ],
     workdir = "/app",

ci/github_actions/archive_ios.sh

@@ -40,6 +40,19 @@ if [ -f "$INFO_PLIST" ]; then
     /usr/libexec/PlistBuddy -c "Set :ITSAppUsesNonExemptEncryption false" "$INFO_PLIST" 2>/dev/null \
         || /usr/libexec/PlistBuddy -c "Add :ITSAppUsesNonExemptEncryption bool false" "$INFO_PLIST"
     echo "Set ITSAppUsesNonExemptEncryption=false in Info.plist"
+
+    # Remove UIApplicationSceneManifest if present.
+    # Unity 6 generates this key, which opts the app into the iOS scene-based
+    # lifecycle. This breaks Application.deepLinkActivated because iOS routes
+    # deep link URLs through UISceneDelegate instead of UIApplicationDelegate,
+    # and Unity doesn't implement the scene delegate path.
+    # See: https://issuetracker.unity3d.com/issues/in-135632
+    if /usr/libexec/PlistBuddy -c "Print :UIApplicationSceneManifest" "$INFO_PLIST" 2>/dev/null; then
+        echo "Found UIApplicationSceneManifest in Info.plist — removing to fix deep link handling"
+        /usr/libexec/PlistBuddy -c "Delete :UIApplicationSceneManifest" "$INFO_PLIST"
+    else
+        echo "No UIApplicationSceneManifest in Info.plist (deep links should work)"
+    fi
 fi
 
 # Unity always generates "Unity-iPhone" as the main app scheme
@@ -88,6 +101,16 @@ EOF
 
 echo "Exporting IPA..."
 
+# Restore keychain search list before export.
+# xcodebuild archive can reset the user keychain search list during long
+# builds, dropping the temporary CI keychain that holds the signing cert.
+# Re-add it here so xcodebuild -exportArchive can find the certificate.
+if [ -n "${KEYCHAIN_NAME:-}" ]; then
+    echo "Restoring keychain search list (adding $KEYCHAIN_NAME)"
+    security list-keychains -d user -s "$KEYCHAIN_NAME" login.keychain
+    security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"
+fi
+
 # Debug: List available keychains and signing identities
 echo "=== Debug: Available keychains ==="
 security list-keychains -d user
@@ -97,11 +120,24 @@ echo "=== Debug: Export options plist ==="
 cat "$EXPORT_OPTIONS_PLIST"
 echo "=== End debug ==="
 
-# Export IPA (removed -allowProvisioningUpdates as we're using manual signing)
+# Export IPA with App Store Connect API key authentication.
+# Without the API key, xcodebuild falls back to the Xcode-Token in the
+# keychain, which expires periodically and breaks headless CI builds.
+EXPORT_AUTH_ARGS=()
+if [ -n "${APP_STORE_CONNECT_API_KEY_PATH:-}" ] && [ -n "${APP_STORE_CONNECT_API_KEY_ID:-}" ] && [ -n "${APP_STORE_CONNECT_API_ISSUER_ID:-}" ]; then
+    echo "Using App Store Connect API key for export authentication"
+    EXPORT_AUTH_ARGS=(
+        -authenticationKeyPath "$APP_STORE_CONNECT_API_KEY_PATH"
+        -authenticationKeyID "$APP_STORE_CONNECT_API_KEY_ID"
+        -authenticationKeyIssuerID "$APP_STORE_CONNECT_API_ISSUER_ID"
+    )
+fi
+
 xcodebuild -exportArchive \
     -archivePath "$ARCHIVE_PATH" \
     -exportPath "$EXPORT_PATH" \
-    -exportOptionsPlist "$EXPORT_OPTIONS_PLIST"
+    -exportOptionsPlist "$EXPORT_OPTIONS_PLIST" \
+    "${EXPORT_AUTH_ARGS[@]}"
 
 # Find and rename the IPA to a consistent name
 IPA_FILE=$(find "$EXPORT_PATH" -name "*.ipa" | head -1)
@@ -111,3 +147,9 @@ fi
 
 echo "Export complete: $EXPORT_PATH/eagle0.ipa"
 ls -la "$EXPORT_PATH"
+
+# Clean up DerivedData for Unity-iPhone builds.
+# Each build creates a new ~3.6GB folder (Unity-iPhone-<random>) that
+# accumulates and wastes disk space on the build runner.
+echo "Cleaning up Unity-iPhone DerivedData..."
+find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -name 'Unity-iPhone-*' -type d -exec rm -rf {} + 2>/dev/null || true

ci/github_actions/build_ios_addressables.sh

@@ -1,49 +0,0 @@
-#!/usr/bin/env bash
-
-# Build iOS Addressables only (no player build)
-# This switches Unity to iOS target and builds addressables for CDN upload
-
-set -euxo pipefail
-
-# Read Unity version from project file
-UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
-
-# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
-BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
-
-WORKSPACE=$(pwd)
-
-echo "Building protos"
-./scripts/build_protos.sh
-UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
-LOG_PATH=${1:-"${BUILD_BASE}/editor_ios_addressables.log"}
-
-echo "Building iOS Addressables"
-
-mkdir -p "$(dirname "$LOG_PATH")"
-
-# Build Addressables for iOS target
-# Uses BuildiOSAddressables which explicitly switches build target
-# Capture exit code to show log on failure
-set +e
-${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity \
-   -nographics \
-   -batchmode \
-   -quit \
-   -executeMethod BuildScript.BuildiOSAddressables \
-   -logFile "$LOG_PATH" \
-   -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
-UNITY_EXIT_CODE=$?
-set -e
-
-if [ $UNITY_EXIT_CODE -ne 0 ]; then
-    echo ""
-    echo "Unity build failed with exit code $UNITY_EXIT_CODE"
-    echo "=== Unity Editor Log (last 200 lines) ==="
-    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
-    echo "=== End of Unity Editor Log ==="
-    exit $UNITY_EXIT_CODE
-fi
-
-echo "iOS Addressables build complete"
-echo "Bundles should be in: $WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0/ServerData/iOS/"

ci/github_actions/build_mac.sh

@@ -38,3 +38,25 @@ if [ $UNITY_EXIT_CODE -ne 0 ]; then
     echo "=== End of Unity Editor Log ==="
     exit $UNITY_EXIT_CODE
 fi
+
+if [ ! -f "$LOG_PATH" ]; then
+    echo ""
+    echo "ERROR: Unity exited successfully but did not write an editor log at $LOG_PATH"
+    exit 1
+fi
+
+# Fail the build if any prefab references are broken — this produces a player
+# that launches but has null Inspector fields, which is hard to debug.
+if grep -q "Missing Prefab" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has missing prefab references (likely stale Library cache):"
+    grep "Missing Prefab" "$LOG_PATH"
+    exit 1
+fi
+
+if grep -q "Build asset version error" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has asset version mismatches (likely stale Library cache):"
+    grep "Build asset version error" "$LOG_PATH" | head -5
+    exit 1
+fi

ci/github_actions/build_unity_ios.sh

@@ -53,6 +53,22 @@ if [ $UNITY_EXIT_CODE -ne 0 ]; then
     exit $UNITY_EXIT_CODE
 fi
 
+# Fail the build if any prefab references are broken — this produces a player
+# that launches but has null Inspector fields, which is hard to debug.
+if grep -q "Missing Prefab" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has missing prefab references (likely stale Library cache):"
+    grep "Missing Prefab" "$LOG_PATH"
+    exit 1
+fi
+
+if grep -q "Build asset version error" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has asset version mismatches (likely stale Library cache):"
+    grep "Build asset version error" "$LOG_PATH" | head -5
+    exit 1
+fi
+
 echo "iOS Unity build complete"
 echo "Xcode project generated at: $BUILD_PATH"
 ls -la "$BUILD_PATH"

ci/github_actions/build_windows.sh

@@ -38,3 +38,25 @@ if [ $UNITY_EXIT_CODE -ne 0 ]; then
     echo "=== End of Unity Editor Log ==="
     exit $UNITY_EXIT_CODE
 fi
+
+if [ ! -f "$LOG_PATH" ]; then
+    echo ""
+    echo "ERROR: Unity exited successfully but did not write an editor log at $LOG_PATH"
+    exit 1
+fi
+
+# Fail the build if any prefab references are broken — this produces a player
+# that launches but has null Inspector fields, which is hard to debug.
+if grep -q "Missing Prefab" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has missing prefab references (likely stale Library cache):"
+    grep "Missing Prefab" "$LOG_PATH"
+    exit 1
+fi
+
+if grep -q "Build asset version error" "$LOG_PATH"; then
+    echo ""
+    echo "ERROR: Build has asset version mismatches (likely stale Library cache):"
+    grep "Build asset version error" "$LOG_PATH" | head -5
+    exit 1
+fi

ci/github_actions/ensure_bazel_installed.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+export PATH="${COMMON_PATHS}:${PATH}"
+
+write_developer_dir_override() {
+    if [ "$(uname -s)" != "Darwin" ]; then
+        return
+    fi
+
+    local developer_dir=""
+    if [ -d "/Applications/Xcode.app/Contents/Developer" ]; then
+        developer_dir="/Applications/Xcode.app/Contents/Developer"
+    elif [ -d "/Library/Developer/CommandLineTools" ]; then
+        developer_dir="/Library/Developer/CommandLineTools"
+    else
+        developer_dir="$(xcode-select -p 2>/dev/null || true)"
+    fi
+
+    if [ -z "$developer_dir" ] || [ ! -d "$developer_dir" ]; then
+        echo "ERROR: no usable Apple developer directory found"
+        echo "Install Command Line Tools with: xcode-select --install"
+        echo "Full Xcode is only required for workflows that build/sign Apple apps."
+        exit 1
+    fi
+
+    export DEVELOPER_DIR="$developer_dir"
+    if [ -f .bazelrc.local ] && [ -z "${CI:-}" ]; then
+        echo "Keeping existing .bazelrc.local outside CI"
+    else
+        {
+            echo "# Generated by ci/github_actions/ensure_bazel_installed.sh; do not edit."
+            printf 'common:macos --repo_env=DEVELOPER_DIR=%s\n' "$developer_dir"
+        } > .bazelrc.local
+    fi
+
+    if [ -n "${GITHUB_ENV:-}" ]; then
+        echo "DEVELOPER_DIR=$developer_dir" >> "$GITHUB_ENV"
+    fi
+
+    echo "Using Apple developer directory at $developer_dir"
+}
+
+write_developer_dir_override
+
+if [ -n "${GITHUB_PATH:-}" ]; then
+    for path in /opt/homebrew/bin /usr/local/bin; do
+        if [ -d "$path" ]; then
+            echo "$path" >> "$GITHUB_PATH"
+        fi
+    done
+fi
+
+if command -v bazel >/dev/null 2>&1; then
+    echo "Using bazel at $(command -v bazel)"
+    bazel --version
+    exit 0
+fi
+
+if ! command -v bazelisk >/dev/null 2>&1; then
+    if ! command -v brew >/dev/null 2>&1; then
+        echo "ERROR: neither bazel nor bazelisk is on PATH, and Homebrew is unavailable"
+        exit 1
+    fi
+
+    echo "Installing bazelisk with Homebrew"
+    brew install bazelisk
+fi
+
+BAZEL_BIN_DIR="${RUNNER_TEMP:-/tmp}/bazel-bin"
+mkdir -p "$BAZEL_BIN_DIR"
+ln -sf "$(command -v bazelisk)" "$BAZEL_BIN_DIR/bazel"
+
+if [ -n "${GITHUB_PATH:-}" ]; then
+    echo "$BAZEL_BIN_DIR" >> "$GITHUB_PATH"
+fi
+
+export PATH="$BAZEL_BIN_DIR:$PATH"
+echo "Using bazelisk as bazel at $BAZEL_BIN_DIR/bazel"
+bazel --version

ci/github_actions/fetch_lfs.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Fetch LFS files from Gitea mirror with retry.
+#
+# Gitea's mirror-sync API is async — the webhook fires on push but the
+# actual sync may still be in progress when CI starts. Retry with backoff
+# to bridge the gap.
+#
+# Usage:
+#   ./ci/github_actions/fetch_lfs.sh                          # full pull
+#   ./ci/github_actions/fetch_lfs.sh --include="path/to/*"    # selective pull
+
+set -euo pipefail
+
+COMMON_PATHS="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+export PATH="${COMMON_PATHS}:${PATH}"
+
+MAX_ATTEMPTS=5
+RETRY_DELAY=15
+
+if [ -n "${GITHUB_PATH:-}" ]; then
+    for path in /opt/homebrew/bin /usr/local/bin; do
+        if [ -d "$path" ]; then
+            echo "$path" >> "$GITHUB_PATH"
+        fi
+    done
+fi
+
+if ! git lfs version >/dev/null 2>&1; then
+    if ! command -v brew >/dev/null 2>&1; then
+        echo "ERROR: git-lfs is unavailable, and Homebrew is not on PATH"
+        exit 1
+    fi
+
+    echo "Installing git-lfs with Homebrew"
+    brew install git-lfs
+fi
+
+echo "Using git-lfs at $(command -v git-lfs)"
+git lfs version
+
+git lfs install
+
+echo "LFS objects before pull:"
+git lfs ls-files | wc -l
+
+GIT_LFS_PULL=(git lfs pull)
+if [ -n "${GITHUB_TOKEN:-}" ]; then
+    BASIC_AUTH=$(printf 'x-access-token:%s' "$GITHUB_TOKEN" | base64 | tr -d '\n')
+    GIT_LFS_PULL=(git -c "http.https://github.com/.extraheader=AUTHORIZATION: basic $BASIC_AUTH" lfs pull)
+fi
+
+for i in $(seq 1 $MAX_ATTEMPTS); do
+    if "${GIT_LFS_PULL[@]}" "$@"; then
+        echo "LFS objects after pull:"
+        git lfs ls-files | wc -l
+        exit 0
+    fi
+    if [ "$i" -lt "$MAX_ATTEMPTS" ]; then
+        echo "LFS pull attempt $i/$MAX_ATTEMPTS failed, retrying in ${RETRY_DELAY}s..."
+        sleep $RETRY_DELAY
+    fi
+done
+
+echo "LFS pull failed after $MAX_ATTEMPTS attempts"
+exit 1

ci/github_actions/test_unity_editmode.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+set -euxo pipefail
+
+# Read Unity version from project file
+UNITY_VERSION=$(grep "m_EditorVersion:" src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/ProjectVersion.txt | head -1 | sed 's/m_EditorVersion: //')
+
+# Use runner-specific build directory if EAGLE0_BUILD_DIR is set, otherwise default
+BUILD_BASE="${EAGLE0_BUILD_DIR:-/tmp/eagle0}"
+
+WORKSPACE=$(pwd)
+UNITY_INSTALL_PATH="/Applications/Unity/Hub/Editor"
+LOG_PATH="${BUILD_BASE}/editor_editmode_tests.log"
+RESULTS_PATH="${BUILD_BASE}/editmode-test-results.xml"
+
+mkdir -p "$BUILD_BASE"
+
+echo "Building protos"
+./scripts/build_protos.sh
+
+echo "Running Unity EditMode tests"
+
+set +e
+"${UNITY_INSTALL_PATH}/${UNITY_VERSION}/Unity.app/Contents/MacOS/Unity" \
+   -nographics \
+   -batchmode \
+   -quit \
+   -executeMethod eagle0.Tests.DynamicTextBindingTestRunner.Run \
+   -testResults "$RESULTS_PATH" \
+   -logFile "$LOG_PATH" \
+   -projectPath "$WORKSPACE/src/main/csharp/net/eagle0/clients/unity/eagle0"
+UNITY_EXIT_CODE=$?
+set -e
+
+if [ $UNITY_EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Unity EditMode tests failed with exit code $UNITY_EXIT_CODE"
+    echo "=== Unity EditMode Test Log (last 200 lines) ==="
+    tail -200 "$LOG_PATH" || echo "Could not read log file at $LOG_PATH"
+    echo "=== End of Unity EditMode Test Log ==="
+    exit $UNITY_EXIT_CODE
+fi
+
+if [ ! -f "$LOG_PATH" ]; then
+    echo ""
+    echo "ERROR: Unity exited successfully but did not write an editor log at $LOG_PATH"
+    exit 1
+fi
+
+if [ ! -f "$RESULTS_PATH" ]; then
+    echo ""
+    echo "ERROR: Unity exited successfully but did not write test results at $RESULTS_PATH"
+    exit 1
+fi
+
+echo "Unity EditMode tests complete"

ci/jar_split.bzl

@@ -0,0 +1,57 @@
+"""Split a JVM binary's runtime classpath into first-party and third-party jar sets.
+
+This exists so the Docker image can place rarely-changing third-party jars in a
+lower OCI layer and frequently-changing first-party jars in a small top layer,
+so most pushes only re-upload the small layer.
+"""
+
+def _unique_name(jar):
+    # short_path is unique per jar and stable across commits (it depends only on
+    # the jar's own package/coordinate, not on unrelated targets), so the deps
+    # layer's tar entries stay byte-identical and its blob digest stays cached.
+    path = jar.short_path
+    if path.startswith("../"):
+        path = path[3:]
+    return path.replace("+", "_").replace("/", "_").replace("~", "_")
+
+def _impl(ctx):
+    info = ctx.attr.binary[JavaInfo]
+
+    app = []
+    deps = []
+    seen = {}
+    for jar in sorted(info.transitive_runtime_jars.to_list(), key = lambda f: f.path):
+        workspace = jar.owner.workspace_name if jar.owner else ""
+        bucket = "app" if workspace == "" else "deps"
+        out_name = _unique_name(jar)
+
+        key = bucket + "/" + out_name
+        if key in seen:
+            fail("jar_split: duplicate output name %r for %s and %s" % (
+                key,
+                seen[key],
+                jar.path,
+            ))
+        seen[key] = jar.path
+
+        link = ctx.actions.declare_file(ctx.label.name + "/" + key)
+        ctx.actions.symlink(output = link, target_file = jar)
+        (app if bucket == "app" else deps).append(link)
+
+    return [
+        DefaultInfo(files = depset(app + deps)),
+        OutputGroupInfo(app = depset(app), deps = depset(deps)),
+    ]
+
+jar_split = rule(
+    implementation = _impl,
+    doc = "Partitions a JVM binary's transitive runtime jars into 'app' " +
+          "(first-party, empty workspace) and 'deps' (third-party) output groups.",
+    attrs = {
+        "binary": attr.label(
+            mandatory = True,
+            providers = [[JavaInfo]],
+            doc = "A jvm binary/library target whose runtime classpath to split.",
+        ),
+    },
+)

docs/ALLIED_VICTORY_BATTLE_RESOLUTION.md

@@ -0,0 +1,281 @@
+# Allied Victory: Battle Resolution Flow
+
+How allied victories work end-to-end, from Shardok tactical resolution through Eagle strategic
+processing to player-facing aftermath decisions.
+
+## 1. Battle Setup (Eagle -> Shardok)
+
+When Eagle sends a battle to Shardok via `RequestBattlesAction`, each player gets specific victory
+conditions:
+
+| Player      | Victory Conditions                                                    |
+|-------------|-----------------------------------------------------------------------|
+| Attacker(s) | `HoldsCriticalTiles`, `LastPlayerStanding`, `LastAllianceStanding`     |
+| Defender    | `LastPlayerStanding`, `WinAfterMaxRounds`                              |
+
+This is set in `RequestBattlesAction.shardokPlayers`.
+
+Alliance information is sent separately in `PlayerSetupInfo.allies`. Eagle reads each player's
+`factionRelationships` and includes all non-HOSTILE factions as allies
+(`ShardokInterfaceGrpcClient.scala:75-80`).
+
+## 2. Victory Condition Evaluation (Shardok)
+
+Victory conditions are checked in `UpdateGameStatusAction.cpp` in priority order:
+
+### Check 1: LastPlayerStanding (any time)
+
+If exactly **one** player has surviving units and has `LastPlayerStanding`:
+- That player is the sole winner.
+- This applies to solo victories only (1 survivor).
+
+### Check 2: LastAllianceStanding (any time)
+
+If **multiple** players survive, check if they form a winning alliance:
+- ALL survivors must have `LastAllianceStanding` condition
+- ALL survivors must be **mutually** allied (every pair checks both directions)
+- If yes: all survivors are winners
+
+This triggers for AssaultProvince battles when allied attackers eliminate all defenders. Since the
+defender does **not** have `LastAllianceStanding`, the check correctly requires that only the
+allied attackers remain alive.
+
+### Check 3: WinAfterMaxRounds (end-of-round only)
+
+If the round counter exceeds `max_rounds`:
+- Find the player with `WinAfterMaxRounds` (always the defender)
+- That player wins, even if they have no surviving units
+- Eagle validates exactly 1 player has this condition (`internalRequire` in `RequestBattlesAction`)
+
+### Check 4: HoldsCriticalTiles (end-of-round only)
+
+**Single-player castle control**: If one player with `HoldsCriticalTiles` occupies ALL critical
+tiles with hero-bearing units, that player wins. Additionally, any other player who:
+- Has `HoldsCriticalTiles`
+- Is **mutually** allied with the castle holder
+
+is also added to `winning_shardok_ids` as a co-winner.
+
+**Allied castle control**: If multiple players collectively occupy all critical tiles with
+hero-bearing units, AND:
+- All occupants have `HoldsCriticalTiles`
+- All occupants are mutually allied
+
+Then all occupants are winners together.
+
+## 3. EndGameCondition Assignment Per Player (Shardok -> Eagle)
+
+Shardok assigns each player a `Victory` or `Loss`. All winners receive `Victory`; there is no
+`AllyVictory` distinction. The `EndGameCondition` proto reserves fields 2 (`ally_victory`) and
+3 (`draw`) for backwards compatibility but Eagle rejects both.
+
+`GameOverResponsePopulator` validates that any player allied to a winner is also in
+`winning_shardok_ids`. If an ally is missing from the winners list, it throws an internal error.
+
+**Known issue**: This validation is too strict for `LastPlayerStanding`. When one allied attacker
+is the sole survivor, their dead co-attacker is allied to the winner but legitimately not in
+`winning_shardok_ids` (they're dead). The throw should be changed to `Loss` for dead allies, or
+the check should only apply when the ally has surviving units.
+
+| Condition | Criterion |
+|-----------|-----------|
+| `Victory(type)` | Player is in `winning_shardok_ids` |
+| `Loss(type)` | Player is not in `winning_shardok_ids` |
+
+The `type` is the VictoryCondition that caused the game to end (e.g., `HoldsCriticalTiles`).
+
+### When do multiple players get Victory?
+
+In standard AssaultProvince battles:
+
+1. **Allied attackers jointly hold all castles** -> both get `Victory(HoldsCriticalTiles)`.
+
+2. **One attacker holds all castles alone, ally has `HoldsCriticalTiles` and is mutually allied**
+   -> both get `Victory(HoldsCriticalTiles)`. The ally is added to `winning_shardok_ids` by
+   `UpdateGameStatusAction`.
+
+3. **Allied attackers eliminate all defenders** -> both get `Victory(LastAllianceStanding)`.
+   This triggers because both have `LastAllianceStanding` and are mutually allied.
+
+4. **One attacker holds all castles, co-attacker is NOT allied** -> only the castle holder
+   gets `Victory(HoldsCriticalTiles)`; the non-allied co-attacker gets `Loss`.
+
+## 4. Eagle Processes Battle Results
+
+`ResolveBattleAction.scala` receives `BattleResolution` containing each player's
+`EndGameCondition` and resolved units.
+
+### Winner/Loser Partition
+
+Players are split by `isVictory` (line 383-386):
+- `winningResolvedPlayers`: Victory
+- `losingResolvedPlayers`: Loss
+
+### The `unitReturned` Function (line 765-788)
+
+Determines which units go home vs stay at the battle province:
+
+| Unit Status   | Returned? | Notes |
+|---------------|-----------|-------|
+| `Fled`        | Always    | Sent to their army's flee province |
+| `NeverEntered`| Conditional | Only if: attacker AND has flee province AND did NOT win (`!isVictory`) |
+| `Captured`    | Never     | |
+| `Normal`      | Never     | |
+| `Retreated`   | Never     | |
+| `Outlawed`    | Never     | Becomes unaffiliated hero |
+
+Key point: `NeverEntered` units from **winning** factions stay at the battle province rather than
+being sent home. This is important for bounced co-attackers who are allied with the actual winner.
+
+### Withdrawn/Fled Unit Routing (line 690-706)
+
+For units that ARE returned, `armyFromResolvedArmy` builds a returning army with
+`fleeProvinceId = None`. If the army has no `fleeProvinceId`, it becomes "shattered" (units
+become outlaws in the battle province). If the original army had a `fleeProvinceId` set, returned
+units are sent there as incoming armies.
+
+### Battle Resolution Branching (line 397-552)
+
+Three branches based on who won:
+
+#### Branch A: Defender Won
+
+Triggered when: `winningShardokPlayers.exists(_.isDefender)`
+
+- Executes `ProvinceHeldAction`
+- All non-defender, non-returned, non-outlawed units are **captured**
+- Province stays with the defending faction
+
+#### Branch B: Single Attacker Won
+
+Triggered when: exactly 1 attacking winner
+
+- Executes `ProvinceConqueredAction` immediately
+- Winning attacker's non-fled units occupy the province
+- Losing defenders' non-fled units are captured
+- Province transfers to the attacker
+
+#### Branch C: Multiple Allied Attackers Won
+
+Triggered when: 2+ attacking winners
+
+- Executes `MultiVictorBattleSetupAction`
+- Creates `PendingConquestInfo` with aftermath claimants
+- Province enters the **Battle Aftermath** phase
+
+## 5. Battle Aftermath (Multi-Victor Only)
+
+When multiple allied attackers win, the province enters an aftermath decision phase where players
+decide who keeps it.
+
+### Claimant Setup
+
+Each attacking winner becomes an `AftermathClaimant` with:
+- `units`: their non-fled, non-outlawed units still at the battle province
+- `armySize`: total troop count of those units
+- `broughtGold` / `broughtFood`: supplies their armies carried
+
+Claimants are **sorted by army size descending** (largest army decides first).
+
+### Decision Phase
+
+Claimants are presented with a choice **one at a time**, in order:
+
+**If no one has chosen "Keep" yet:**
+- **Keep Province**: claim the province for your faction
+- **Withdraw To**: pick an adjacent province to march your army to, optionally carrying up to
+  the gold/food you brought
+
+**If someone already chose "Keep":**
+- **Withdraw To** is the only option (can't have two keepers)
+
+**Last undecided claimant:**
+- If no one has chosen "Keep" yet, the last claimant **automatically keeps** (no command shown,
+  resolved by `AutoResolveBattleAftermathAction`)
+- This guarantees someone always claims the province
+
+### Finalization
+
+Once all claimants have decided (`FinalizeAftermathAction`):
+
+1. The keeper's units run through `ProvinceConqueredAction` -- province transfers to their faction
+2. Withdrawing claimants' units become incoming armies to their chosen adjacent province,
+   arriving next round, carrying the specified supplies
+3. `PendingConquestInfo` is cleared from the province
+
+## 6. Summary: Who Gets What
+
+### Two allied attackers jointly hold all castles
+- Shardok: Both get `Victory(HoldsCriticalTiles)` (both in `winning_shardok_ids`)
+- Eagle: Both are attacking winners -> MultiVictorBattleSetupAction
+- Players: Largest army picks first: Keep or Withdraw. Last player auto-keeps if no one chose Keep.
+
+### One attacker holds all castles, allied attacker doesn't
+- Shardok: Castle-holder gets `Victory(HoldsCriticalTiles)`. Mutually-allied co-attacker with
+  `HoldsCriticalTiles` is added to `winning_shardok_ids` -> also gets `Victory(HoldsCriticalTiles)`.
+- Eagle: Both are attacking winners -> MultiVictorBattleSetupAction -> Battle Aftermath.
+- Players: Largest army picks first: Keep or Withdraw.
+
+### Allied attackers eliminate all defenders
+- Shardok: Both attackers have `LastAllianceStanding` and are mutually allied -> both get
+  `Victory(LastAllianceStanding)`.
+- Eagle: Both are attacking winners -> MultiVictorBattleSetupAction -> Battle Aftermath.
+- Players: Largest army picks first: Keep or Withdraw.
+
+### Non-allied co-attackers: one holds all castles
+- Shardok: Castle-holder gets `Victory(HoldsCriticalTiles)`, non-allied co-attacker gets
+  `Loss(HoldsCriticalTiles)`.
+- Eagle: Single attacker won -> ProvinceConqueredAction. Non-allied co-attacker's units are
+  captured along with the defender's.
+
+### One allied attacker is sole survivor (LastPlayerStanding)
+- Shardok: Sole survivor gets `Victory(LastPlayerStanding)`. Dead ally should get `Loss`.
+- **BUG**: `GameOverResponsePopulator` currently throws because dead ally is allied to winner
+  but not in `winning_shardok_ids`. Needs fix — see known issue in Section 3.
+- Eagle (once fixed): Single attacker won -> ProvinceConqueredAction. Dead ally's units were
+  already destroyed in battle.
+
+### Single attacker wins (any condition, no co-attackers)
+- No alliance considerations. ProvinceConqueredAction immediately.
+
+### Defender wins (WinAfterMaxRounds or LastPlayerStanding)
+- ProvinceHeldAction. All non-returned attacker units are captured.
+
+## 7. Edge Cases and Known Issues
+
+### BUG: Dead ally causes crash via LastPlayerStanding
+
+When one allied attacker is the sole survivor (both the co-attacker and defender are dead),
+`LastPlayerStanding` fires and only the survivor is in `winning_shardok_ids`. The
+`GameOverResponsePopulator` then sees the dead co-attacker is allied to the winner but not in
+`winning_shardok_ids`, and throws `ShardokInternalErrorException`. Fix: dead allies should
+receive `Loss`, not trigger a validation error.
+
+### Non-allied co-attackers eliminate all defenders
+
+Two non-allied attackers who both survive after eliminating the defender cannot win via
+`LastAllianceStanding` (they aren't mutually allied). The game continues until max rounds,
+at which point the defender wins via `WinAfterMaxRounds`. They must capture all critical tiles.
+
+### Non-allied co-attackers: one holds all castles
+
+Only the castle holder wins. The non-allied co-attacker gets `Loss` and their units are captured
+along with the defender's. The mutual-alliance check in `UpdateGameStatusAction` prevents
+non-allied players from being added to `winning_shardok_ids`.
+
+## Key File References
+
+| Component | File |
+|-----------|------|
+| Victory condition checking | `src/main/cpp/net/eagle0/shardok/library/actions/UpdateGameStatusAction.cpp` |
+| Per-player EndGameCondition | `src/main/cpp/net/eagle0/shardok/server/GameOverResponsePopulator.cpp` |
+| Battle setup (victory conditions) | `src/main/scala/.../library/actions/impl/action/RequestBattlesAction.scala` |
+| Alliance communication | `src/main/scala/.../shardok_interface/ShardokInterfaceGrpcClient.scala:75-80` |
+| Battle result processing | `src/main/scala/.../library/actions/impl/action/ResolveBattleAction.scala` |
+| Unit return logic | `ResolveBattleAction.scala:765-788` (`unitReturned`) |
+| Multi-victor setup | `src/main/scala/.../library/actions/impl/action/MultiVictorBattleSetupAction.scala` |
+| Aftermath availability | `src/main/scala/.../library/actions/availability/AvailableBattleAftermathDecisionCommandFactory.scala` |
+| Aftermath command | `src/main/scala/.../library/actions/impl/command/BattleAftermathDecisionCommand.scala` |
+| Auto-resolve last claimant | `src/main/scala/.../library/actions/impl/action/AutoResolveBattleAftermathAction.scala` |
+| Finalize aftermath | `src/main/scala/.../library/actions/impl/action/FinalizeAftermathAction.scala` |
+| EndGameCondition enum | `src/main/scala/.../model/state/shardok_battle/EndGameCondition.scala` |

docs/ASSET_AUDIT.md

@@ -12,7 +12,7 @@ This document catalogs all media assets in the Unity project for licensing revie
 |----------|-------|-------|
 | Images | 10,637 | Mostly PNG icons and UI sprites |
 | Audio | 1,778 | 26 music tracks + 1,752 sound effects |
-| 3D Models | 52 | Bridge pack only |
+| 3D Models | 66+ | Bridge pack, Animal pack deluxe, Honey Badger |
 | Fonts | 16 | TTF files |
 
 ---
@@ -55,6 +55,30 @@ These are commercial Unity Asset Store purchases tied to your account:
 - **Contents:** Bridge construction pieces
 - **License:** Unity Asset Store
 
+### Animal pack deluxe
+- **Location:** `Assets/Animal pack deluxe/`
+- **Publisher:** janpec
+- **Asset Store Link:** https://assetstore.unity.com/packages/3d/characters/animals/animal-pack-deluxe-99702
+- **Contents:** 26 rigged and animated 3D animal models (bear, boar, crocodile, wolf, frog, crab, rabbit, scorpion, snake, stag, deer, rat, goat, pig, etc.) with idle, walk, run, eat, attack, and die animations
+- **Used for:** Beast province effects on the strategic map (AnimalEffect)
+- **License:** Unity Asset Store
+
+### 2D Monster Pack: Basic Bundle (+PSB)
+- **Location:** `Assets/DungeonMonsters2D/`
+- **Publisher:** SP1
+- **Asset Store Link:** https://assetstore.unity.com/packages/2d/characters/2d-monster-pack-basic-bundle-psb-328637
+- **Contents:** 2D animated monster sprites with PSB (Photoshop) source files. Characters: SkeletonWarrior, SkeletonArcher, SkeletonMage, Zombie, ZombieWarrior, Demon, Succubus, Imp, Spider, Rat, Vampire, DragonRed, Butcher
+- **Used for:** Beast province effects (MonsterEffect, DragonEffect) and human-type beast effects on the strategic map
+- **License:** Unity Asset Store
+
+### Honey Badger 3D Model
+- **Location:** `Assets/HoneyBadger/`
+- **Creator:** WildMesh 3D (@WildMesh_3D)
+- **Source:** https://sketchfab.com/3d-models/realistic-honey-badger-3d-model-09751ed5383c4afb924cfb6485d313f1
+- **Contents:** Rigged 3D honey badger model (FBX) with 63 animations and PBR texture
+- **Used for:** Honey badger beast province effect (AnimalEffect)
+- **License:** Purchased via Sketchfab/Patreon
+
 ### Fantasy Interface Sounds
 - **Location:** `Assets/Fantasy Interface Sounds/`
 - **Count:** 320 WAV files

docs/BEAST_EFFECTS.md

@@ -17,28 +17,26 @@ ProvinceBeastsController
 |------|---------|
 | `Assets/Eagle/ProvinceBeastsController.cs` | Routes beast names to prefabs, positions effects |
 | `Assets/Eagle/BeastsEffect.cs` | Generic effect (circling birds via particle system) |
-| `Assets/Eagle/DragonEffect.cs` | Dragon-specific effect (animated PSD Importer prefab) |
-| `Assets/Eagle/Effects/BeastsEffect.prefab` | Generic effect prefab |
-| `Assets/Eagle/Effects/DragonEffect.prefab` | Dragon effect prefab |
+| `Assets/Eagle/DragonEffect.cs` | Dragon-specific effect (3D model with flying/ground modes) |
+| `Assets/Eagle/MonsterEffect.cs` | Wandering 2D monster group (DungeonMonsters2D prefabs) |
+| `Assets/Eagle/AnimalEffect.cs` | Wandering 3D animal group (Animal Pack Deluxe prefabs) |
+| `Assets/Eagle/Effects/` | All effect prefabs |
 
 ## Adding a new beast type
 
-### 1. Create the effect MonoBehaviour
+### 1. Create the effect MonoBehaviour (or reuse an existing one)
 
-Create `Assets/Eagle/<BeastName>Effect.cs`. Two approaches:
+Three effect scripts exist for different asset types:
 
-**Particle-based** (like `BeastsEffect.cs`): Good for simple effects like swarms, packs, or atmospheric particles. Build particle systems programmatically in `Awake()`.
+**MonsterEffect** (2D sprites, DungeonMonsters2D): Spawns a group of wandering 2D monsters. Uses PascalCase animator states (`Idle`, `Move`) and triggers (`AttackTrigger`, `SpecialATrigger`). Flips sprite X scale for facing direction. Best for DungeonMonsters2D prefabs.
 
-**Animated prefab** (like `DragonEffect.cs`): Good for a single creature with bone-driven animation. Requires:
-- A PSD Importer `.psb` file with the creature art
-- `com.unity.2d.animation` and `com.unity.2d.psdimporter` packages (already installed)
-- An Animator Controller with animation clips
-- The effect script instantiates the animated prefab and drives its position/animation
+**AnimalEffect** (3D models, Animal Pack Deluxe): Spawns a group of wandering 3D animals. Uses lowercase animator states (`idle`, `walk`, `eat`, `attack`) with `Animator.Play()`. Rotates model on Y axis for facing. Sets `sortingOrder=103`, `renderQueue=4000`, and `ZTest=Always` to render above the map. Best for Animal Pack Deluxe prefabs.
 
-Your MonoBehaviour should:
-- Use `[RequireComponent(typeof(RectTransform))]` for UI canvas positioning
-- Accept tuning parameters as public fields (circle radius, speed, scale, etc.)
-- Clean up materials in `OnDestroy()` to avoid leaks
+**DragonEffect** (single animated 3D creature): Spawns a 3D dragon that alternates between flying (circling at altitude with fly actions) and grounded (wandering with ground actions) modes. Uses `Animator.Play()` with DragonMapAnims controller. Best for large creatures with flight capabilities.
+
+**Particle-based** (like `BeastsEffect.cs`): Good for simple effects like swarms or atmospheric particles.
+
+To create a new effect script, use `[RequireComponent(typeof(RectTransform))]` for UI canvas positioning and accept tuning parameters as public fields.
 
 ### 2. Create the prefab
 
@@ -83,21 +81,161 @@ Use `[ContextMenu]` methods on `ProvinceBeastsController` to test:
 
 Beast names come from `BeastInfo.SingularName` in the proto, which uses the canonical `singularName` from `src/main/resources/net/eagle0/eagle/beasts.tsv`. The switch in `GetEffectPrefab` uses exact string matching on this canonical name (e.g. `"dragon"`, `"wolf"`, `"skeleton"`).
 
-## Existing beast types in the game
+Human-type beasts (pirates, bandits, etc.) are matched via a `HumanBeastNames` HashSet in `ProvinceBeastsController` rather than individual switch cases.
 
-See `src/main/resources/net/eagle0/eagle/beasts.tsv` for the full list. Some candidates for custom effects:
+## Beast animation coverage
 
-| singularName | Notes |
-|---|---|
-| dragon | Has custom effect (animated 2D dragon) |
-| wolf | Common, could use pack/howling effect |
-| bear | Could use large creature effect |
-| skeleton | Could reuse DungeonMonsters2D Skeleton asset |
-| demon | Could reuse DungeonMonsters2D Demon asset |
-| spider | Could reuse DungeonMonsters2D Spider asset |
-| rat | Could reuse DungeonMonsters2D Rat asset |
-| vampire | Could reuse DungeonMonsters2D Vampire asset |
-| zombie | Could reuse DungeonMonsters2D Zombie asset |
+### Custom animations
+
+| Beast | Effect Type | Asset Pack | Prefabs Used |
+|---|---|---|---|
+| dragon | DragonEffect | 3dFoin Dragon | dragon_skin.FBX (w/ DragonMapAnims controller) |
+| skeleton | MonsterEffect | DungeonMonsters2D | SkeletonWarrior, SkeletonArcher, SkeletonMage |
+| zombie | MonsterEffect | DungeonMonsters2D | Zombie, ZombieWarrior |
+| rat | MonsterEffect + AnimalEffect | DungeonMonsters2D + Animal Pack Deluxe | Rat (2D), Rat (3D) |
+| spider | MonsterEffect | DungeonMonsters2D | Spider |
+| demon | MonsterEffect | DungeonMonsters2D | Demon, Succubus |
+| orc | MonsterEffect | DungeonMonsters2D | Imp |
+| vampire | MonsterEffect | DungeonMonsters2D | Vampire |
+| knight types (6 names) | AnimalEffect | Polytope Studio | PT_Male_Knight_01/02, PT_Female_Knight_01/02 (w/ HumanMapAnims controller) |
+| soldier types (8 names) | AnimalEffect | Polytope Studio | PT_Male_Soldier_01/02, PT_Female_Soldier_01/02 (w/ HumanMapAnims controller) |
+| archer types (3 names) | AnimalEffect | Polytope Studio | PT_Male_Archer_01/02, PT_Female_Archer_01/02 (w/ HumanMapAnims controller) |
+| militia types (8 names) | AnimalEffect | Polytope Studio | PT_Male_Militia_01/02, PT_Female_Militia_01/02 (w/ HumanMapAnims controller) |
+| peasant types (9 names) | AnimalEffect | Polytope Studio | PT_Male_Peasant_01, PT_Female_Peasant_01_a (w/ HumanMapAnims controller) |
+| clown | AnimalEffect | Clown Pack | Clown, Fat Clown (w/ per-prefab controller overrides) |
+| giant | AnimalEffect | Polytope Studio | PT_Male/Female_Peasant at 3x scale (w/ HumanMapAnims controller) |
+| ogre, troll | AnimalEffect | Orc-Ogre Pack | OrcOgre_Animated (w/ OgreMapAnims controller) |
+| bear | AnimalEffect | Animal Pack Deluxe | Brown_bear |
+| boar | AnimalEffect | Animal Pack Deluxe | Wild_boar |
+| crocodile | AnimalEffect | Animal Pack Deluxe | Crocodile |
+| snake | AnimalEffect | Animal Pack Deluxe | Viper |
+| crab | AnimalEffect | Animal Pack Deluxe | Crab |
+| frog | AnimalEffect | Animal Pack Deluxe | Common_frog, Common_frog_v2, Common_frog_v3 |
+| rabbit | AnimalEffect | Animal Pack Deluxe | Wild_rabbit, Wild_rabbit_v2 |
+| salamander | AnimalEffect | Animal Pack Deluxe | Fire_salamander |
+| scorpion | AnimalEffect | Animal Pack Deluxe | Scorpion, Yellow_fattail_scorpion |
+| stag | AnimalEffect | Animal Pack Deluxe | Deer, Deer_male |
+| wild goat | AnimalEffect | Animal Pack Deluxe | Goat, Ibex |
+| wild pig | AnimalEffect | Animal Pack Deluxe | Iron_age_pig, Iron_age_pig_v2 |
+| wolf, wolverine | AnimalEffect | Animal Pack Deluxe | Wolf |
+| honey badger | AnimalEffect | HoneyBadger (Sketchfab) | HoneyBadger (w/ HoneyBadgerMapAnims controller) |
+| raccoon | AnimalEffect | Raccoon (Sketchfab) | Raccoon (w/ RaccoonMapAnims controller) |
+| tiger | AnimalEffect | ithappy Animals FREE | Tiger_001 (w/ TigerMapAnims controller) |
+| elephant | AnimalEffect | Animal Pack Deluxe v2 | African_elephant, Indian_elephant (w/ ElephantMapAnims controller) |
+| mammoth | AnimalEffect | Animal Pack Deluxe v2 | African_elephant, Indian_elephant (w/ ElephantMapAnims controller) |
+| hippopotamus | AnimalEffect | Africa Animals Pack Low Poly V2 | Hippopotamus (w/ HippopotamusMapAnims controller) |
+| lion | AnimalEffect | Africa Animals Pack Low Poly V1 | Lion, Lioness (w/ LionMapAnims controller) |
+| velociraptor | AnimalEffect | Dino Pack Low Poly V1 | VelociraptorColor1, VelociraptorColor2 (w/ VelociraptorMapAnims controller) |
+| black panther | AnimalEffect | Africa Animals Pack Low Poly V1 | BlackPanther (w/ BlackPantherMapAnims controller) |
+| rhinoceros | AnimalEffect | Africa Animals Pack Low Poly V1 | Rhinoceros (w/ RhinocerosMapAnims controller) |
+| gorilla | AnimalEffect | Africa Animals Pack Low Poly V2 | Gorilla (w/ GorillaMapAnims controller) |
+| hyena | AnimalEffect | Africa Animals Pack Low Poly V2 | Hyena (w/ HyenaMapAnims controller) |
+| leopard | AnimalEffect | Africa Animals Pack Low Poly V2 | Leopard (w/ LeopardMapAnims controller) |
+| warthog | AnimalEffect | Africa Animals Pack Low Poly V2 | Phacochoerus (w/ WarthogMapAnims controller) |
+| emu | AnimalEffect | Australia Animals Pack V1 | Emu (w/ EmuMapAnims controller) |
+| kangaroo | AnimalEffect | Australia Animals Pack V1 | Kangaroo (w/ KangarooMapAnims controller) |
+| tasmanian devil | AnimalEffect | Australia Animals Pack V1 | TasmanianDevil (w/ TasmanianDevilMapAnims controller) |
+| hippogryph | DragonEffect | Heroic Fantasy Creatures Full Pack Vol 2 | Hippogriff_PBR (w/ HippogryphMapAnims controller) |
+
+### Human-type beasts
+
+34 human-type beast names use 3D Polytope Studio characters grouped into 5 archetypes. Each archetype uses a shared `HumanMapAnims.controller` that retargets Clown animation clips (idle, walk, attack, damage) via Unity's Humanoid system. One additional human type (psychopath) uses the 2D Butcher sprite from DungeonMonsters2D.
+
+| Archetype | Polytope Type | Beast Names (count) |
+|---|---|---|
+| **Knight** (heavy armor) | Knight M/F x2 | cultist, heretic, cannibal, terrorist, cossack, desperado (6) |
+| **Soldier** (medium armor) | Soldier M/F x2 | bandit, brigand, robber, highwayman, marauder, dacoit, freebooter, mobster (8) |
+| **Archer** (light armor, ranged) | Archer M/F x2 | thief, pirate, buccaneer (3) |
+| **Militia** (light armed) | Militia M/F x2 | hooligan, street tough, ruffian, scalawag, ne'er-do-well, crook, miscreant, asshole (8) |
+| **Peasant** (unarmed) | Peasant M/F | agitator, instigator, rabble-rouser, separatist, particularist, nihilist, proud boy, rebel, traitor (9) |
+
+Asset packs: Polytope Studio - Lowpoly Medieval Characters (Soldiers, Knights, Militia, Archers, Peasants)
+
+| **Butcher** (armed loner) | DungeonMonsters2D Butcher | psychopath (1) |
+
+### No custom animation (falls back to generic vultures)
+
+Ordered by spawn likelihood (most common first):
+
+| Beast | Likelihood | Notes |
+|---|---|---|
+| chimpanzee | 0.04 | Primate |
+| unknown | 0.00 | Intentional fallback |
+
+## Using low-poly animal packs (Africa Animals, Dino Pack)
+
+Assets from these packs (by the same author) require extra setup because they ship with **Legacy** animation import and include physics components that conflict with AnimalEffect. The workflow below applies to all of them:
+- Africa Animals Pack Low Poly V1 (Lion, Lioness, Black Panther, Crocodile, Elephant, Giraffe, Rhinoceros, Tiger, Zebra)
+- Africa Animals Pack Low Poly V2 (Hippopotamus, Antelope, Gorilla, Hyena, Leopard, Phacochoerus/Warthog)
+- Dino Pack Low Poly V1 (Velociraptor, Brontosaurus, Pteranodon, Stegosaurus, T-Rex, Triceratops)
+- Australia Animals Pack V1 (Chlamydosaurus/Frilled Lizard, Echidna, Emu, Kangaroo, Koala, Platypus, Tasmanian Devil)
+
+### Per-animal setup steps
+
+1. **Switch FBX import to Generic animation type.**
+   In the `.fbx.meta` file (location varies by pack):
+   - Change `animationType: 1` to `animationType: 2`
+   - Change `avatarSetup: 0` to `avatarSetup: 1` (newer format) — older metas without `avatarSetup` will auto-create an avatar at runtime
+   - Set `loopTime: 1` on looping clips (idle, walk, eat, run) but NOT one-shot clips (attack, death, hurt)
+   Unity will re-import the FBX with Mecanim-compatible clips when it next opens.
+
+2. **Create an AnimatorController** in `Assets/Eagle/Effects/` named `<Animal>MapAnims.controller`.
+   Use the same 4-state pattern (idle, walk, eat, attack) as ElephantMapAnims. Reference the animation clips by their fileIDs from the FBX meta's `internalIDToNameTable` (type 74 entries) or `fileIDToRecycleName` (older format, type 7400000+). These IDs are stable across import type changes. Note: if the FBX names its idle clip `idle1`, create the controller state as `idle` but reference the `idle1` clip by fileID.
+
+3. **Create an AnimalEffect prefab** in `Assets/Eagle/Effects/` named `<Animal>Effect.prefab`.
+   Reference the pack's prefab as the animal prefab, and wire up the new AnimatorController. Multiple color/sex variants from the same or similar FBX can share one controller (e.g., Lion and Lioness). AnimalEffect will automatically strip the pack's legacy Animation, Rigidbody, and Collider components at spawn time, and add an Animator if the prefab doesn't already have one.
+
+4. **Register in ProvinceBeastsController** with a case in `GetEffectPrefab()` and a test ContextMenu method.
+
+5. **Mark the effect prefab as Addressable** with the `beast-effects` label in the Unity editor (Window > Asset Management > Addressables > Groups).
+
+### Notes
+
+- The packs include both SingleTexture and TextureAtlas variants; use SingleTexture for best visual quality.
+- Hippos have water-specific animations (idlewater, deathwater) that could be used for future water-province effects.
+- The packs' prefabs include Rigidbody/BoxCollider components intended for gameplay use. AnimalEffect strips these automatically since it controls position directly.
+
+### Available animals not yet set up as beasts
+
+These animals exist in the imported packs and could be set up as in-game beasts using the workflow above:
+
+**Africa Animals Pack V1** (already imported):
+| Animal | Good fit for | Notes |
+|---|---|---|
+| Giraffe (x2 variants) | giraffe beast | Tall model, may need larger scale |
+| Zebra | zebra beast | Herd animal; good with higher animalCount |
+
+(Black Panther, Rhinoceros, Crocodile, Elephant, and Tiger already have effects.)
+
+**Africa Animals Pack V2** (already imported):
+| Animal | Good fit for | Notes |
+|---|---|---|
+| Antelope | antelope/gazelle beast | Fast-moving; good with higher moveSpeed |
+
+(Gorilla, Hyena, Leopard, Warthog, and Hippopotamus already have effects.)
+
+**Dino Pack Low Poly V1** (already imported):
+| Animal | Good fit for | Notes |
+|---|---|---|
+| Brontosaurus | brontosaurus/sauropod beast | Very large; needs big scale, low count |
+| Pteranodon | pteranodon/flying beast | Has fly animation; could use DragonEffect-style flight |
+| Stegosaurus | stegosaurus beast | Large herbivore |
+| T-Rex | tyrannosaurus beast | Iconic predator; good as a solo beast |
+| Triceratops | triceratops beast | Large herbivore; good for tough beast |
+
+(Velociraptor already has an effect.)
+
+**Australia Animals Pack V1** (already imported):
+| Animal | Good fit for | Notes |
+|---|---|---|
+| Koala | koala beast | Peaceful; good for low-threat province events |
+| Echidna | echidna beast | Small, spiny |
+| Chlamydosaurus (Frilled Lizard) | lizard beast | Has threat display animation |
+| Platypus (Ornitorinco) | platypus beast | Semi-aquatic; unique |
+
+(Emu, Kangaroo, and Tasmanian Devil already have effects.)
+
+None of the remaining animals above are currently in `beasts.tsv`.
 
 ## Tips
 
@@ -105,3 +243,4 @@ See `src/main/resources/net/eagle0/eagle/beasts.tsv` for the full list. Some can
 - Use `ParticleSystemScalingMode.Hierarchy` so effects scale with the map zoom
 - Set appropriate `sortingOrder` on renderers (existing effects use 102-104)
 - For animated prefabs, set `AnimatorCullingMode.AlwaysAnimate` since UI elements may be considered offscreen by the culling system
+- For 3D models (AnimalEffect), set `renderQueue=4000` and `ZTest=Always` on materials to prevent clipping behind the map

docs/LLM_MODEL_COMPARISON.md

@@ -42,16 +42,17 @@ Time-to-first-token (TTFT) was measured from request initiation to the first tex
 
 ### For Narrative Text Generation (Default)
 
-**Gemini 2.5 Flash-Lite** is recommended as the default:
-- Fastest TTFT (~0.6s) - nearly 3x faster than alternatives
-- Cheapest pricing ($0.10/$0.40 per 1M tokens)
-- Quality is acceptable for short narrative snippets
+**Gemini 3.1 Flash-Lite** is recommended as the default:
+- Priced at $0.25/$1.50 per 1M input/output tokens
+- Significantly faster than 2.5 Flash-Lite on throughput and TTFT
+- Meaningfully smarter than 2.5 Flash-Lite, while remaining one of the cheapest options
+- Quality is more than sufficient for short narrative snippets
 
 ### Alternative Options
 
 | Priority | Model | When to Use |
 |----------|-------|-------------|
-| Speed + Cost | Gemini 2.5 Flash-Lite | Default for most use cases |
+| Speed + Cost | Gemini 3.1 Flash-Lite | Default for most use cases |
 | Speed + Quality | gpt-4.1-mini | When you need OpenAI quality with good speed |
 | Instruction Following | claude-3-5-haiku | Complex multi-step prompts, consistent tone |
 | Maximum Quality | claude-sonnet-4 or gpt-5.2 | When output quality is paramount |
@@ -70,7 +71,7 @@ LLM settings can be changed at runtime via the admin console:
 1. Navigate to Admin Console → Settings
 2. Change `LlmProvider` to select vendor (gemini, openai, claude)
 3. Change the corresponding model name setting:
-   - `GeminiModelName` (default: gemini-2.5-flash-lite)
+   - `GeminiModelName` (default: gemini-3.1-flash-lite-preview)
    - `OpenAiModelName` (default: gpt-4.1-mini)
    - `ClaudeModelName` (default: claude-3-5-haiku-20241022)
 

docs/SHARDOK_AI_EXPERIMENT_TOOLING_PLAN.md

@@ -0,0 +1,77 @@
+# Shardok AI Experiment Tooling Plan
+
+## Summary
+
+Build a reusable workflow for Shardok AI battle baselines and scoring experiments. The goal is to
+turn the current one-off benchmark process into repeatable commands that extract real battles, run
+baseline and candidate configurations, capture detailed per-command traces, and write comparable
+reports.
+
+This work starts with the target-aware archery scoring experiment: attacker `EXPERIMENTAL` against
+defender `STANDARD`.
+
+## Key Changes
+
+- Add simulator trace support to `ai_battle_simulator_main`.
+  - New flag: `--trace-jsonl=<path>`.
+  - Emit one JSONL row per AI-selected command.
+  - Include run label, config path, state file, phase, sequence, round, player, side, command type,
+    actor unit, target coords, chosen index, available command count, search depth, commands
+    evaluated, completion reason, forced commands posted afterward, and pre/post side troop totals.
+  - Keep existing summary output unchanged.
+
+- Add reusable benchmark tooling under
+  `src/main/cpp/net/eagle0/shardok/ai_battle_simulator/benchmarks/`.
+  - `real_battle_suite.py`: shared helpers for reading `game.db`, materializing battle/state/result
+    blobs, extracting configs, running simulator binaries, parsing summaries, and collecting
+    real-game metadata.
+  - `run_real_battle_experiment.py`: CLI orchestration for baseline/candidate runs.
+  - Outputs: `summary.csv`, `comparison.csv`, `report.md`, generated configs, and per-run trace
+    JSONL files.
+
+- Add a clean EXPERIMENTAL switch for target-aware archery value.
+  - Use a new experiment id.
+  - Change only archery-availability scoring.
+  - Replace the flat archery-possible value with a target-sensitive value based on the best enemy
+    unit value.
+  - Do not include the previous fear-value change from experiment `27`.
+
+## Execution Plan
+
+- Create a feature branch from fetched `origin/main`.
+- Commit this plan document first.
+- Implement simulator trace output and reusable benchmark tooling.
+- Add the target-aware archery-only EXPERIMENTAL switch.
+- Run the new tool first on battle `6248`, then on the all-40 saved-battle suite if local runtime is
+  acceptable.
+- Compare baseline attacker `STANDARD` / defender `STANDARD` with candidate attacker
+  `EXPERIMENTAL` / defender `STANDARD`.
+- Record the results under the existing benchmark results area and call out battle `6248` in the
+  generated report.
+- Push the branch and create a PR after local validation.
+
+## Tests
+
+- Build:
+  - `bazel build //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator_main`
+  - `bazel build //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:real_battle_config_extractor`
+  - `bazel build //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:real_battle_smoke_metadata`
+- Unit/integration:
+  - `bazel test //src/test/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator_test`
+  - Add or extend a simulator test that verifies trace output is created and contains required
+    command fields.
+  - `python3 -m py_compile` on the new benchmark scripts.
+- Validation:
+  - Run the new tool on battle `6248`.
+  - Run the new tool on all 40 battles if feasible locally.
+  - Run `bazel test //src/test/cpp/...` before push if local time allows; otherwise open the PR
+    promptly and continue validation while CI starts.
+
+## Assumptions
+
+- "Experiment 3" means target-aware archery value from the previous recommendation list.
+- The first experiment compares attacker-only candidate behavior against unchanged defender
+  `STANDARD`.
+- JSONL is the trace format because command diagnostics will evolve over time.
+- Python benchmark scripts follow the existing executable-script pattern rather than adding Python
+  Bazel targets.

docs/SHARDOK_AI_SCORING_BENCHMARKS.md

@@ -0,0 +1,82 @@
+# Shardok AI Scoring Benchmarks
+
+The current STANDARD scoring experiment results are recorded in
+`src/main/cpp/net/eagle0/shardok/ai_battle_simulator/benchmarks/experimental_results/`.
+They use 40 saved Shardok battles extracted from `game_389ffb1901903118.zip`.
+
+The corrected all-40 run uses:
+
+- `max_rounds = 31`
+- `random_seed = 1`
+- iterative-deepening timeout propagation fix from PR #6923
+- AI setup placement
+- forced single-option commands
+- defender scoring fixed to `STANDARD` for every row
+- archery/start-fire capability derived like production setup
+- per-unit flee capability preserved by real-battle extraction
+- zero-troop combat heroes preserved as live units
+- `NO_PROFESSION` treated as a valid hero profession state, not as "no hero"
+
+Shardok siege battles do not have a draw result. If the attacker has not won after 31 rounds, the
+defender wins. The simulator records those cutoffs as `max_rounds_reached` defender wins.
+
+All 40 saved battle payloads now produce valid simulator configs. A battle side can have zero
+remaining troops as long as it has a hero; this is common for `NO_PROFESSION` heroes with no
+commanded battalion.
+
+An all-40 real-vs-sim comparison records whether the saved-game attacker/defender were human or AI
+players. Factions `3` and `4` are human players; all other factions in this save are AI players.
+The comparison uses broad winner side from the saved Shardok result payload, because exact replay
+is not available from the compact result rows. Real end-of-battle troop totals come from the
+all-factions Shardok `ActionResultView` stream's final `changed_player_totals`.
+
+An AI-vs-AI smoke check also reruns a subset where neither side used faction `3` or `4`.
+
+## Current Results
+
+These artifacts are the current baseline for future scoring comparisons.
+
+| Dataset | Valid battles | Invalid rows | Attacker wins | Defender wins | Notes |
+| --- | ---: | ---: | ---: | ---: | --- |
+| All-40 timeout-fix STANDARD baseline | 40 | 0 | 18 | 22 | `standard_scoring_all40_post_bugfix_baseline.*`; regenerated after fixing iterative-deepening timeout score propagation |
+| All-40 real saved game | 40 known | 0 unknown | 19 | 21 | `standard_scoring_all40_real_vs_sim.*`; sim matches 39/40 known winners |
+| AI-vs-AI smoke | 31 | 0 | 10 | 21 | 31/31 winner-side matches |
+
+The remaining real-vs-sim winner-side miss is `11754` (real attacker, sim defender), which had an
+AI attacker but a human defender in the saved game. The real attacker won with `2119` troops
+remaining; the STANDARD-vs-STANDARD simulation replaces the human defender with AI and the defender
+wins with `1000` troops remaining, so this row is not a comparable AI-vs-AI smoke miss. Battle
+`6248`, previously the remaining AI-vs-AI miss, now matches as an attacker win after expected-impact
+archery scoring was promoted to STANDARD.
+
+The closest six valid baseline rows are used for the scalar and behavior experiment batches. The
+single-run harness still has some nondeterminism even with `random_seed = 1`, so near-margin changes
+should be repeated before being promoted.
+
+## Experiment Tooling
+
+`src/main/cpp/net/eagle0/shardok/ai_battle_simulator/benchmarks/run_real_battle_experiment.py`
+is the reusable real-battle experiment runner. It can read a saved-game zip or extracted `game.db`,
+generate baseline/candidate simulator configs, run both sides, and write `summary.csv`,
+`comparison.csv`, `report.md`, generated configs, and per-command trace JSONL files.
+
+The repository keeps the current STANDARD baseline artifacts, but omits generated configs/traces
+for abandoned experiment batches. Regenerate those locally with the runner when a new comparison
+needs command-level traces.
+
+`src/main/cpp/net/eagle0/shardok/ai_battle_simulator/benchmarks/run_standard_baselines.py`
+regenerates the tracked STANDARD-vs-STANDARD baseline artifacts from a saved-game zip or extracted
+`game.db`, including the all-40 baseline, real-vs-sim comparison, and AI-vs-AI smoke files.
+
+The simulator supports `--trace-jsonl=<path>` and `--run-label=<label>` for detailed command traces.
+Each row records the selected command, search depth, forced command count, and pre/post side troop
+totals.
+
+Expected-impact archery replaced the old flat archery-position value in STANDARD. A unit that can
+shoot now gets half of the expected volley impact; a unit that is merely positioned for a future
+volley gets one quarter. Promoting that behavior flips `6248` to match the real AI-vs-AI attacker
+win without introducing an AI-vs-AI winner-side miss in the current saved-battle baseline.
+
+The latest baseline refresh was generated after the iterative-deepening evaluator stopped letting
+timeout fallback scores compete with completed command evaluations. Future STANDARD-vs-EXPERIMENTAL
+comparisons should compare against these checked-in timeout-fix baseline artifacts.

docs/SMALL_EAGLE_TODO.md

@@ -6,6 +6,16 @@ Be able to support a small (10-50 user) private alpha, including with strangers.
 
 Larger set of goals in [The Big Eagle TODO](https://docs.google.com/document/d/17RTt3-4Wl2AAVMRLodaC3a84E4de6xuQTWBPvCRM484/edit?pli=1&tab=t.0), but most of that is not necessary for MVP.
 
+## Current priority order
+
+1. Finish tutorial & first-session onboarding, especially the clear first-session goal and guided first scenario.
+2. Fix the basic Shardok AI issues that can make tactical battles feel broken or unfair.
+3. Publish a known issues doc so alpha testers do not repeatedly report the same rough edges.
+4. Verify the existing game-ended flow, then mark the win condition done if "all other factions defeated" works end-to-end.
+5. Add mid-game progression events where the King recognizes the player as they gain power.
+6. Add account-linking when provider switching or account recovery becomes important for alpha support.
+7. Leave terms of service and Windows code signing deferred until they matter for public release or broader distribution.
+
 ## Required
 
 ### Gameplay Productionization
@@ -17,7 +27,7 @@ Larger set of goals in [The Big Eagle TODO](https://docs.google.com/document/d/1
 - [x] ~~Fix long disconnects on deployments~~
 - [x] Fix the Mac installer
 - [x] ~~Still not reconnecting after deployments~~
-- [ ] Notify about client updates, button to come directly back
+- [x] Notify about client updates, button to come directly back
 - [x] Generatedtext healing
 - [x] Kill outstanding shardok requests when game is deleted
 
@@ -51,7 +61,7 @@ Larger set of goals in [The Big Eagle TODO](https://docs.google.com/document/d/1
 
 ### Basic Gameplay
 
-- [ ] Tutorial
+- [ ] Tutorial & first-session onboarding
   - [x] In the Your Warlord panel, say what the profession is
   - [x] ~~And separate panels for each profession when you encounter one~~
   - [x] ~~Command tutorial for each command the first time it's clicked~~
@@ -62,17 +72,16 @@ Larger set of goals in [The Big Eagle TODO](https://docs.google.com/document/d/1
   - [x] ~~Time to swear brotherhood~~
     - [x] ~~When you get large, or~~
     - [x] ~~When you get a good candidate~~
-  - [ ] Shardok tutorial!
+  - [x] ~~Shardok tutorial!~~
+  - [x] ~~Narrative hook in first few minutes - why should I care about my warlord?~~
+  - [ ] Clear first-session goal ("try to capture your first province" or similar)
+  - [x] ~~Early small victory to build momentum~~
+  - [ ] Guided first scenario vs. overwhelming sandbox?
 - [ ] Basic Shardok AI stuff fixed
-- [ ] Lobby fixes
+- [x] ~~Lobby fixes~~
 - [ ] Have goals / ending
   - [ ] Win condition: all other factions defeated
   - [ ] Mid-game progression: King recognizes you as you gain power (generated events)
-- [ ] First-session onboarding (beyond mechanics tutorial)
-  - [ ] Narrative hook in first few minutes - why should I care about my warlord?
-  - [ ] Clear first-session goal ("try to capture your first province" or similar)
-  - [ ] Early small victory to build momentum
-  - [ ] Guided first scenario vs. overwhelming sandbox?
 
 ## Nice to have
 

docs/SQLITE_ACTION_RESULT_DECOMPOSITION.md

@@ -0,0 +1,335 @@
+# SQLite Action Result Decomposition
+
+Follow-up to [SQLITE_HISTORY_DESIGN.md](SQLITE_HISTORY_DESIGN.md). This document plans the second wave of the SQLite migration: decomposing the `ActionResult` proto blob in `action_results.payload` into native relational tables, deleting the proto representation entirely for everything in scope.
+
+## Status — option B adopted (updated 2026-05-17)
+
+**This section supersedes the original plan below. Where the body conflicts with this section, this section wins.** The full-relational design is kept below for historical context and as the migration target if a structured-query need on deep aggregates ever materializes.
+
+The original plan (decompose every field into relational tables; "decision locked") was implemented for `ChangedProvince` first — ~37 child tables, ~1500 lines (PR #6721) — and then **rejected on cost/benefit**. We adopted **option B**: apply the "stopping rule" (originally carved out only for `Quest`) *consistently*. Shipped and merged as Phase 4.5b in **PR #6725**:
+
+- Keep the per-entity **top-level table with scalar / entity-reference columns + indexes** (the 4.5a tables). That is the part that earns its keep — "which actions changed province/hero/faction X, by how much" is one-line SQL.
+- Store the **rest of the aggregate as one `<entity>_proto BLOB` column** on that row: lossless round-trip / replay, no child tables for the deep nesting.
+- Scalar columns are pure query denormalization; **the proto blob is authoritative**. A later fully-relational pass (if ever needed) is a pure read-blob → write-columns migration — which is why the blob must survive any future proto deletion.
+
+Rationale: the deep army/unit/hero/claimant nesting is never analytics-queried — the exact property that justified blobbing `Quest`. Exploding it into ~37 tables was code volume without query value. The blob also means deep-aggregate field changes need **no SQL migration** (only promoted scalar columns do), which is the right shape for the volatile parts of the model. This rescinds "Decisions locked #1" and revises principle 7, the Scope, the Sequencing table, and "Deleting the proto" (all updated in place below).
+
+## Refinement — "refined option B" for shallow entities (updated 2026-05-19)
+
+**This section further supersedes the body and the Status section above where they conflict; it wins.** It records the pattern actually shipped for `ChangedHero` in Phase 4.5c.1 (#6727), which is a refinement of option B, not the whole-entity-blob shape the body still describes for that entity.
+
+Option B as originally stated keeps **one `<entity>_proto BLOB`** per row for the entire non-scalar residual. For a *shallow* entity that is more blob than it needs. Refined option B decomposes the residual into three tiers instead of one blob:
+
+- **Tier 1 — scalar / entity-reference columns + indexes.** The queryable surface (deltas, touched entities, enum ordinals). Always present; unchanged from 4.5a.
+- **Tier 2 — typed columns for sealed value-oneofs.** A sealed choice over simple values (e.g. `ChangedHeroC`'s `loyalty` / `vigor` `StatChange`, subtypes `StatDelta`/`StatAbsolute`/`StatNoChange`) becomes a **pair of nullable columns** (`loyalty_delta` / `loyalty_absolute`, …). The *column name is the discriminator*; at most one of each pair is non-NULL; both NULL ⇒ the no-change case. No `kind` column.
+- **Tier 3 — per-row leaf-proto blobs in a child table.** A repeated/optional nested aggregate becomes a child table keyed by `(action_seq, entity_id, n)` storing the **leaf** proto's bytes one row per element (e.g. `action_changed_heroes_new_backstory_events` holding `EventForHeroBackstory` blobs) — *not* a whole-entity blob.
+
+**Consequence (changes Decisions #1–#3 and 4.5i):** an entity fully covered by Tiers 1–3 has **no whole-entity blob**. It round-trips losslessly from columns + per-leaf blobs, so its per-entity proto and converter (`changed_hero.proto` / `ChangedHeroConverter`) become genuinely dead code, deletable in 4.5i. Only the **leaf** protos used as Tier-3 blob payloads (`event_for_hero_backstory.proto`) are retained as a wire format. The whole-entity `<entity>_proto BLOB` is now reserved for **deep** entities where Tiers 2–3 would be more work than value (`ChangedProvince`, the "new entity" snapshots).
+
+Per-entity decision (supersedes Decisions #2): classify each entity as **all-scalar** (Tier 1 only, no blob — e.g. likely `ChangedFaction`), **refined** (Tiers 1–3, no whole-entity blob, proto deletable — `ChangedHero`), or **deep** (Tier 1 + whole-entity `<entity>_proto BLOB`, proto retained — `ChangedProvince`, new-entity snapshots). Default to **refined** for shallow entities; fall back to **deep** only when the residual is too varied to be worth Tiers 2–3. Wherever the body or Status says "the proto blob is authoritative," for a *refined* entity read "the columns + per-leaf-proto blobs are authoritative."
+
+## Why
+
+The first wave (Phases 1–4) stores each action as a single proto blob in `action_results.payload`. That blob is opaque to SQL — any query about action contents (changed provinces, heroes affected, etc.) requires deserializing every row. The `action_result_type`, `round_id`, and date columns we denormalized are the only handles SQL has into actions.
+
+Two observations make full decomposition more attractive than the original design admitted:
+
+1. **The proto exists for storage only.** 92 Scala files reference `ChangedProvince`, but exactly one imports the proto type — `ChangedProvinceConverter.scala`. Everything else (action handlers, AI, utils) operates on `ChangedProvinceC`. The proto is **not** in any client-facing RPC contract — it lives under `eagle.internal`. Same is true for `ChangedHero`, `ChangedFaction`, `ChangedBattalion`, `Notification`, `GeneratedTextRequest`, and `ActionResult` itself. Replacing proto serialization with SQL writes does **not** lose forward/backward compatibility, because there are no external consumers depending on the proto wire format.
+
+2. **`ActionResultC` has no polymorphism at the top level.** It's a 34-field flat struct — `Option`s and `Vector`s, but no `sealed trait` discriminator at the action level. Every action has the same shape; the `actionResultType` enum tells you *which fields* are populated. This means the entire structure is relationalizable without per-action-type tables.
+
+The work is bounded, the proto becomes dead code at the end of it, and it has to happen before alpha — once we have users, every schema change costs a real migration. Doing it pre-alpha lets us nuke save dirs as part of deployment.
+
+## Scope
+
+**In:** `action_results.payload` (the whole-`ActionResult` blob) is gone by the end. Per-entity scalar / entity-reference columns make the *queryable* surface (deltas, touched entities) native SQL. **Under refined option B (see Status):** `internal/action_result.proto` and *deep* entities' sub-message protos (`changed_province.proto`, …) are retained as blob payloads; *refined* entities' protos (`changed_hero.proto`) are decomposed away and deleted, with only their Tier-3 leaf protos (`event_for_hero_backstory.proto`) kept. (The original plan deleted all of them, then a draft of option B kept all of them; neither holds — it's now per-entity.)
+
+**Out:**
+- `state_snapshots.payload` — stays as proto-blob `GameState`. These are caches for replay, not authoritative data; querying inside a snapshot adds nothing over querying the action deltas that produced it. Cost/benefit doesn't justify decomposing them.
+- Shardok tables — already designed in Phase 3, no changes here. The shardok protos (`ShardokActionResult`, etc.) are owned by the Shardok subsystem and are part of an actual RPC contract; they stay.
+- Client text — already SQLite-backed (`SqliteClientTextStore`).
+
+## Principles
+
+1. **One table per non-trivial aggregate type.** Every `Vector[X]` or `Option[X]` where `X` is a Scala case class with multiple fields gets its own table.
+2. **Vectors of primitives → join tables.** `Vector[Int]` becomes a two-column table: `(parent_key, value)`. No JSON arrays, no comma-separated strings — those defeat the point.
+3. **Optional aggregates → presence by row existence.** `Option[X]` for aggregate `X` is a row that may or may not exist with the matching parent key. The natural primary key on `(action_seq)` enforces 0-or-1-row semantics for `Option[X]` aggregates and `(action_seq, n)` for vectors.
+4. **Sealed traits get a discriminator column.** When a Scala sealed trait has a few subtypes with diverging fields, prefer one wide table with `kind TEXT NOT NULL` + nullable per-subtype columns over per-subtype tables. When subtypes diverge significantly (>5 unrelated fields each), use per-subtype tables. Decide per case.
+5. **`ON DELETE CASCADE` everywhere.** Every child table has `FOREIGN KEY (action_seq) REFERENCES action_results(action_seq) ON DELETE CASCADE`. `truncateTo` becomes a single `DELETE FROM action_results WHERE action_seq >= ?` and the cascades do the rest.
+6. **Schema migrations are now real.** Once we have a relational schema, evolving it means SQL migrations. We introduce a real migration runner (see "Schema evolution" below). The `metadata` table's `schema_version` becomes load-bearing.
+7. **(Revised under option B — see Status.) The proto blob is the retained authoritative store for each entity's deep aggregates; scalar / entity-reference columns are denormalized projections of it.** The original principle assumed full decomposition and proto deletion. Instead each entity keeps one proto-blob source of truth and denormalizes only the queryable columns from the same write — so there is no dual *relational* representation to keep in sync.
+
+## Top-level: `action_results`
+
+The `payload BLOB` column goes away. Scalar fields become columns; aggregate fields move to related tables.
+
+```sql
+CREATE TABLE action_results (
+    action_seq                              INTEGER PRIMARY KEY,
+    action_result_type                      INTEGER NOT NULL,
+    -- existing scalar denormalizations
+    round_id                                INTEGER NOT NULL,
+    date_year                               INTEGER,
+    date_month                              INTEGER,
+    -- new scalar columns (formerly inside payload)
+    acting_hero_id                          INTEGER,
+    acting_faction_id                       INTEGER,
+    province_id                             INTEGER,
+    province_id_acted                       INTEGER,
+    new_round_phase                         INTEGER,
+    new_round_id                            INTEGER,
+    last_command_type_for_acting_province   INTEGER,
+    resolved_battle                         TEXT,
+    new_victor_faction_id                   INTEGER,
+    game_ended                              INTEGER,  -- 0/1/NULL
+    new_random_seed                         INTEGER,
+    new_game_type                           INTEGER
+);
+
+-- Vectors of bare IDs become join tables:
+CREATE TABLE action_destroyed_battalion_ids (
+    action_seq    INTEGER NOT NULL,
+    battalion_id  INTEGER NOT NULL,
+    PRIMARY KEY (action_seq, battalion_id),
+    FOREIGN KEY (action_seq) REFERENCES action_results(action_seq) ON DELETE CASCADE
+);
+
+CREATE TABLE action_removed_hero_ids (
+    action_seq INTEGER NOT NULL,
+    hero_id    INTEGER NOT NULL,
+    PRIMARY KEY (action_seq, hero_id),
+    FOREIGN KEY (action_seq) REFERENCES action_results(action_seq) ON DELETE CASCADE
+);
+
+CREATE TABLE action_removed_faction_ids (...);
+CREATE TABLE action_affected_faction_ids (...);
+
+-- Singleton optional aggregates: a row exists if and only if Option is Some.
+CREATE TABLE action_new_battles (
+    action_seq INTEGER PRIMARY KEY,
+    -- ShardokBattle fields here, columns or sub-tables as needed
+    FOREIGN KEY (action_seq) REFERENCES action_results(action_seq) ON DELETE CASCADE
+);
+
+CREATE TABLE action_new_chronicle_entries (action_seq INTEGER PRIMARY KEY, ...);
+CREATE TABLE action_new_eagle_map_info (action_seq INTEGER PRIMARY KEY, ...);
+```
+
+Each `Vector[Aggregate]` field on `ActionResultC` gets its own table (covered below).
+
+### Indexes
+
+We keep the existing indexes (`round_id`, `(date_year, date_month)`) and add a few that obvious queries need:
+
+- `idx_action_results_acting_hero_id`
+- `idx_action_results_acting_faction_id`
+- `idx_action_results_province_id`
+
+Plus indexes on the per-entity join tables on the entity-id side, so cross-game queries like "all actions touching hero X" become single-index lookups:
+
+- `idx_action_changed_provinces_province_id`
+- `idx_action_changed_heroes_hero_id`
+- `idx_action_changed_faction_faction_id`
+- `idx_action_changed_battalions_battalion_id`
+
+## Changed-entity tables (four parallel structures)
+
+### `action_changed_provinces`
+
+`ChangedProvinceC` has ~50 fields: scalar deltas, nested aggregates, ID vectors. The scalar fields become columns on `action_changed_provinces`; aggregate fields become child tables.
+
+```sql
+CREATE TABLE action_changed_provinces (
+    action_seq                            INTEGER NOT NULL,
+    province_id                           INTEGER NOT NULL,
+    -- resource changes
+    gold_delta                            INTEGER,
+    food_delta                            INTEGER,
+    -- stat changes
+    new_price_index                       REAL,
+    economy_delta                         REAL,
+    agriculture_delta                     REAL,
+    infrastructure_delta                  REAL,
+    economy_devastation_delta             REAL,
+    agriculture_devastation_delta         REAL,
+    infrastructure_devastation_delta      REAL,
+    support_delta                         REAL,
+    -- round properties
+    set_has_acted                         INTEGER,  -- 0/1/NULL
+    set_ruler_is_traveling                INTEGER,
+    -- ruling faction changes
+    clear_ruling_faction_id               INTEGER NOT NULL DEFAULT 0,
+    new_ruling_faction_id                 INTEGER,
+    -- misc scalar fields
+    new_locked_improvement_kind           TEXT,     -- 'none', 'new'
+    new_locked_improvement_value          INTEGER,  -- ImprovementType if kind='new'
+    new_province_orders                   INTEGER,  -- ProvinceOrderType enum
+    clear_defending_army                  INTEGER NOT NULL DEFAULT 0,
+    cleared_pending_conquest_info         INTEGER NOT NULL DEFAULT 0,
+    removed_deferred_change_index         INTEGER,
+    PRIMARY KEY (action_seq, province_id),
+    FOREIGN KEY (action_seq) REFERENCES action_results(action_seq) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_action_changed_provinces_province_id
+    ON action_changed_provinces(province_id);
+```
+
+The vector and optional-aggregate fields of `ChangedProvinceC` become per-aggregate child tables, all keyed by `(action_seq, province_id)`:
+
+- `action_changed_provinces_new_unaffiliated_heroes(action_seq, province_id, n, ...)` — one row per added hero, with `UnaffiliatedHero` fields as columns
+- `action_changed_provinces_changed_unaffiliated_heroes(...)` — same shape
+- `action_changed_provinces_removed_unaffiliated_hero_ids(action_seq, province_id, hero_id)` — join table for ID vector
+- `action_changed_provinces_new_captured_heroes(...)` — `CapturedHero` fields
+- `action_changed_provinces_recruitment_attempted_captured_hero_ids(...)` — join table
+- `action_changed_provinces_removed_captured_hero_ids(...)` — join table
+- `action_changed_provinces_new_ruling_faction_hero_ids(...)` — join table
+- `action_changed_provinces_removed_ruling_faction_hero_ids(...)` — join table
+- `action_changed_provinces_new_battalion_ids(...)` — join table
+- `action_changed_provinces_removed_battalion_ids(...)` — join table
+- `action_changed_provinces_new_incoming_armies(...)` — `MovingArmy` decomposition
+- `action_changed_provinces_removed_incoming_army_ids(...)` — join table
+- `action_changed_provinces_new_withdrawing_armies(...)` — `MovingArmy` decomposition
+- `action_changed_provinces_removed_withdrawing_army_ids(...)` — join table
+- `action_changed_provinces_new_hostile_armies(...)` — `HostileArmyGroup` decomposition
+- `action_changed_provinces_removed_hostile_army_faction_ids(...)` — join table
+- `action_changed_provinces_hostile_army_status_changes(action_seq, province_id, faction_id, new_status)` — small flat aggregate
+- `action_changed_provinces_new_defending_army` — `Option[Army]` (singleton row if present)
+- `action_changed_provinces_new_incoming_shipments(...)` — `MovingSupplies` decomposition
+- `action_changed_provinces_removed_incoming_shipment_ids(...)` — join table
+- `action_changed_provinces_new_incoming_end_turn_actions(...)` — `IncomingEndTurnAction` decomposition
+- `action_changed_provinces_removed_incoming_end_turn_actions(...)` — same shape (these are values, not IDs)
+- `action_changed_provinces_new_battle_revelations(...)` — `BattleRevelation` decomposition
+- `action_changed_provinces_removed_battle_revelations(...)` — same shape
+- `action_changed_provinces_new_pending_conquest_info` — `Option[PendingConquestInfo]` (singleton row)
+- `action_changed_provinces_new_province_events` — `Vector[ProvinceEvent]`
+- `action_changed_provinces_new_deferred_change` — `Option[DeferredChange]` (singleton, with discriminator since `DeferredChangeT` is sealed)
+
+That's a lot of tables — ~25 just under `ChangedProvince`. The schema is mechanical once the principles are set; what makes it tractable is that every table follows the same shape: parent FK, `n` (vector index) where ordering matters, the aggregate's fields as columns, child aggregates as their own tables.
+
+### `action_changed_heroes`, `action_changed_factions`, `action_changed_battalions`
+
+Same pattern. Each gets its top-level table keyed by `(action_seq, entity_id)`, plus child tables for nested aggregates and ID vectors. Indexes on the entity id (`hero_id`, `faction_id`, `battalion_id`) so cross-game queries are fast.
+
+`ChangedHeroC` is a *refined* entity (see "Refinement" in Status): no whole-entity blob. Its sealed `StatChange` (`StatDelta`/`StatAbsolute`/`StatNoChange`) `loyalty` and `vigor` oneofs are Tier-2 column pairs (`loyalty_delta`/`loyalty_absolute`, `vigor_delta`/`vigor_absolute`; column name discriminates, both-NULL ⇒ `StatNoChange`). Its `newBackstoryEvents: Vector[EventForHeroBackstory]` is Tier-3: per-event `EventForHeroBackstory` blobs, one row each, in `action_changed_heroes_new_backstory_events`. Columns + per-event blobs round-trip losslessly, so `changed_hero.proto`/`ChangedHeroConverter` become deletable (4.5i) and only `event_for_hero_backstory.proto` is retained as a blob format.
+
+## "New" entity tables
+
+`ActionResultC.newProvinces: Vector[ProvinceT]`, `newHeroes`, `newFactions`, `newBattalions`. These are *full snapshots* of new entities at creation.
+
+These are bigger and recursive: `ProvinceT` itself has fields including its armies, heroes, battalions, events, etc. Decomposing fully duplicates the structure already covered by the existing `state_snapshots` blob (which we're explicitly keeping). The decomposition still needs to happen because we're dropping the proto entirely — and these vectors live in `ActionResultC`, which we're decomposing.
+
+**Decision**: go fully relational here too. Each "new entity" gets its top-level table (`action_new_provinces` etc.) keyed by `(action_seq, entity_id)`, with the same per-aggregate-field decomposition pattern as the changed-entity tables. Where a "new entity" type contains its own nested aggregates, those aggregates either share child tables with the `changed_*` family (preferred where the field shape is identical, e.g., `MovingArmy`, `UnaffiliatedHero`) or get their own (where they diverge).
+
+This is the most expensive single chunk of the decomposition — explicitly called out so we know what we're committing to in PR 4.5f.
+
+## Notifications and generated text requests
+
+```sql
+CREATE TABLE action_new_notifications (action_seq INTEGER NOT NULL, n INTEGER NOT NULL, ...);
+CREATE TABLE action_removed_notifications (action_seq INTEGER NOT NULL, n INTEGER NOT NULL, ...);
+CREATE TABLE action_new_generated_text_requests (...);
+CREATE TABLE action_client_text_visibility_extensions (...);
+```
+
+`NotificationT` and `GeneratedTextRequestT` are both sealed traits. Use the discriminator-column pattern: `kind TEXT NOT NULL` plus nullable per-subtype columns, unless a subtype's fields are too divergent to share a row.
+
+## Schema evolution
+
+We can't punt on this any more. With this many tables, the next field addition can't be "edit the proto." It needs a real migration mechanism.
+
+Conventions:
+- `metadata['schema_version']` is a small integer, currently `1`.
+- A `Migrations` object holds an ordered `Vector[(Int, Connection => Unit)]` of migration steps.
+- On `SqliteHistory.loaded`, the schema version is read; any pending migrations are applied in a single transaction; the version is bumped.
+- New games start at the latest version.
+- Migration steps are append-only — never edit an existing step.
+
+This is the standard Rails / Flyway / etc. pattern, scaled down to one file.
+
+## Read path: reconstructing `ActionResultC`
+
+The current pattern:
+```scala
+val proto = ActionResult.parseFrom(payloadBlob)
+val scala = ActionResultProtoConverter.fromProto(proto)
+```
+
+The new pattern:
+```scala
+val scala = ActionResultDbReader.read(connection, actionSeq)  // assembles from action_results + child tables
+```
+
+`ActionResultDbReader.read` is one query per child table (or a single multi-result query with carefully ordered joins, though that has aggregation pitfalls). Per-table queries are simpler to write and SQLite query planning handles them well.
+
+For bulk reads (`since`, `all`, `sinceDate`, etc.), the existing `replayFrom` helper iterates action seqs in order, and currently parses one proto per action. The new equivalent runs one batched query per child table for the relevant action_seq range, materializing rows into a map keyed by action_seq, then walks the range emitting `ActionResultC` instances assembled from the maps. This is more code than the proto version but doesn't change the algorithmic shape.
+
+## Write path
+
+`withNewResults` becomes:
+1. INSERT into `action_results` (scalar fields).
+2. For each non-empty aggregate: INSERT N rows into the corresponding child table.
+
+All inside a single transaction. Per-action insert count is bounded by what the action does — most actions touch 0–3 provinces, 0–5 heroes, 0–10 changed entities total, plus 0–2 notifications. So the typical insert is ~5–20 rows. With WAL and a single per-batch transaction, this is cheap.
+
+## Replay performance
+
+Today's `replayFrom` parses one proto per action. Decomposed, each action requires per-child-table queries. For a 25-action replay between snapshots, that's still small absolute work — maybe 100–500 rows fetched from a handful of indexed tables. Should be faster than proto parsing once the JIT warms up, but won't matter either way at typical sizes.
+
+## Deleting the proto
+
+> **Superseded by refined option B (see Status).** Whole-`ActionResult` `payload` is removed in 4.5h. After that it depends on per-entity classification: *refined* entities' per-entity sub-message protos + converters (e.g. `changed_hero.proto`) **do** become dead code and are deleted in 4.5i; *deep* entities' whole-entity blob protos, the leaf protos used as Tier-3 blob payloads (e.g. `event_for_hero_backstory.proto`), and `Quest` are *retained*. The original full-deletion plan below is kept for historical context.
+
+Once `SqliteHistory` writes and reads exclusively from the new tables:
+
+1. Delete `ActionResultProtoConverter.scala`, the `Changed{Province,Hero,Faction,Battalion}Converter.scala` files, the `Notification`/`GeneratedTextRequest`/etc. converters.
+2. Delete the proto definitions: `action_result.proto`, `changed_province.proto`, `changed_hero.proto`, `changed_faction.proto`, `notification.proto`, `generated_text_request.proto`, anything else in this scope.
+3. Delete the corresponding `_scala_proto` Bazel targets.
+4. Gazelle should drop the unused deps from downstream targets.
+
+This is satisfying but should land *last*, after everything's stable. The proto files are dead code at that point — keeping them around for a PR or two while we verify migration is fine.
+
+## Sequencing
+
+**Phase 4** (cutover) lands as planned: `GamesManager` swaps to `SqliteHistory`, save dirs get nuked, action data is the single proto-blob `payload`. Days of work, validates the lifecycle integration without conflating with schema design.
+
+**Phase 4.5** (this design) starts after Phase 4 is verified stable. Subdivided into small PRs. **Re-planned for option B (see Status):** each entity gets the 4.5a scalar/entity-ref columns + a `<entity>_proto BLOB`; no child-table explosion. Each decomposition PR splits into `.1` (schema + backfill over existing `payload`) and `.2` (live `withNewResults` write path + read path), per the precedent set by 4.5b.
+
+| PR | Work | State |
+|---|---|---|
+| 4.5a | Schema-migration scaffolding + four changed-entity top-level tables (scalar columns) | ✅ merged |
+| 4.5b | `ChangedProvince`: scalar columns + `changed_province_proto BLOB` + v3 backfill (option B, #6725) | ✅ merged |
+| 4.5c.1 | `ChangedHero` (**refined option B**, see Status): 4.5a scalars + loyalty/vigor Tier-2 column pairs + `newBackstoryEvents` as per-event `EventForHeroBackstory` Tier-3 blobs in `action_changed_heroes_new_backstory_events`; **no whole-entity blob** — `changed_hero.proto`/`ChangedHeroConverter` become deletable, `event_for_hero_backstory.proto` retained. Schema v4 + backfill over existing `payload` (#6727) | ✅ merged |
+| 4.5c.2 | `ChangedHero`: live `withNewResults` write path + read path | planned |
+| 4.5d | `ChangedFaction`: same pattern (mostly scalar already; small/empty blob — see Decisions #2) | planned |
+| 4.5e | `ChangedBattalion`: `changed_battalion_proto BLOB` (sole field is the contained `BattalionT`) + battalion_id index from 4.5a | planned |
+| 4.5f | "New entity" vectors (`newProvinces`/`newHeroes`/`newFactions`/`newBattalions`): one table per type keyed by `(action_seq, entity_id)` + a couple of queryable handles + `<entity>_proto BLOB`. Biggest win for B — these are the deepest snapshots | planned |
+| 4.5g | Notifications + generated text requests: `(action_seq, n, kind, <entity>_proto BLOB)` — `kind` discriminator queryable, payload blobbed (quest-hybrid shape) | planned |
+| 4.5h | Top-level `ActionResultC` scalar/entity-ref columns on `action_results` (acting_hero_id, acting_faction_id, province_id, …) + **drop `payload BLOB`**. Read path = scalar columns + per-entity proto blobs (close to today's proto parse; simpler than the original per-table-join plan) | planned |
+| 4.5i | Delete proto files/targets that became dead code. *Refined* entities' per-entity protos + converters (e.g. `changed_hero.proto`/`ChangedHeroConverter`) **are deleted** here. *Deep* entities' protos + leaf Tier-3 protos (e.g. `event_for_hero_backstory.proto`) + `Quest` are **retained** as blob payloads. No longer near-nothing — scope scales with how many entities went *refined* | planned |
+
+Each PR nukes save dirs as part of its rollout (still pre-alpha). Each PR is independently reviewable and revertable. Under option B the per-PR cost is far lower than the original estimate (~110-line writer per entity, no child-table schema), so the remaining sequence is roughly **1 week**, not 3–4.
+
+After 4.5: Phase 5 (idle-game eviction) and Phase 6 (final cleanup) proceed as the parent design doc lays out.
+
+## What we gain at the end
+
+- **Single source of truth.** Action data lives in tables; no proto representation for the things in scope.
+- **Native SQL analytics.** Cross-game queries like "actions touching province X" or "all riots in year Y" are one-line SELECTs. No backfill code needed.
+- **Inspectable saves.** `sqlite3 game.db` shows readable data. Debugging is normal SQL work, not "parse this binary blob."
+- **Cleaner replay path.** No proto parsing during replay. The `ActionResultProtoConverter` (currently called per replayed action in `replayFrom`) goes away entirely.
+- **Less code.** ~7 proto files deleted; their generated Scala targets deleted; their converter classes deleted; the dual proto/Scala representation collapses to one.
+- **Schema migrations as a first-class concept.** Future field additions are SQL migrations, which is the right shape for a system that owns its storage.
+
+## What we lose
+
+- **The "edit one proto" workflow** for adding fields. Adding `newFooDelta: Double` to `ChangedProvinceC` is now a Scala edit + SQL migration step + converter update. More steps. Pre-alpha this is cheap; post-alpha (when migrations apply to real data) it's a careful PR but still bounded.
+- **A safety net for unrecognized fields.** Proto silently keeps unknown fields on parse; SQL doesn't. We accept this because we control both ends.
+
+## Decisions locked
+
+1. **Refined option B is the pattern (see "Refinement" in Status; rescinds both "fully relational, no blob fallback" and the original whole-entity-blob-per-entity rule).** Per entity, three tiers: scalar/entity-ref columns (Tier 1) + typed columns for sealed value-oneofs (Tier 2) + per-row leaf-proto blobs in child tables (Tier 3). A whole-entity `<entity>_proto BLOB` is used **only for deep entities** where Tiers 2–3 cost more than they're worth. No child-table explosion for deep aggregates.
+2. **Classify each entity: all-scalar / refined / deep (supersedes the old "is a blob needed").** *All-scalar* → Tier 1 only, no blob (likely `ChangedFaction`). *Refined* → Tiers 1–3, no whole-entity blob, per-entity proto deletable (`ChangedHero`). *Deep* → Tier 1 + whole-entity `<entity>_proto BLOB`, proto retained (`ChangedProvince`, new-entity snapshots). Default to *refined* for shallow entities; fall back to *deep* only when the residual is too varied for Tiers 2–3.
+3. **What's retained vs. deleted depends on the classification.** `action_results.payload` (the whole-`ActionResult` blob) still goes away in 4.5h. *Refined* entities' per-entity sub-message protos + converters become dead code, deleted in 4.5i; only the **leaf** protos they use as Tier-3 blob payloads (e.g. `event_for_hero_backstory.proto`) are retained. *Deep* entities' protos + `Quest` stay as whole-entity blob payloads. So 4.5i is no longer near-nothing.
+4. **Sub-phase ordering** as in the Sequencing table; each decomposition PR splits into `.1` (schema + backfill) and `.2` (live write + read).
+5. **Phase 4 landed separately, before 4.5a** (historical, unchanged). Cutover validated the lifecycle integration with the simpler schema before decomposition began.

docs/SQLITE_HISTORY_DESIGN.md

@@ -0,0 +1,291 @@
+# SQLite Game History Design
+
+## Why
+
+The current persistence layer is file-based: action results are chunked into `.e0a` files, individual results spill to `.e0i` files for crash recovery, state snapshots live in `.e0s` files, and a `directory.e0i` index tracks chunks. This shape has produced three workarounds in recent history:
+
+1. A `games.e0es` cache (PR #6706) to avoid re-reading the running-games list.
+2. Dual-storage in `PersistedActionResult` (proto bytes + parsed proto) to amortize serialization across save flushes.
+3. Lazy `gameState` (PR #6692) to avoid eager proto conversion on every replayed step, after PR #6691 fixed the `stateAfter` OOM that materialized ~4500 `PersistedActionResult` instances during a stale-LLM-replay path.
+
+Each is a workaround for the same root cause: file-based random access is expensive, so we cache aggressively, and the cache layers are fragile (one misplaced `.map(_.gameState)` reintroduces the OOM).
+
+The alternative — SQLite as a per-game container, with proto bytes stored as BLOB columns indexed by action sequence number — gives us random access by construction, removes the need for all three workarounds, and makes idle-game eviction cheap (rehydrate from the DB instead of reparsing files). The pattern is already in production here: `SqliteClientTextStore` does exactly this for the client text cache. We extend the same pattern to game history.
+
+## Goal & non-goals
+
+**In scope:**
+- Per-game SQLite container (`game.db`) holding action history, state snapshots, and shardok results.
+- A new `SqliteHistory` class implementing the existing `FullGameHistory` trait, drop-in replacement for `PersistedHistory` at the call site.
+
+**Out of scope (deferred or rejected):**
+- **Migration of existing saves.** Pre-alpha there are only two users and a handful of test games. Cheaper to nuke the existing save directories at cutover than to write and verify a migration importer. New games created post-cutover land in `game.db` directly; existing games are gone.
+- The top-level `games.e0es` running-games registry. Stays as-is; its cache (PR #6706) already works.
+- Idle-game eviction. Enabled by this work but lands in a follow-up phase after `SqliteHistory` is the authoritative path.
+- A shared cross-game analytics DB. Per-game design supports ad-hoc cross-game queries via iterate-and-aggregate; build the centralized analytics DB only if/when those queries become hot.
+
+## File layout
+
+`game.db` lives in the existing per-game save directory, alongside `text_store.db`:
+
+```
+${EAGLE_SAVE_DIR}/${gameIdHex}/
+├── game.db          # NEW — action history, snapshots, shardok results
+└── text_store.db    # existing — client text (SqliteClientTextStore)
+```
+
+Existing `.e0a` / `.e0s` / `.e0i` / `directory.e0i` files do not coexist with `game.db`: at cutover we nuke save directories one time. There is no migration path and no legacy-file fallback.
+
+### Why `game.db` and `text_store.db` are separate files (not tables in one DB)
+
+It's tempting to combine them — one file per game, one connection per game, one cloud-upload story. The reason not to: **writer-lock contention.** SQLite serializes writers per-database file. `SqliteClientTextStore` writes frequently during LLM streaming (one `UPDATE` per token append on `texts.text`). `SqliteHistory` writes per-action during turn commits. Combining them means an in-flight LLM token append can block a turn commit, or vice versa. Separate DBs have separate writer locks and never contend. Subsystem ownership (each package owning its own schema, independent migration paths if the schemas evolve) is a bonus.
+
+`Persister` integration follows the `SqliteClientTextStore` pattern: `game.db` is uploaded to / downloaded from cloud storage as a single opaque blob, keyed by the filename. On first load, if `game.db` is missing locally, try `persister.retrieveAsStream("game.db")`. If both are missing, this is a new game and we create an empty DB.
+
+## Schema
+
+```sql
+-- Action results, one row per action_result_index.
+CREATE TABLE action_results (
+    action_seq           INTEGER PRIMARY KEY,        -- 0-based, dense, never sparse
+    action_result_type   INTEGER NOT NULL,           -- denormalized for filtering
+    round_id             INTEGER NOT NULL,           -- denormalized for recentResultsForRound
+    date_year            INTEGER,                    -- denormalized for sinceDate; NULL pre-game-start
+    date_month           INTEGER,                    -- denormalized for sinceDate; NULL pre-game-start
+    payload              BLOB    NOT NULL            -- ActionResult proto bytes
+) WITHOUT ROWID;
+
+CREATE INDEX idx_action_results_round   ON action_results(round_id);
+CREATE INDEX idx_action_results_date    ON action_results(date_year, date_month);
+-- action_seq is the PK so no index needed there.
+
+-- State snapshots at chunk boundaries (and the starting state at seq 0).
+-- boundary_action_seq is the action_seq AFTER which the snapshot reflects state.
+-- The starting state lives at boundary_action_seq = 0 (state before any actions).
+CREATE TABLE state_snapshots (
+    boundary_action_seq  INTEGER PRIMARY KEY,
+    payload              BLOB    NOT NULL            -- GameState proto bytes
+) WITHOUT ROWID;
+
+-- Shardok per-battle results.
+CREATE TABLE shardok_results (
+    shardok_game_id      TEXT    NOT NULL,
+    action_seq           INTEGER NOT NULL,           -- 0-based within this shardok game
+    payload              BLOB    NOT NULL,           -- ShardokActionResult proto bytes
+    PRIMARY KEY (shardok_game_id, action_seq)
+) WITHOUT ROWID;
+
+-- Shardok per-game state (one row per shardok_game_id).
+CREATE TABLE shardok_state (
+    shardok_game_id      TEXT    PRIMARY KEY,
+    game_state           BLOB    NOT NULL,           -- ShardokGameState proto bytes
+    last_eagle_round_id  INTEGER NOT NULL
+) WITHOUT ROWID;
+
+-- Shardok per-player results (filtered ActionResultView per faction).
+CREATE TABLE shardok_player_results (
+    shardok_game_id      TEXT    NOT NULL,
+    faction_id           INTEGER NOT NULL,
+    seq                  INTEGER NOT NULL,
+    payload              BLOB    NOT NULL,           -- ShardokActionResultView proto bytes
+    PRIMARY KEY (shardok_game_id, faction_id, seq)
+) WITHOUT ROWID;
+
+-- Shardok per-player available commands (latest only, keyed by game + faction).
+CREATE TABLE shardok_player_commands (
+    shardok_game_id      TEXT    NOT NULL,
+    faction_id           INTEGER NOT NULL,
+    payload              BLOB,                       -- ShardokAvailableCommands proto bytes; NULL = no commands
+    PRIMARY KEY (shardok_game_id, faction_id)
+) WITHOUT ROWID;
+
+-- Schema version and starting state.
+CREATE TABLE metadata (
+    key                  TEXT    PRIMARY KEY,
+    value                BLOB    NOT NULL
+);
+-- Seeded with: schema_version=1
+```
+
+### Column rationale
+
+- **`action_seq`** as `INTEGER PRIMARY KEY` (the SQLite rowid alias) — densest possible storage and no separate index; range scans for `since(start)` are O(log n + result count).
+- **`WITHOUT ROWID`** on tables with synthetic keys to skip the implicit rowid column.
+- **Denormalized `action_result_type`, `round_id`, `date_year`, `date_month`** — these are the predicates the existing read paths use (`recentResultsForRound`, `sinceDate`). Keeping them as columns avoids parsing the proto blob to filter.
+- **No `created_at` timestamp** — wall-clock time isn't queried by the History trait, and game date (year/month) is what matters semantically.
+- **`payload BLOB`** — the proto bytes are the source of truth for the structured action result. Polymorphic action types make a relational schema painful for limited gain; the denormalized columns above cover the queries we need.
+- **Snapshots keyed by `boundary_action_seq`** — `stateAfter(N)` finds `MAX(boundary_action_seq) WHERE boundary_action_seq <= N`, returns that snapshot, replays forward `N - boundary_action_seq` actions. Snapshot at `0` is the game's starting state.
+
+### Snapshot strategy
+
+Match the existing `resultsPerSaveFile = 25` boundary: write a `state_snapshots` row every 25 actions. That gives the same replay-window cost as the current chunk-file design (`stateAfter(N)` replays at most 25 actions to reach an arbitrary point), and matches the cadence developers are already calibrated to.
+
+Snapshots are GameState proto bytes, identical in shape to today's chunk-file `startingState`. The migration importer derives them directly from the chunk files. New games write a snapshot after every 25th `withNewResults` action.
+
+## Connection lifecycle
+
+Mirror `SqliteClientTextStore`:
+
+- One `Connection` per loaded game, opened when `GamesManager` loads the game, closed when the game is evicted (future eviction work) or the server shuts down.
+- `Class.forName("org.sqlite.JDBC")` + `DriverManager.getConnection("jdbc:sqlite:${path}")` on open.
+- `PRAGMA journal_mode = WAL` on every connection open. WAL gives us crash-safe writes and lets readers proceed concurrently with the single writer — important because gRPC stream readers (humanPlayerClientConnectionState) query history mid-turn.
+- `PRAGMA synchronous = NORMAL` (the WAL-recommended setting; durability is preserved through WAL checkpoint).
+- `PRAGMA foreign_keys = ON` (defensive; we have no FKs today but cheap to enable).
+- Auto-commit on by default. Transactions explicitly opened for `withNewResults` (batch of action inserts + optional snapshot) and `truncateTo` (deletes across all tables).
+
+### Threading
+
+The current `PersistedHistory` is an immutable case class; `withNewResults` returns a new instance. `SqliteHistory` cannot be pure-immutable (the DB is mutable state) but should present the same interface: methods that "change" the history return `this` after a successful write. The underlying `Connection` is shared.
+
+JDBC `Connection` is not thread-safe in general; SQLite's JDBC driver serializes operations per-connection. Existing call sites already serialize writes through the `EngineApplier` flow, so single-threaded write access is preserved. Reads from gRPC stream readers can use the same connection — SQLite serializes them transparently, and WAL prevents read-write blocking.
+
+## Read paths
+
+How each `FullGameHistory` method maps to SQL:
+
+| Method | Query |
+|---|---|
+| `count` | `SELECT COALESCE(MAX(action_seq), -1) + 1 FROM action_results` (cached as a counter after the first read) |
+| `last` | `SELECT payload FROM action_results ORDER BY action_seq DESC LIMIT 1` + state from `stateAfter(count)` |
+| `all` | `SELECT payload FROM action_results ORDER BY action_seq` — used by `GameAdminServiceImpl.getActionDetail` to fetch one action by index. See follow-up note below. |
+| `since(start)` | `SELECT payload FROM action_results WHERE action_seq >= ? ORDER BY action_seq` |
+| `sinceDate(date)` | `SELECT payload FROM action_results WHERE (date_year, date_month) >= (?, ?) ORDER BY action_seq` |
+| `recentResultsForRound(round, pred)` | `SELECT payload FROM action_results WHERE round_id = ? AND action_seq > ? ORDER BY action_seq` where `?` is the cutoff matching current `recentHistory` semantics (last N actions, or all actions for the current round) |
+| `stateAfter(N)` | Find latest snapshot ≤ N, replay forward via `replayApplier` (same logic as `replayScalaOnlyToState`) |
+
+For methods that return `Vector[ActionResultWithResultingState]` (with resulting state per row): we **do not** materialize per-row gameStates. Instead, fold the actions through `replayApplier` starting from the latest snapshot ≤ start, producing the states on the fly. This matches what `formAwrs` does today, with one critical difference: no `PersistedActionResult` wrapper is allocated, and no proto-conversion is performed per step. This is the same shape as `replayScalaOnlyToState`, generalized to produce intermediate states.
+
+### `all()` follow-up
+
+`GameAdminServiceImpl.getActionDetail` is the one production caller. It fetches a single action by index from the full vector. Either of these is cheaper than materializing the whole history:
+
+- Replace the call site with `history.since(index).headOption`.
+- Add a new `actionAt(index): Option[ActionResultWithResultingState]` method and drop `all()` from the trait entirely.
+
+`SqliteHistory.all` will work — it's just `SELECT * ORDER BY action_seq` — but it's expensive (materializes the full history into memory), so we should switch the admin caller in a small follow-up PR. Not blocking the SQLite work.
+
+### `recentResultsForRound` semantics
+
+Today this filters `recentHistory` (the in-memory tail) by `roundId`. In SQLite there's no in-memory/persisted split — all results live in the DB. The semantics shift slightly: return all results matching `round_id` after a configurable cutoff. The cutoff should match today's behavior (results since the start of the current round, or some bounded recent window). Default to "all results with the given `round_id`," which is correct as long as `round_id` uniquely identifies a round across the game's history (it does, per the current `RoundId` model).
+
+## Write paths
+
+### `withNewResults(newResults)`
+
+In a transaction:
+1. `INSERT INTO action_results (action_seq, action_result_type, round_id, date_year, date_month, payload) VALUES ...` — one row per new result. Use `addBatch()` for multiple.
+2. For each new result whose `action_seq % 25 == 0` (snapshot boundary), `INSERT INTO state_snapshots(boundary_action_seq, payload) VALUES (?, ?)` with the GameState proto bytes.
+3. Commit.
+
+The denormalized columns (`action_result_type`, `round_id`, `date_year`, `date_month`) are extracted from the action's resulting state at insert time. They are immutable once written; if the schema interpretation changes, a migration is required.
+
+The "individual result for crash recovery" pattern (`.e0i` files) is replaced by: the action result is durably written when the transaction commits. WAL gives us atomicity per transaction. No separate crash-recovery file is needed.
+
+### `saveNow`
+
+Becomes a no-op in normal operation — writes are already durable per `withNewResults` commit. We keep the method on the trait for API compatibility but the implementation just returns `this`. (We could call `PRAGMA wal_checkpoint(TRUNCATE)` here to roll the WAL into the main DB file, useful before cloud upload; defer this until we measure WAL growth.)
+
+### `truncateTo(targetActionCount)`
+
+In a transaction:
+1. `DELETE FROM action_results WHERE action_seq >= ?`
+2. `DELETE FROM state_snapshots WHERE boundary_action_seq > ?`
+3. Shardok cleanup: `DELETE FROM shardok_results / shardok_state / shardok_player_results / shardok_player_commands WHERE shardok_game_id NOT IN (...)` (the set of battles still outstanding at the truncate point; mirrors `deleteOrphanedShardokFiles`).
+4. Commit.
+
+`truncateTo(0)` resets the game; everything after the starting-state snapshot is deleted.
+
+## Shardok results
+
+The shardok subsystem currently lives in `.e0s` files (one per battle, full per-battle state). It's loaded selectively at game-load time, only for outstanding battles (see `PersistedHistory.apply` line 248-256).
+
+Moving to SQLite, the four shardok tables above capture:
+- `shardok_results` — the per-battle result stream
+- `shardok_state` — current per-battle state (one row per battle)
+- `shardok_player_results` — per-faction filtered views
+- `shardok_player_commands` — current available commands per faction
+
+`withNewShardokResults` writes to all four in a transaction. `shardokCount`, `shardokGameState`, etc., become single-row indexed lookups.
+
+The selective-load optimization disappears with SQLite: we don't proactively read anything; queries hit the DB on demand. The "load only outstanding battles" logic is replaced by "query by `shardok_game_id` when needed."
+
+## Crash recovery
+
+WAL replaces the `.e0i` individual-result-file mechanism. On startup:
+- WAL is automatically replayed by SQLite if the previous shutdown was unclean. No application code needed.
+- A successful commit means durable; an interrupted commit means rolled back. No half-written state visible.
+
+The current "orphaned individual results on load" path (`loadIndividualResults` in `PersistedHistory.apply`) is gone.
+
+## Cutover
+
+No migration path. At cutover:
+
+1. Stop the server.
+2. Nuke the contents of `${EAGLE_SAVE_DIR}` (and `${EAGLE_ARCHIVE_DIR}` if there's anything there).
+3. Deploy.
+4. New games created post-deploy land in `game.db` directly.
+
+Pre-alpha there are only two users and a handful of test games; a one-time nuke is cheaper than a verified migration importer. Trade-off accepted by the user explicitly.
+
+### Testing strategy (no migration)
+
+Without migration, we don't need equivalence-vs-`PersistedHistory` testing. The correctness gate becomes:
+
+1. **Adapt `PersistedHistoryTest`** to run against `SqliteHistory` instead. The 890-line existing test suite covers the trait surface exhaustively. Same assertions, new implementation under test.
+2. **Property-style end-to-end test**: create a synthetic game, run N batches of `withNewResults`, verify that `since(start)`, `stateAfter(N)`, `sinceDate(date)`, `recentResultsForRound`, `truncateTo`, etc., all produce expected values. Run with a deterministic random seed.
+3. **Manual smoke test in dev**: start a fresh game, play several turns, restart the server, verify saves persist and replay correctly.
+
+## Cloud-storage integration
+
+`Persister.save(key, bytes)` and `persister.retrieveAsStream(key)` already handle local-vs-S3 transparently. `SqliteClientTextStore` integrates by treating `text_store.db` as a single binary blob: upload after writes, download before reads.
+
+`SqliteHistory` will do the same with `game.db`:
+- **On load:** if local `game.db` missing, try to download via `persister.retrieveAsStream("game.db")`. Fall back to migration from `.e0a` if both are missing.
+- **On save:** after a meaningful change (turn boundary? configurable cadence?), upload the current `game.db` file to S3. Need to decide the upload trigger — too frequent and we burn S3 PUTs; too rare and crash recovery is lossy.
+
+**Open question:** the right upload cadence. Today, chunk saves trigger cloud upload at chunk boundaries (every 25 actions). The simplest match: keep that cadence, upload `game.db` once per chunk boundary. We could be smarter (only upload if WAL has been checkpointed; only upload deltas) but those are optimizations.
+
+## What the trait-level cutover looks like
+
+`GamesManager` currently has roughly:
+
+```scala
+val history: FullGameHistory = PersistedHistory(gameId, persister).getOrElse(...)
+```
+
+Becomes:
+
+```scala
+val history: FullGameHistory = SqliteHistory.loaded(gameId, persister)
+```
+
+Every other consumer of `FullGameHistory` is unchanged.
+
+## Decisions locked
+
+1. **Per-game `game.db`** (not shared across games).
+2. **`game.db` and `text_store.db` stay separate files** (not combined into one DB). Writer-lock contention is the deciding factor.
+3. **No migration** of existing saves. Nuke save directories at cutover. Pre-alpha trade-off accepted by the user.
+4. **No feature flag.** Cutover is unconditional. Failures are loud.
+5. **Cloud upload cadence**: match the existing 25-action chunk cadence. Upload `game.db` once per snapshot boundary.
+6. **`recentResultsForRound`**: return all results for the given round (no recent-window cap). The `round_id` predicate bounds the scan naturally.
+7. **WAL checkpointing**: rely on SQLite's auto-checkpoint. Add explicit `PRAGMA wal_checkpoint` only if WAL file growth becomes a problem.
+8. **Schema versioning**: seed `metadata` with `schema_version = 1`. Schema migration mechanism deferred until we need a v2.
+9. **`history.all`**: keep on the trait for now; admin call site moved to `since(i).headOption` (or a new `actionAt(i)` method) in a small follow-up PR. Not blocking.
+
+## Phase plan (revised)
+
+| Phase | Work | Estimate |
+|---|---|---|
+| 0 | This design doc | 2-3 days (in flight) |
+| 1 | `SqliteHistory` schema + write paths + tests adapted from `PersistedHistoryTest` | ~1 week |
+| 2 | Read paths + full test parity | ~1 week |
+| 3 | Shardok results integration | 3-5 days |
+| 4 | Cutover in `GamesManager` (nuke `${EAGLE_SAVE_DIR}` as part of deploy) | 2-3 days |
+| 5 | Idle-game eviction | 3-5 days |
+| 6 | Post-alpha cleanup (delete `PersistedHistory`, `PersistedActionResult`, `PartialGameUtils`, the chunk-file save code, `games.e0es` cache if no longer needed) | 1-2 days |
+
+**Total: ~3-4 weeks** (down from 5-6 — migration and equivalence-testing dropped).
+
+The follow-up to migrate `GameAdminServiceImpl.getActionDetail` off `history.all` is a small, independent PR that can land any time.

docs/TUTORIAL_BATTLE_SYSTEM.md

@@ -32,7 +32,7 @@ When a new player starts their first game in tutorial mode, they experience:
   - 1x Heavy Cavalry (600 troops, 80 training/armament)
   - 1x Heavy Infantry (500 troops, 80 training/armament)
   - 1x Longbowmen (300 troops, 80 training/armament)
-- **Origin Province**: 32
+- **Origin Province**: 31
 
 ### Flee Trigger
 Attacker flees when ANY of these conditions are met:

docs/TUTORIAL_SYSTEM.md

@@ -0,0 +1,322 @@
+# Tutorial System Architecture
+
+This document describes how the Unity client's tutorial system is wired together: the classes involved, the trigger catalog, the step lifecycle, and the expected first-session flow. It complements two existing docs:
+
+- **`TUTORIAL_CONTENT.md`** — human-facing copy for tutorial steps and dialogues
+- **`TUTORIAL_BATTLE_SYSTEM.md`** — the scripted first-battle scenario (Tarn vs. John Ranil)
+
+It also overlaps slightly with the in-tree `Assets/Tutorial/TUTORIAL_PLAN.md`, which is an older implementation plan.
+
+All paths below are relative to `src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/`.
+
+---
+
+## Current State (important)
+
+There are **two parallel subsystems** that share the same trigger plumbing:
+
+| Subsystem | Status | Lives in |
+|-----------|--------|----------|
+| Step-based tutorial UI (modals, overlays, hints) | **Dormant** | `Tutorial/TutorialManager.cs`, `Tutorial/UI/*`, `Tutorial/Content/*` |
+| Narrative dialogue system | **Live** | `Tutorial/Dialogue/*`, `Resources/Dialogues/*.json` |
+
+`TutorialContentDefinitions.RegisterAll()` returns early at line 17 with the comment *"Old tutorial content suppressed — replaced by narrative dialogue system."* As a result:
+
+- `OnboardingSequence` is never assigned, so `StartOnboarding()` no-ops at the "No onboarding sequence assigned" branch.
+- No contextual tutorial sequences are registered with the trigger registry.
+- The trigger registry still fires events normally, but nothing on the step-UI side is listening.
+- `DialogueManager` consumes those same events and matches them against scripts in `Resources/Dialogues/` (`tutorial_strategic.json`, `tutorial_battle.json`).
+
+**In practice today, the entire active tutorial experience runs through the dialogue system.** The step-UI machinery is preserved for future use — content definitions still exist below the early return in `TutorialContentDefinitions.cs` for reference.
+
+---
+
+## Class Map
+
+### Orchestration
+- **`Tutorial/TutorialManager.cs`** — Singleton. Owns `OnboardingSequence`, the active step queue, the trigger registry, and the dialogue manager handle. Initialized by `EagleGameController.SetUpGame()` and `ShardokGameController.SetUpGame()`.
+- **`Tutorial/TutorialState.cs`** — PlayerPrefs persistence. Tracks `OnboardingCompleted`, `OnboardingStepReached`, completed sequence IDs (HashSet for O(1) lookup), dismissed hints, and a global "tutorials disabled" preference.
+- **`Tutorial/TutorialTargetRegistry.cs`** — Maps string IDs to `RectTransform`s for highlighting. Static targets are Inspector-assigned (`ProvinceInfoPanel`, `SupportField`, `CommitButton`, etc.); dynamic targets register at runtime (e.g., hero rows from `HeroesAndBattalionsPanelController`).
+
+### Triggers
+- **`Tutorial/Triggers/TutorialTriggerRegistry.cs`** (~1100 lines) — Routes game events to both the step UI (when sequences are registered) and `DialogueManager`. Maintains one-shot session flags so the same first-encounter trigger doesn't fire twice.
+
+### Content (step UI — dormant)
+- **`Tutorial/Content/TutorialStep.cs`** — Per-step record: `DisplayMode`, `CompletionType`, target path, copy, panel anchor, highlight options.
+- **`Tutorial/Content/TutorialSequence.cs`** — `ScriptableObject` holding ordered `TutorialStep`s plus `IsOnboarding` flag and lifecycle callbacks.
+- **`Tutorial/Content/TutorialContentDefinitions.cs`** — Static class that *would* register all sequences. Currently short-circuits before any registration.
+
+### UI (step UI — dormant)
+- **`Tutorial/UI/TutorialUIManager.cs`** — Coordinates which presenter renders each step.
+- **`Tutorial/UI/TutorialCanvasBuilder.cs`** — Builds the Canvas at runtime (no prefab dependency).
+- **`Tutorial/UI/TutorialModalPanel.cs`** — Full-screen blocking modal.
+- **`Tutorial/UI/TutorialOverlayController.cs`** + **`TutorialOverlayBuilder.cs`** — Dimmer with highlighted cutout, gold border, pulsing animation, and adjacent tooltip text.
+- **`Tutorial/UI/TutorialHintIndicator.cs`** — Stub for pulsing-dot mode.
+
+### Dialogue (live)
+- **`Tutorial/Dialogue/DialogueManager.cs`** — Loads all `Resources/Dialogues/*.json` scripts at startup, indexes by trigger ID, drives the panel.
+- **`Tutorial/Dialogue/DialogueScript.cs`** / **`DialogueStep.cs`** — JSON-shaped records for scripts and steps.
+- **`Tutorial/Dialogue/DialoguePanelController.cs`** — Renders the speaker headshot, body text, instruction line, optional highlight target, and Continue button.
+- **Scripts:** `Assets/Resources/Dialogues/tutorial_strategic.json`, `tutorial_battle.json`.
+
+---
+
+## Step Lifecycle (Step-UI System)
+
+1. **Triggered** — `TutorialTriggerRegistry` raises an event (e.g., `game_started`, `battle_entered`).
+2. **Queued or shown** — If no active sequence, show immediately. If an active step is hidden (`DisplayMode.None`), interrupt it. If both new and active are command tutorials, interrupt for responsiveness. Otherwise queue.
+3. **Rendered** — `TutorialUIManager.ShowCurrentStep()` dispatches to the modal/overlay/hint presenter based on `DisplayMode`.
+4. **Awaiting completion** — One of:
+   - `ButtonClick` — user dismisses
+   - `GameEvent` — wait for a named event (e.g., `province_selected`)
+   - `Timer` — auto-advance after delay
+   - `UIInteraction` — wait for the highlighted target to be interacted with
+   - `Condition` — custom predicate (rare)
+5. **Advance** — `AdvanceStep()` moves to the next step or completes the sequence; completion writes to `TutorialState`.
+
+Hidden steps (`DisplayMode.None`) deliberately don't block — they exist so contextual tutorials can fire while the onboarding sequence is waiting on an async event.
+
+---
+
+## Display Modes
+
+| Mode | Renderer | Notes |
+|------|----------|-------|
+| **Modal** | `TutorialModalPanel` | Full blocking dialog with dim background |
+| **Overlay** | `TutorialOverlayController` | Dimmer with cutout + tooltip near a target |
+| **Tooltip** | `TutorialOverlayController` | Currently same renderer as overlay |
+| **Hint** | `TutorialHintIndicator` | Pulsing dot only (stub) |
+| **None** | (invisible) | Waits for a completion event |
+
+Panels can be anchored via `TutorialPanelAnchor` (`Center` / `Left` / `Right` / `Top` / `Bottom`).
+
+---
+
+## Trigger Catalog
+
+All triggers are raised via `TutorialTriggerRegistry`. Today these flow to `DialogueManager.TriggerDialogue()` and are matched against the dialogue JSON; if step-UI sequences are re-registered, they will also route there. File:line citations are for the registry unless noted; line numbers may drift.
+
+### Bootstrap / first-session
+| Trigger | Fires from | When |
+|---------|-----------|------|
+| `game_started` | `EagleGameController.SetUpGame()` | First time entering a tutorial game |
+| `first_battle_available` | `OnModelUpdated()` ~L204 | A `RunningShardokGameModel` first appears |
+| `battle_entered` | `OnBattleEntered()` ~L793 | User clicks **Battle!** |
+| `tutorial_battle_ended` | `CheckTutorialBattleEnded()` ~L594 | Tutorial battle removed from running models |
+| `tutorial_rebuild_support` | `CheckTutorialRebuildSupport()` ~L616 | Captured-heroes phase done |
+| `tutorial_taxes_collected` | `CheckTaxesCollected()` ~L680 | New Year action with positive tax delta |
+| `tutorial_in_town` | `CheckInTown()` ~L500 | Return command becomes available |
+
+### Strategic-map contextual
+| Trigger | Site | When |
+|---------|------|------|
+| `province_selected` | `EagleGameController.ProvinceWasSelected()` | Province click |
+| `command_issued` | `EagleGameController.PostCommittedCommand()` | User commits |
+| `diplomacy_available` | `CheckStrategicCommandsAvailable()` ~L243 | Diplomacy command appears |
+| `weather_control_available` | `CheckStrategicCommandsAvailable()` ~L249 | Weather command appears |
+| `hero_recruitment_available` | `CheckHeroRecruitmentAvailable()` ~L266 | Free heroes detected |
+| `tutorial_ready_to_join` | `CheckReadyToJoinHero()` ~L479 | Free hero with `WouldJoin` |
+| `profession_<X>_encountered` | `CheckProfessionTutorial()` ~L726 | First time seeing each profession |
+
+### Strategic guidance (state-derived, conditions checked each model update)
+| Trigger | Site | Condition |
+|---------|------|-----------|
+| `guidance_loyalty_danger` | `CheckLoyaltyDanger()` ~L339 | November + hero loyalty < 70 |
+| `guidance_neighbor_danger` | `CheckNeighborDanger()` ~L383 | Hostile faction adjacent |
+| `guidance_recruit_heroes` | `CheckRecruitHeroesGuidance()` ~L420 | Province with support ≥40 has free heroes |
+| `guidance_expand` | `CheckExpandGuidance()` ~L449 | One stable province, hasn't expanded |
+| `guidance_sworn_kinship` | `CheckSwornKinshipGuidance()` ~L549 | Good candidate or 4+ provinces |
+| `tutorial_loyalty_warning` | `CheckTutorialLoyaltyWarning()` ~L634 | November + hero loyalty < 70 |
+| `tutorial_support_deadline` | `CheckTutorialSupportDeadline()` ~L654 | December + province support < 40 |
+
+### Strategic action-result triggers (fired from `OnStrategicActionResult()`)
+| Trigger | Site | When |
+|---------|------|------|
+| `hero_stat_gained` | ~L281 | `HeroStatGained` action result |
+| `hero_profession_gained` | ~L284 | `ProfessionGained` action result |
+| `tutorial_faction_appears` | ~L287 | `TutorialFactionAppears` action — the Fracture Covenant landing |
+| `tutorial_hero_faction_appears` | ~L290 | `TutorialHeroFactionAppears` action (no dialogue script today) |
+| `tutorial_hero_departed` | ~L299 | First `HeroesDeparted` action against another player (King's hero abandons service) |
+| `tutorial_hero_departed_again` | ~L302 | Second `HeroesDeparted` in a *different* month than the first |
+
+### Tactical (battle) — abilities and spells
+Combat triggers are *paced*: `_combatTutorialPending` ensures only one fires per action, with priority `archery > duel > melee > charge > fire`.
+
+| Trigger | Site | When |
+|---------|------|------|
+| `shardok_placement_started` | `OnBattleEntered()` ~L796 | Battle in setup phase |
+| `shardok_battle_started` | `OnBattleEntered()` ~L793 | Battle begins |
+| `shardok_battle_running` | `OnTacticalCommandsAvailable()` ~L948 | Player's first turn |
+| `archery_available` | `OnTacticalCommandsAvailable()` ~L990 | Archery available |
+| `melee_available` | `OnTacticalCommandsAvailable()` ~L991 | Melee available |
+| `duel_available` | `OnTacticalCommandsAvailable()` ~L1005 | Duel available (non-Tarn target) |
+| `ability_charge_available` | `OnTacticalCommandsAvailable()` ~L1001 | Charge for Old Marek |
+| `start_fire_available` | `OnTacticalCommandsAvailable()` ~L1021 | Start Fire on enemy |
+| `hide_available` | `OnTacticalCommandsAvailable()` ~L985 | Hedrick can hide |
+| `thunderstorm` | `OnTacticalCommandsAvailable()` ~L1056 | Weather is thunderstorm |
+| `spell_lightning_available` | `OnTacticalCommandsAvailable()` ~L960 | Lightning available |
+| `spell_meteor_available` | `OnTacticalCommandsAvailable()` ~L963 | Meteor available |
+| `spell_holywave_available` | `OnTacticalCommandsAvailable()` ~L965 | Holy Wave available |
+| `spell_raisedead_available` | `OnTacticalCommandsAvailable()` ~L969 | Raise Dead available |
+| `spell_lightning_cast` / `spell_meteor_cast` / `spell_holywave_cast` / `spell_raisedead_cast` | `CheckTacticalActionType()` ~L830-838 | Spell action observed |
+| `ability_charge_used` | `CheckTacticalActionType()` ~L842 | Charge attack executed |
+| `terrain_fire_encountered` | `CheckTacticalActionType()` ~L864 | Fire damage / spread |
+| `terrain_water_encountered` | `CheckTacticalActionType()` ~L867 | Water crossing |
+| `engineer_near_enemy` | `CheckEngineerNearEnemy()` ~L1105 | John Ranil within 3 hexes of enemy |
+| `tutorial_reinforcement_engineer` / `tutorial_reinforcement_paladin` | `CheckTacticalActionType()` ~L857 | Reinforcement arrival |
+| `friendly_hero_captured` | `CheckHeroRemovals()` ~L919 | Friendly hero unit removed |
+| `enemy_hero_captured` | `CheckHeroRemovals()` ~L928 | Enemy hero unit removed |
+| `battle_action` | `ShardokGameController.OnBattleAction()` | Any action result |
+| `turn_ended` | `ShardokGameController.OnTurnEnded()` ~L1137 | Battle turn ends |
+| `shardok_battle_reset` | `ShardokGameController.cs:627` (fired *directly* to `DialogueManager`, bypassing the registry) | Battle retry; the registry's battle flags and the battle dialogue scripts' completed-set are reset alongside, so per-battle tutorials re-fire |
+
+### One-shot semantics
+Most contextual triggers are guarded by booleans on the registry (e.g., a `_diplomacyShown` flag). These are session-local — they don't persist via `TutorialState`, but the registry has `ResetBattleTriggerFlags()` for replays. The strategic completion list *does* persist across sessions.
+
+---
+
+## Highlight Targets
+
+Steps reference UI by string ID through `TutorialTargetRegistry`:
+
+1. Static targets are wired in the Inspector on the registry.
+2. Dynamic targets register at runtime (`RegisterTarget(id, rectTransform)`).
+3. Lookup falls back to `GameObject.Find()` if not registered.
+
+Step options:
+- `TargetGameObjectPath` — primary highlight
+- `AdditionalHighlightTargets[]` — multiple at once
+- `HighlightBoundsFromChildren` — use children's bounding box
+- `HighlightPulsing` — strobe animation
+
+Dialogue scripts use the same registry via `highlightTarget` (and `persistHighlight: true` to keep the highlight after the dialogue closes).
+
+---
+
+## Sequences vs. Contextual Dispatch
+
+- **Onboarding sequence** (`IsOnboarding = true`) — Single linear sequence, started by `StartOnboarding()`. Resumes from `OnboardingStepReached`. Counts only visible steps for progress.
+- **Contextual** (`IsOnboarding = false`) — Single- or multi-step, dispatched on demand by `TriggerContextualTutorial()`.
+- Dispatch rules in `TriggerContextualTutorial()`:
+  1. No active sequence → show immediately.
+  2. Active step is hidden (`None`) → interrupt.
+  3. Both are command tutorials → interrupt.
+  4. Otherwise → queue.
+
+---
+
+## Dialogue System (Currently Live)
+
+`DialogueManager` is a parallel system, not a step-UI subclass. It loads every `TextAsset` in `Resources/Dialogues/` at startup, parses them as `DialogueScript` objects, and indexes by `trigger`.
+
+Script shape (see `tutorial_strategic.json`):
+```json
+{
+  "scripts": [{
+    "id": "tutorial_opening",
+    "trigger": "game_started",
+    "panelPosition": null,
+    "steps": [{
+      "speakerName": "Old Marek the Learned",
+      "speakerImagePath": "fixed/old_marek_the_learned.png",
+      "dialogueText": "...",
+      "instructionText": "Click Battle! to enter tactical combat.",
+      "highlightTarget": "GoToBattleButton",
+      "persistHighlight": true,
+      "highlightProvince": "Onmaa",
+      "completionEvent": null
+    }]
+  }]
+}
+```
+
+When a registry trigger fires, `OnGameEvent()` calls `DialogueManager.TriggerDialogue(triggerId)`. If a script matches and hasn't completed, it queues (or shows immediately) and the panel renders speaker headshot + body + instruction. Steps can pause for a `completionEvent` (e.g., wait for the player to click the highlighted button), allowing the dialogue to chain across game state changes.
+
+Dialogue panel position defaults sensibly per scene (`top` during combat) and can be overridden per script.
+
+---
+
+## Persistence
+
+`TutorialState` (PlayerPrefs JSON):
+- `OnboardingCompleted` (bool)
+- `OnboardingStepReached` (int)
+- `CompletedTutorials` (List → HashSet at load)
+- `DismissedHints` (List → HashSet at load)
+- `AllTutorialsDisabled` (bool)
+
+Reset paths:
+- `TutorialState.Reset()` clears everything.
+- Entering a tutorial game (`GameType.Tutorial`) resets so it can be replayed.
+- Settings → "Reset Tutorials" calls `TutorialManager.ResetAllProgress()`, which also calls `DialogueManager.ResetCompletedScripts()`.
+
+`DialogueManager` tracks completed scripts in memory only — they reset whenever `TutorialState` does.
+
+---
+
+## Bootstrap
+
+1. `TutorialManager` is in the scene as a singleton; `Awake` loads state and creates the trigger registry. `RegisterAll()` is called here but currently no-ops.
+2. `ConnectionHandler` sets `IsTutorialGame` and `IsMultiplayerGame` when the game is created/joined.
+3. `EagleGameController.SetUpGame()` calls `TutorialManager.Instance.Initialize(this, null)`. If `IsTutorialGame && !OnboardingCompleted`, it would call `StartOnboarding()` — currently a no-op because `OnboardingSequence` is null.
+4. The first model update raises `game_started`. `DialogueManager` matches `tutorial_opening` from `tutorial_strategic.json` and the dialogue runs.
+5. `ShardokGameController.SetUpGame()` calls `TutorialManager.Instance.Initialize(null, this)` when battle starts; raises `battle_entered` and battle-only triggers from there.
+
+---
+
+## Expected Tutorial Flow (today)
+
+Driven by `tutorial_strategic.json` + `tutorial_battle.json`. Old Marek the Learned narrates almost everything.
+
+### Narrative arc
+
+You play **Sadar Rakon**, formerly Ikhaan Tarn's most trusted lieutenant. Tarn's behavior grew erratic, the King wouldn't listen, so Sadar broke off and raised the **Reclamation**. He's been pushed back to **Onmaa** for a last stand against Tarn's superior royal army. After surviving, the real twist arrives: a new invasion — **The Fracture Covenant**, led by a mysterious figure called *The Eagle* — lands ships on the western coast and starts taking provinces. Heroes from the King's own service mysteriously begin to desert. The Reclamation's framing pivots from "rebellion" to "the only force that can stop the actual invasion."
+
+### Strategic-map flow (`tutorial_strategic.json`)
+
+| # | Trigger | What happens |
+|---|---------|--------------|
+| 1 | `game_started` | **Opening monologue** (3 steps): Sadar's backstory, the Reclamation, last stand at Onmaa. Ends highlighting the **Battle!** button (`persistHighlight`) |
+| 2 | `tutorial_battle_ended` | **Aftermath**: Tarn has *vanished*; you've captured his lieutenants. Recruit them or hold them |
+| 3 | `tutorial_rebuild_support` | **Rebuild Onmaa** (3 steps): Marek frames it; **John Ranil** introduces *Improve* (engineer bonus); **Elena Fyar** introduces *Give Alms* (paladin bonus). Goal: 40 support by January |
+| 4 | `tutorial_loyalty_warning` | November-ish, low-loyalty hero may leave at year end → use *Give Gold* / *Feast* |
+| 5 | `tutorial_support_deadline` | December nag if support < 40: have Elena give alms now |
+| 6 | `guidance_expand` (script `tutorial_expansion`) | Once support is stable: keep developing, taxes coming in January |
+| 7 | `tutorial_taxes_collected` | January: gold/food collected. Now expand — March your warlord + most heroes to a neighbor, leave 1–2 behind |
+| 8 | `tutorial_ready_to_join` | A free hero in `{provinceName}` is ready to recruit → Travel + Recruit |
+| 9 | `tutorial_in_town` | When you Travel: explains Trade / Arm Troops / Divine / Recruit / Manage Prisoners; *Return* ends the turn |
+| 10 | `tutorial_faction_appears` | **The twist**: Fracture Covenant lands at Ingia and Soria. *The Eagle* commands them. Tarn may be with them |
+| 11 | `tutorial_hero_departed` | First King's hero abandons service — "something deeper is at work" |
+| 12 | `tutorial_hero_departed_again` | Second one in a different month — "something is wrong, I can feel it" (foreshadowing) |
+
+### Tactical battle flow (`tutorial_battle.json`)
+
+| # | Trigger | What happens |
+|---|---------|--------------|
+| 1 | `shardok_placement_started` | **Placement** (3 steps): identify Tarn's units (knights, heavy infantry, dragoons), color legend (red/blue/black), placement instructions, highlight Commit |
+| 2 | `shardok_battle_running` | **Turn 1 strategy** (2 steps): victory conditions for both sides, advice to hold castles and End Turn |
+| 3 | `archery_available` | First archery opportunity → purple outlines, longbows vs. armor |
+| 4 | `melee_available` | First melee opportunity → right-click adjacent enemy |
+| 5 | `ability_charge_available` | Charge mechanics (Marek hams it up: "old scholar without a horse") |
+| 6 | `start_fire_available` | Start Fire on enemy hex, fire spread mechanics |
+| 7 | `thunderstorm` | Weather: archery disabled, fires extinguished |
+| 8 | `tutorial_reinforcement_paladin` | **Elena Fyar arrives** mid-battle (2-step exchange) → Paladin profession intro (Holy Wave) |
+| 9 | `tutorial_reinforcement_engineer` | **John Ranil arrives** (2-step exchange) → Engineer profession intro |
+| 10 | `engineer_near_enemy` | Once Ranil is close to enemy: Fortify + Reduce (siege bombardment) |
+| 11 | `duel_available` | Champion duel mechanics (Marek warns *not* to duel Tarn himself) |
+| 12 | `hide_available` | Hedrick the Hedge-merchant: forest/swamp Hide + ambush |
+| 13 | `enemy_hero_captured` / `friendly_hero_captured` | Capture mechanics, with `{heroName}` substitution |
+| 14 | `shardok_battle_reset` | If you lose and replay: Marek "had the strangest sensation… as though we'd already fought this battle, and lost" — fourth-wall-adjacent retry framing |
+
+Most remaining "Tutorial / first-session onboarding" items in `SMALL_EAGLE_TODO.md` (Shardok tutorial, narrative hook, first-session goal, early small victory, guided first scenario vs. sandbox) map to *adding new dialogue scripts* against existing trigger IDs, or — if the step-UI is revived — to populating `TutorialContentDefinitions.RegisterAll()` and removing the early return.
+
+---
+
+## Notable Behaviors and Gotchas
+
+- **`IsTutorialGame` gates everything.** Outside tutorial games, both subsystems short-circuit early.
+- **Combat tutorials are deliberately paced.** Don't expect every available-ability trigger to fire on its first eligible turn — the registry intentionally spaces them.
+- **One-shot flags are session-local.** A trigger that "already fired" will not re-fire even if `TutorialState` is reset, until the registry is recreated.
+- **`TutorialTargetRegistry` lookups silently fall back to `GameObject.Find`.** Typos in target IDs will render with no highlight rather than throwing.
+- **`TutorialContentDefinitions.RegisterAll()` returning early is load-bearing.** If the step UI is revived without auditing trigger overlap, dialogue and step-UI tutorials may double-fire on the same trigger.
+- **`Tutorial/TUTORIAL_PLAN.md`** in the Unity project is an older implementation plan and partially overlaps this doc.

docs/TWO_STAGE_ANIMATIONS.md

@@ -0,0 +1,19 @@
+# Two-Stage Animation Implementation Pattern
+
+Actions with server-determined success/failure outcomes use a two-stage system:
+1. **Attempt phase**: Animation + sound plays immediately when the command is issued
+2. **Result phase**: A distinct success or failure animation + sound plays when the server responds
+
+## Adding a New Two-Stage Action
+
+To add distinct success/failure animations for an action (using `ExtinguishFire` as an example):
+
+1. **AnimationType enum** (`ShardokGameController.cs`): Add `ExtinguishFireFailed`
+2. **AnimationTypeForAction()**: Map `ActionType.ExtinguishFireFailed` to new type
+3. **AttemptAnimationType()**: Map `ExtinguishFireFailed` back to `ExtinguishFire`
+4. **ActionTypeForSound()**: Map new type to `ActionType.ExtinguishFireFailed`
+5. **PlayAnimation()**: Add dispatch case calling the new animator method
+6. **Animator**: Add `AnimateExtinguishFailed()` method
+7. **SoundManager**: Ensure result sound is mapped (usually already done)
+
+See FearAnimator and FleeAnimator for reference implementations.

docs/UNITY_SCENE_SEPARATION_PLAN.md

@@ -0,0 +1,197 @@
+# Unity Scene Separation Plan
+
+## Current State
+
+The Unity client currently has both a large legacy scene and an unfinished split-scene setup.
+
+- `Assets/Gameplay.unity` is still the production-sized monolithic scene. It contains connection/lobby UI, Eagle strategic UI, Shardok tactical UI, shared UI, camera/event-system objects, and miscellaneous persistent controllers.
+- `Assets/Scenes/Main.unity`, `Connection.unity`, `Eagle.unity`, `Shardok.unity`, and `Shared.unity` already exist, but they are small shell scenes.
+- `ProjectSettings/EditorBuildSettings.asset` includes both `Assets/Gameplay.unity` and the split scenes.
+- `Assets/UI/Scripts/BootstrapManager.cs` is explicitly transitional and currently defaults to loading `Gameplay` additively through `useOriginalGameplayScene = true`.
+- Additional migration notes exist under `Assets/SCENE_SEPARATION_PLAN.md`, `Assets/Scenes/README.md`, and `Assets/NEXT_STEPS.md`, but there is no repo-level plan in `docs/`.
+
+This means the project is partway through a scene-separation migration, but runtime still depends on the monolithic scene.
+
+## Recommendation
+
+Finish the split-scene architecture. Keep one small bootstrap scene and load mode-specific UI scenes additively.
+
+The target architecture should be:
+
+- `Main`: startup/bootstrap only. Owns scene loading and truly persistent app services.
+- `Shared`: shared UI and app-wide interaction infrastructure, such as the event system, error panels, confirmation modals, connection status overlays, settings, and update notifications.
+- `Connection`: login, account selection, lobby, custom battle creation, and game-selection UI.
+- `Eagle`: strategic map, strategic command panels, province/hero/battalion UI, notifications, and Eagle-specific effects.
+- `Shardok`: tactical battle UI, hex grid, battle command UI, unit rows, tactical effects, and battle-only camera/input helpers.
+
+Do not treat large prefabs as inherently bad. A large prefab is acceptable when it represents a coherent, reusable feature root. The problematic pattern is a large scene that owns unrelated application states and long-lived object references.
+
+## Goals
+
+- Reduce merge conflicts and accidental Unity serialization churn.
+- Make login/lobby, Eagle, and Shardok changes independently editable.
+- Make scene lifecycle explicit: load only the mode currently needed.
+- Avoid cross-scene inspector references that are hard to reason about.
+- Preserve a safe fallback until each migrated section is validated.
+
+## Non-Goals
+
+- Do not refactor gameplay logic and scene structure in the same change.
+- Do not delete `Gameplay.unity` until all migrated scenes are verified in Editor, local builds, and CI.
+- Do not move large vendor asset packs as part of this work.
+- Do not split every small widget into its own scene. Prefer prefabs for reusable UI components and scenes for application modes.
+
+## Target Runtime Flow
+
+```text
+Main
+  Load Shared
+  Load Connection
+
+Connection -> Eagle
+  Unload Connection
+  Ensure Shared remains loaded
+  Load Eagle
+
+Eagle -> Shardok
+  Keep Eagle loaded unless the battle UI must exclusively own the viewport
+  Load Shardok additively
+
+Shardok -> Eagle
+  Unload Shardok
+  Keep Eagle and Shared loaded
+
+Eagle -> Connection
+  Unload Shardok if loaded
+  Unload Eagle
+  Load Connection
+```
+
+## Ownership Rules
+
+Use these rules during migration to avoid ambiguous object lifetimes.
+
+- `Main` owns `GameSceneManager`, app bootstrap, and any service object that must survive across login, lobby, Eagle, and Shardok.
+- `Shared` owns exactly one active `EventSystem` and shared modal/overlay UI.
+- `Connection` owns `ConnectionHandler` and connection/lobby panel instances.
+- `Eagle` owns `EagleGameController` and strategic-mode scene roots.
+- `Shardok` owns `ShardokGameController` and tactical-mode scene roots.
+- Cross-mode communication should happen through model/controller APIs, not direct serialized references to objects in another loadable scene.
+- If a scene needs an object from another scene, prefer resolving it during scene initialization and failing loudly when required dependencies are missing.
+
+## Migration Plan
+
+### Phase 1: Make Bootstrap Explicit
+
+- Make `Main.unity` the intended startup scene.
+- Update `BootstrapManager` so the split-scene path is the default in development builds.
+- Keep a temporary fallback flag for loading `Gameplay.unity`.
+- Ensure build settings order is intentional: `Main` first, then loadable scenes. Leave `Gameplay` present only while fallback is still required.
+- Add logging that states which startup path was chosen.
+
+Validation:
+
+- Enter Play Mode from `Main.unity`.
+- Confirm `Shared` and `Connection` load without duplicate `EventSystem` objects.
+- Confirm fallback still loads `Gameplay.unity` if explicitly enabled.
+
+### Phase 2: Migrate Shared Infrastructure
+
+- Move shared error UI, update UI, settings UI, connection status overlays, and global modal roots into `Shared.unity`.
+- Keep only one event system active when additive scenes are loaded.
+- Remove duplicated shared UI from `Gameplay.unity` only after migrated UI is validated.
+
+Validation:
+
+- Trigger an error modal from Connection, Eagle, and Shardok flows.
+- Open/close settings from each mode that supports it.
+- Verify no duplicate event-system warnings.
+
+### Phase 3: Migrate Connection and Lobby
+
+- Move `ConnectionCanvas`, login controls, account selector, lobby, custom battle UI, and game-selection rows into `Connection.unity`.
+- Make `ConnectionHandler` initialize after the scene is loaded rather than assuming objects exist in `Gameplay.unity`.
+- Replace show/hide transitions that activate large inactive subtrees with scene transitions where appropriate.
+
+Validation:
+
+- Start unauthenticated, authenticate, list available games, create/drop a custom battle, and enter a game.
+- Return from an active game to the lobby.
+- Test stored account flows.
+
+### Phase 4: Migrate Eagle Strategic UI
+
+- Move strategic map, command panel roots, hero/battalion/province UI, Eagle notifications, and strategic effects into `Eagle.unity`.
+- Keep reusable row/panel widgets as prefabs under `Assets/Eagle/`.
+- Remove direct dependencies on connection-scene objects.
+
+Validation:
+
+- Load a game from the lobby.
+- Select provinces, heroes, battalions, command buttons, and notifications.
+- Issue at least one representative command from each major command-panel family.
+- Confirm generated/dynamic text listeners clean up when leaving the scene.
+
+### Phase 5: Migrate Shardok Tactical UI
+
+- Move Shardok canvas, hex grid, battle panels, tactical rows, battle effects, and battle-only input/camera roots into `Shardok.unity`.
+- Decide whether Eagle remains visible/loaded under Shardok. Prefer keeping Eagle loaded if returning from battle must preserve strategic UI state.
+- Ensure Shardok scene unload disposes generated text listeners, subscriptions, object pools, and pending animation state.
+
+Validation:
+
+- Enter battle from Eagle.
+- Select units, issue movement/attack/fire/extinguish/end-turn commands.
+- Resolve a battle and return to Eagle.
+- Start a second battle in the same session to catch stale singleton/listener state.
+
+### Phase 6: Remove Legacy Scene Dependency
+
+- Flip the default so `Gameplay.unity` is not loaded during normal startup.
+- Remove `Gameplay.unity` from build settings once no supported flow needs it.
+- Keep `Gameplay.unity` in the repo temporarily as a reference snapshot if useful, then delete it in a separate cleanup PR.
+- Remove transitional helpers whose only purpose was loading or testing the legacy scene.
+
+Validation:
+
+- Local Editor smoke test through login, Eagle, Shardok, and return flows.
+- Unity edit-mode test suite if available.
+- CI Unity build.
+- TestFlight build before deleting the legacy scene.
+
+## Review Checklist For Each Migration PR
+
+- The PR moves one coherent subsystem, not multiple unrelated UI areas.
+- Scene files remain small enough to review.
+- Prefab changes are limited to the migrated subsystem.
+- No required Inspector field is hidden behind a defensive null check.
+- No duplicate `EventSystem`, camera, global canvas, or singleton is active.
+- Leaving and re-entering the migrated scene works in one app session.
+- The old `Gameplay.unity` object is removed only after the new scene object is verified.
+
+## Risks
+
+- Serialized cross-scene references will break when objects move. Prefer runtime lookup/initialization through explicit scene controllers.
+- Singletons may survive scene unload and hold stale references. Audit `OnDestroy`, `Dispose`, and listener cleanup for every moved controller.
+- Additive scenes can accidentally create duplicate input/event/camera objects. Keep these centralized in `Shared` or `Main`.
+- Loading Shardok additively over Eagle can expose hidden assumptions about active canvases, cameras, and selected input targets.
+- Unity scene YAML changes are easy to corrupt manually. Prefer moving objects in the Unity Editor and reviewing diffs carefully.
+
+## Open Decisions
+
+- Whether Shardok should overlay Eagle additively or unload most Eagle UI while battle is active.
+- Whether the primary persistent game connection object belongs in `Main` or should be recreated per selected game.
+- Whether `Shared` should always load at startup or only after successful connection.
+- How long to keep `Gameplay.unity` after the split scene flow is fully validated.
+
+## Suggested First PR
+
+The first implementation PR should not move Eagle or Shardok. It should:
+
+1. Make `Main.unity` the startup scene in build settings.
+2. Make the split-scene bootstrap path explicit and logged.
+3. Load `Shared` plus `Connection` by default.
+4. Keep a fallback flag for loading `Gameplay.unity`.
+5. Validate login/lobby startup in Editor and CI.
+
+That gives a controlled base for subsequent subsystem migrations.

docs/URP_MIGRATION_PLAN.md

@@ -0,0 +1,173 @@
+# URP Migration Plan
+
+## Why
+
+Unity is removing Built-In Render Pipeline (BiRP) support after Unity 6.7. We're currently on Unity 6.4. Each Unity minor version ships roughly quarterly, giving us a few release cycles before BiRP is dropped. This document lays out the migration plan.
+
+## Strategy: Long-Lived Feature Branch
+
+All URP conversion work happens on a **long-lived `urp-migration` branch**. Main stays fully functional on BiRP throughout the migration.
+
+- **Main branch**: Continues using BiRP. All gameplay, AI, and server development proceeds normally.
+- **URP branch**: Accumulates rendering pipeline changes across all phases.
+- **Regular rebasing**: Periodically rebase/merge `main` into the URP branch to stay current. Shader and material changes rarely conflict with gameplay code, so merge conflicts should be manageable.
+- **Merge to main**: Only when everything renders correctly and visual QA passes.
+
+This avoids the "everything is pink" problem of switching the pipeline on main before shaders are converted.
+
+## Current State
+
+| Category | Count | Notes |
+|---|---|---|
+| Shaders | 47 | 7 custom Eagle, 1 hex mesh, 20 Polytope, 13 TextMesh Pro, 6 other third-party |
+| Materials | 325 | Mix of Standard shader, custom, and third-party |
+| ShaderGraph files | 4 | All TextMesh Pro (URP + HDRP variants already exist) |
+| Scenes with baked lighting | 6 | Gameplay, Connection, Eagle, Shardok, Shared, Map Editor |
+| Post-processing | 1 profile | PPP_Orc.asset (Post Processing Stack v2, FXAA/TAA, AO) |
+| C# rendering scripts | 16 | Material/shader property manipulation only |
+| Rendering path | Forward | Matches URP default |
+
+### Positive Findings
+
+- **No OnRenderImage, Graphics.Blit, CommandBuffer, or GL.\* usage** in C# code
+- Forward rendering already in use (matches URP default)
+- TextMesh Pro already has URP ShaderGraph variants in the project
+- No custom render passes or ScriptableRenderFeatures
+- Shader property manipulation (SetTexture, SetFloat, SetColor) is URP-compatible
+
+### Known Risk Areas
+
+- **GrabPass shaders** (HeatShimmerShader, PT_Water_Shader) have no direct URP equivalent
+- **ProvinceMapShader** is complex (province ID lookup, border rendering, ocean animation, faction highlighting, UI clipping)
+- **Surface shaders** (`#pragma surface surf Standard`) must be rewritten as HLSL or ShaderGraph
+- **Polytope Studio shaders** (20 shaders) have no vendor-provided URP variants
+- **Post Processing Stack v2** must be replaced with URP's integrated Volume system
+- **Tessellation** (PT_Water_Shader) is not natively supported in URP
+
+## Shader Inventory
+
+### Custom Eagle Shaders (7) -- HIGH PRIORITY
+
+| Shader | Complexity | Key Issues |
+|---|---|---|
+| ProvinceMapShader | High | Province ID texture lookup, border rendering, ocean animation, faction highlighting, `UnityUI.cginc` dependency, stencil/clipping |
+| ProvinceWeatherMapShader | Medium | Weather overlay rendering |
+| ProvinceWeatherShader | Medium | Province weather effects |
+| ProvinceParticleShader | Low | Custom particle rendering |
+| HeatShimmerShader | High | **GrabPass** for screen distortion, province masking |
+| ClipRectParticleUnlit | Low | UI-clipped particle shader |
+| maskShader | Low | UI masking |
+
+### Hex Mesh Shader (1) -- MODERATE PRIORITY
+
+Uses `#pragma surface surf Standard` with GPU instancing. Straightforward conversion to URP Lit or ShaderGraph.
+
+### Third-Party Shaders (39)
+
+| Source | Count | Complexity | Notes |
+|---|---|---|---|
+| Polytope Studio | 20 | Moderate-High | PBR, Toon, vegetation (custom lighting), water (**GrabPass + tessellation**). No vendor URP pack available. |
+| TextMesh Pro | 13 | Low | URP ShaderGraph variants already exist in project |
+| RRFreelance | 3 | Low | Standard surface shaders, direct conversion |
+| Clown.fat | 2 | Moderate | Custom ToonRamp lighting model |
+| GUI Pro Kit | 1 | Low | Hidden particle shader |
+
+### GrabPass Shaders (Require Special Handling)
+
+GrabPass does not exist in URP. These must be reimplemented using `ScriptableRenderPass` + `Renderer Features` or Blit-based alternatives:
+
+1. **HeatShimmerShader** -- Screen distortion effect (currently has a shimmer-disabled TODO, may be deprioritized)
+2. **PT_Water_Shader** -- Water refraction/transparency (PT_Water_Shader_WebGl exists without GrabPass as a reference)
+
+## Phased Approach
+
+### Phase 1: Pipeline Setup + Auto-Conversion (Days 1-3)
+
+- Install URP package
+- Create URP Pipeline Asset and Renderer Asset
+- Configure basic pipeline settings (forward rendering, shadow settings)
+- Run Unity's **Render Pipeline Converter** (Edit > Rendering > Render Pipeline Converter)
+  - Auto-converts Standard shader materials and some built-in shaders
+  - Handles a significant portion of the 325 materials
+  - Will NOT touch custom shaders
+- Create a test scene to validate basic rendering
+- Migrate viewport clipping system (`RendererViewportClipper`, `ViewportClipper`, `PopupClipper`) to use URP-compatible global shader properties
+
+### Phase 2: Custom Eagle Shaders (Weeks 1-3)
+
+This is the critical path. Without these, the game is unplayable.
+
+**Week 1-2: ProvinceMapShader**
+- Convert from BiRP Cg/HLSL to URP HLSL
+- Replace `UnityCG.cginc` includes with `Core.hlsl` / `Common.hlsl`
+- Replace `UnityUI.cginc` with custom URP-compatible UI clipping
+- Preserve province ID texture lookup, border rendering, ocean animation, faction highlighting
+- Validate stencil operations and render queue ordering
+
+**Week 2-3: Remaining Eagle shaders**
+- ProvinceWeatherMapShader + ProvinceWeatherShader
+- ProvinceParticleShader + ClipRectParticleUnlit
+- maskShader
+- Hex Mesh Shader (convert surface shader to URP Lit)
+- HeatShimmerShader (reimplement without GrabPass, or defer if shimmer remains disabled)
+
+### Phase 3: Third-Party Shaders (Weeks 4-6)
+
+**Polytope Studio (20 shaders)**
+- Convert PBR shaders (Armors, NPC, Weapons, Props, Rock) from surface shaders to URP Lit / ShaderGraph
+- Convert Toon shaders to custom URP shader or ShaderGraph with custom lighting
+- Convert vegetation shaders (custom `StandardCustom` lighting) to ShaderGraph
+- PT_Water_Shader: Reimplement without GrabPass and tessellation (use PT_Water_Shader_WebGl as reference for non-GrabPass approach)
+
+**Other third-party**
+- Clown.fat ToonRamp shaders: Convert custom lighting model to ShaderGraph
+- RRFreelance shaders: Direct Standard-to-URP-Lit conversion
+- GUI Pro Kit particle shader: Convert to URP particle shader
+
+### Phase 4: Materials, Lighting & Post-Processing (Weeks 7-8)
+
+**Materials**
+- Batch-update any remaining materials not handled by the auto-converter
+- Verify all 325 materials render correctly
+- Fix any visual differences from lighting model changes
+
+**Lighting**
+- Rebake lightmaps for all 6 scenes (Gameplay, Connection, Eagle, Shardok, Shared, Map Editor)
+- Configure URP shadow cascade settings to match current quality levels
+- Verify HDR rendering
+
+**Post-Processing**
+- Remove Post Processing Stack v2 dependency (`com.unity.postprocessing: 3.5.1`)
+- Replace with URP integrated Volume system
+- Recreate PPP_Orc effects (FXAA/TAA, Ambient Occlusion) using URP Volume overrides
+
+### Phase 5: Testing & Validation (Weeks 9-11)
+
+- Visual QA across all 6 scenes
+- Verify beast/character rendering (vertex colors, animations)
+- Verify weather effects (blizzard, drought, flood)
+- Verify particle systems (fire & explosion effects, UI particles)
+- Verify UI rendering (GUI Pro Kit, Modern UI Pack, TextMesh Pro)
+- Performance profiling (URP has different performance characteristics)
+- Test on target platforms
+- Bug fixes and visual polish
+
+## Effort Estimates
+
+| Phase | Best Case | Realistic | Worst Case |
+|---|---|---|---|
+| 1. Pipeline Setup | 1-2 days | 2-3 days | 3-5 days |
+| 2. Custom Eagle Shaders | 1.5 weeks | 2-3 weeks | 3-4 weeks |
+| 3. Third-Party Shaders | 1.5 weeks | 2-3 weeks | 3-4 weeks |
+| 4. Materials & Lighting | 3-5 days | 1-1.5 weeks | 2 weeks |
+| 5. Testing & Validation | 1 week | 1.5-2 weeks | 2-3 weeks |
+| **Total** | **6-8 weeks** | **8-12 weeks** | **12-16 weeks** |
+
+The biggest variable is Polytope Studio shader conversion. If vendor URP packs become available, Phase 3 shrinks significantly.
+
+## Key Reminders
+
+- **Don't leave GrabPass rewrites and ProvinceMapShader for the end** -- they're the riskiest pieces and should be tackled early.
+- The migration window (~1 year) is comfortable. Spreading the work across this window is fine, but front-load the hard shader work.
+- C# code changes should be minimal -- the codebase avoids direct rendering API usage.
+- `UnityUI.cginc` has no direct URP equivalent. Custom implementation will be needed for UI clipping in shaders.

docs/ai-quest-completion.md

@@ -4,17 +4,36 @@ This document describes which quests the AI attempts to complete proactively to
 
 ## Overview
 
-The AI attempts to complete quests via `FulfillQuestsCommandSelector`, which is invoked by `MidGameAIClient.chosenFulfillEasyQuestsCommand`. The AI only considers quests from unaffiliated heroes in provinces ruled by a faction leader.
+The AI attempts to complete most quests via `FulfillQuestsCommandSelector`, which is invoked by `MidGameAIClient.chosenFulfillEasyQuestsCommand`.
+
+Important scope limits:
+
+- The selector only considers quests from unaffiliated heroes in provinces owned by the acting faction.
+- It further filters to provinces ruled by that faction's leader.
+- It only emits a command when the corresponding command is currently available.
+- Handler order is fixed. The first handler that produces a valid command wins.
 
 ## Quests the AI Actively Completes
 
+This section lists quests with direct `QuestCommandChooser` handlers in `FulfillQuestsCommandSelector`.
+
 ### Diplomacy Quests
 
 | Quest | Handler | Conditions |
 |-------|---------|------------|
-| `AllianceQuest` | `AllianceQuestCommandChooser` | Target faction must meet trust conditions for alliance and not already be in an alliance |
 | `TruceWithFactionQuest` | `TruceWithFactionQuestCommandChooser` | Target faction must meet trust conditions for truce |
 | `TruceCountQuest` | `TruceCountQuestCommandChooser` | Picks a random faction that meets trust conditions and isn't already in a truce/alliance |
+| `AllianceQuest` | `AllianceQuestCommandChooser` | Target faction must meet trust conditions for alliance and not already be in an alliance |
+| `BetrayAllyQuest` | `BetrayAllyQuestCommandChooser` | Break alliance with target faction. Only if factions don't share a border. Sends weakest non-leader hero. |
+
+### Province Development Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `ImproveAgricultureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Agriculture type |
+| `ImproveEconomyQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Economy type |
+| `ImproveInfrastructureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Infrastructure type |
+| `TotalDevelopmentQuest` | `TotalDevelopmentQuestCommandChooser` | Improve the lowest stat in the target province |
 
 ### Resource Giving Quests
 
@@ -24,72 +43,99 @@ The AI attempts to complete quests via `FulfillQuestsCommandSelector`, which is
 | `AlmsAcrossRealmQuest` | `AlmsAcrossRealmQuestCommandChooser` | Gives food from the province with the largest surplus |
 | `GiveToHeroesInProvinceQuest` | `GiveToHeroesInProvinceQuestCommandChooser` | Gives gold to the hero with the lowest loyalty in the specified province |
 | `GiveToHeroesAcrossRealmQuest` | `GiveToHeroesAcrossRealmQuestCommandChooser` | Gives gold from the province with the most gold available |
+| `SpendOnFeastsInProvinceQuest` | `SpendOnFeastsQuestCommandChooser` | Spend gold on feasts in the quest holder's province |
+| `SpendOnFeastsAcrossRealmQuest` | `SpendOnFeastsQuestCommandChooser` | Spend gold on the most expensive currently available feast |
+| `SendSuppliesQuest` | `SendSuppliesQuestCommandChooser` | Send food to the target province |
 
-### Province Development Quests
+### Prisoner Quests
 
 | Quest | Handler | Notes |
 |-------|---------|-------|
-| `ImproveAgricultureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Agriculture type |
-| `ImproveEconomyQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Economy type |
-| `ImproveInfrastructureQuest` | `ImproveQuestCommandChooser` | Issues an Improve command with Infrastructure type |
+| `ReleasePrisonerQuest` | `ReleasePrisonerQuestCommandChooser` | Release a specific prisoner |
+| `ExilePrisonerQuest` | `ExilePrisonerQuestCommandChooser` | Exile a specific prisoner |
+| `ExecutePrisonerQuest` | `ExecutePrisonerQuestCommandChooser` | Execute a specific prisoner |
+| `ReturnPrisonerQuest` | `ReturnPrisonerQuestCommandChooser` | Return a prisoner to their faction |
+| `ReleaseAllPrisonersQuest` | `ReleaseAllPrisonersQuestCommandChooser` | Release all prisoners |
+
+### Province Order Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `DevelopProvincesQuest` | `DevelopProvincesQuestCommandChooser` | Switches provinces to Develop order. Prefers provinces without hostile neighbors. |
+| `MobilizeProvincesQuest` | `MobilizeProvincesQuestCommandChooser` | Switches provinces to Mobilize order. Prefers provinces with hostile neighbors. Skipped if a DevelopProvincesQuest also exists (conflict avoidance). |
+
+### Weather/Epidemic Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `StartEpidemicQuest` | `StartEpidemicQuestCommandChooser` | Start an epidemic in a province. Skipped if the target province belongs to the acting faction. |
+| `StartBlizzardQuest` | `ControlWeatherQuestCommandChooser` | Start a blizzard via ControlWeather command. Skipped if the target province belongs to the acting faction. |
+| `StartDroughtQuest` | `ControlWeatherQuestCommandChooser` | Start a drought via ControlWeather command. Skipped if the target province belongs to the acting faction. |
+
+### Military Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `GrandArmyQuest` | `GrandArmyQuestCommandChooser` | Uses OrganizeTroops to top off existing battalions and hire Light Infantry. Only executes if resources are sufficient to fully meet the troop target. |
+| `BattalionDiversityQuest` | `BattalionDiversityQuestCommandChooser` | Hires one battalion of a missing type to reach 3+ distinct types. Only attempts if the province already has 2+ existing types, has sufficient development (`meetsRequirements`), and gold/food surplus. |
+| `UpgradeBattalionQuest` | `UpgradeBattalionQuestCommandChooser` | Walks a priority tree per turn: arm-completes (with optional travel and/or food sale setup) → train-completes → march in a pre-qualified neighbor battalion → organize/top-off of the target type → march in an unqualified neighbor battalion → develop Economy/Agriculture → train progress → develop Infrastructure → arm progress. Only toggles Travel when it directly enables an arm-completes finisher. |
+
+### Reconnaissance Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `ReconSpecificProvincesQuest` | `ReconSpecificProvincesQuestCommandChooser` | Recon specific target provinces. Prefers not-yet-reconned targets. |
+| `ReconProvincesQuest` | `ReconProvincesQuestCommandChooser` | Issues a Recon command to reconnoiter a province |
+
+### Beast Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `FightBeastsAloneQuest` | `FightBeastsAloneQuestCommandChooser` | Send an expendable non-leader hero to fight beasts without a battalion. Hero must have power at most `MaxExpendableHeroPowerRatio` (default 0.75) times the quest-giving hero's power. Picks the weakest eligible hero. |
+
+### Special Event Quests
+
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `ApprehendOutlawQuest` | `ApprehendOutlawQuestCommandChooser` | Apprehend a specific outlaw hero when present in the province |
 
 ### Other Quests
 
 | Quest | Handler | Conditions |
 |-------|---------|------------|
+| `RestProvinceQuest` | `RestProvinceQuestCommandChooser` | Use the Rest command in a specific province |
+| `SwearBrotherhoodWithHeroQuest` | `SwearBrotherhoodQuestCommandChooser` | Swear brotherhood with a specific hero |
 | `DismissSpecificVassalQuest` | `DismissSpecificVassalCommandChooser` | Only if province has more than 2 heroes AND the unaffiliated hero's power >= target hero's power * `RequiredPowerMultiplierForDismiss` |
 
-## Quests the AI Does Not Attempt to Complete
+## Quests the AI Handles Indirectly
 
-The following quests have no handler in `FulfillQuestsCommandSelector` and must be completed naturally through gameplay:
+These are not in `FulfillQuestsCommandSelector`, but other AI command-selection code can still bias toward completing them.
 
-### Combat/Military Quests
-- `DefeatFactionQuest` - Defeat a specific faction
-- `GrandArmyQuest` - Accumulate a large number of troops
-- `UpgradeBattalionQuest` - Upgrade a battalion to minimum armament/training
-- `WinBattleOutnumberedQuest` - Win a battle while outnumbered
-- `WinBattlesQuest` - Win a number of battles
-- `RescueImprisonedLeaderQuest` - Rescue an imprisoned leader from another faction
+| Quest | Handler | Notes |
+|-------|---------|-------|
+| `SuppressRiotByForceQuest` | `CommandChoiceHelpers.handleRiotSelectedCommand` | When this quest exists and the faction has battalions, the AI prefers CrackDown over Give when handling riots. |
 
-### Expansion Quests
-- `ExpandToProvincesQuest` - Expand to control a certain number of provinces
-- `SpecificExpansionQuest` - Conquer a specific province
-- `BorderSecurityQuest` - Have troops in a border province
+## Quests the AI Does Not Yet Attempt to Complete
 
-### Prisoner Quests
-- `ExecutePrisonerQuest` - Execute a specific prisoner
-- `ExilePrisonerQuest` - Exile a specific prisoner
-- `ReleasePrisonerQuest` - Release a specific prisoner
-- `ReturnPrisonerQuest` - Return a prisoner to their faction
-- `ReleaseAllPrisonersQuest` - Release all prisoners
+The following quests have no handler and must be completed naturally through gameplay. They are listed in rough priority order for future implementation.
 
-### Province Order Quests
-- `DevelopProvincesQuest` - Maintain provinces in Develop order for months
-- `MobilizeProvincesQuest` - Maintain provinces in Mobilize order for months
-- `RestProvinceQuest` - Use the Rest command in a specific province
+### Planned for Implementation
 
-### Reconnaissance Quests
-- `ReconProvincesQuest` - Reconnoiter a number of provinces
-- `ReconSpecificProvincesQuest` - Reconnoiter specific provinces
+None currently planned.
 
-### Economic Quests
-- `TotalDevelopmentQuest` - Achieve total development level in a province
-- `WealthQuest` - Accumulate gold and food
-- `SpendOnFeastsQuest` - Spend gold on feasts
-- `SendSuppliesQuest` - Send food to a specific province
-- `RepairDevastationQuest` - Repair devastation
+### Not Planned
 
-### Special Event Quests
-- `SuppressRiotByForceQuest` - Suppress a riot by force
-- `FightBeastsAloneQuest` - Fight beasts alone
-- `StartBlizzardQuest` - Start a blizzard in a province
-- `StartEpidemicQuest` - Start an epidemic in a province
-- `ApprehendOutlawQuest` - Apprehend an outlaw hero
+These quests are too situational, passive, or risky to actively pursue. They may be completed naturally through gameplay.
 
-### Miscellaneous
-- `BattalionDiversityQuest` - Have diverse battalion types
-- `SwearBrotherhoodWithHeroQuest` - Swear brotherhood with a specific hero
-- `BetrayAllyQuest` - Betray an allied faction
+- `BorderSecurityQuest` - Have troops in a border province. Involves taking provinces; better left to organic expansion.
+- `DefeatFactionQuest` - Defeat a specific faction. Too risky to pursue proactively.
+- `SpecificExpansionQuest` - Conquer a specific province. Too risky.
+- `ExpandToProvincesQuest` - Expand to control a certain number of provinces. Too risky.
+- `WinBattleOutnumberedQuest` - Win a battle while outnumbered. Can't reliably engineer.
+- `WinBattlesQuest` - Win a number of battles. Passive.
+- `RescueImprisonedLeaderQuest` - Rescue an imprisoned leader. Complex multi-step.
+- `WealthQuest` - Accumulate gold and food. Happens passively.
+- `RepairDevastationQuest` - Repair devastation. Happens passively.
 
 ## Implementation Details
 
@@ -102,12 +148,34 @@ Each chooser extends either:
 - `DeterministicQuestCommandChooser` - For quests with deterministic command selection
 
 The AI prioritizes quests in the order they appear in `FulfillQuestsCommandSelector.choosers`:
-1. Alliance
-2. TruceWithFaction
-3. Improve (Agriculture/Economy/Infrastructure)
+1. TruceWithFaction
+2. Improve (Agriculture/Economy/Infrastructure)
+3. TotalDevelopment
 4. AlmsToProvince
 5. GiveToHeroesInProvince
 6. AlmsAcrossRealm
 7. GiveToHeroesAcrossRealm
 8. TruceCount
 9. DismissSpecificVassal
+10. ReleasePrisoner
+11. ExilePrisoner
+12. ExecutePrisoner
+13. ReturnPrisoner
+14. ReleaseAllPrisoners
+15. ApprehendOutlaw
+16. SpendOnFeastsInProvince / SpendOnFeastsAcrossRealm
+17. RestProvince
+18. DevelopProvinces
+19. MobilizeProvinces
+20. SendSupplies
+21. StartEpidemic
+22. ControlWeather (StartBlizzard/StartDrought)
+23. GrandArmy
+24. FightBeastsAlone
+25. BattalionDiversity
+26. UpgradeBattalion
+27. ReconSpecificProvinces
+28. ReconProvinces
+29. SwearBrotherhood
+30. Alliance
+31. BetrayAlly

go.mod

@@ -12,7 +12,7 @@ require (
 	github.com/golang-jwt/jwt/v5 v5.2.1
 	github.com/google/uuid v1.6.0
 	github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6
-	golang.org/x/sys v0.28.0
+	golang.org/x/sys v0.30.0
 	google.golang.org/grpc v1.68.0
 	google.golang.org/protobuf v1.36.3
 )

go.sum

@@ -43,8 +43,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6 h1:VQpB2SpK88C6B5lPHTuSZKb2Qee1QWwiFlC5CKY4AW0=
 github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6/go.mod h1:yE65LFCeWf4kyWD5re+h4XNvOHJEXOCOuJZ4v8l5sgk=
-golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
-golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 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=

scripts/build_sparkle_plugin.sh

@@ -2,9 +2,6 @@
 #
 # Build the SparklePlugin native library for Unity using Bazel
 #
-# The SparklePlugin is built in a separate Bazel workspace (sparkle_workspace/)
-# to avoid rules_swift version conflicts between grpc and rules_apple.
-#
 # Usage: build_sparkle_plugin.sh [output_dir]
 
 set -euo pipefail
@@ -14,14 +11,13 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 OUTPUT_DIR="${1:-$PROJECT_ROOT/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/macOS}"
 
-echo "=== Building SparklePlugin with Bazel (from sparkle_workspace) ==="
+echo "=== Building SparklePlugin with Bazel ==="
 
-# Build in the separate sparkle_workspace to avoid dependency conflicts
-cd "$PROJECT_ROOT/sparkle_workspace"
-bazel build //:SparklePlugin
+cd "$PROJECT_ROOT"
+bazel build //src/main/objc/net/eagle0/clients/unity/sparkle:SparklePlugin
 
 # Get the zip path from bazel
-ZIP_PATH=$(bazel cquery --output=files //:SparklePlugin 2>/dev/null)
+ZIP_PATH=$(bazel cquery --output=files //src/main/objc/net/eagle0/clients/unity/sparkle:SparklePlugin 2>/dev/null)
 
 echo "=== Extracting SparklePlugin.bundle ==="
 mkdir -p "$OUTPUT_DIR"

scripts/pre-commit-gazelle.sh

@@ -4,8 +4,10 @@
 
 set -e
 
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
 # Run gazelle
-bazel run //:gazelle 2>/dev/null
+bazel run //:gazelle
 
 # Check if any BUILD files were modified
 if ! git diff --quiet -- '*.bazel' '**/BUILD' 'WORKSPACE*'; then

scripts/pre-commit-scalafmt.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Pre-commit hook wrapper for scalafmt.
+# Runs the repository-pinned scalafmt CLI through Bazel.
+
+set -e
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+if [ "$#" -eq 0 ]; then
+    exit 0
+fi
+
+repo_root="$(git rev-parse --show-toplevel)"
+files=()
+for file in "$@"; do
+    case "$file" in
+        /*) files+=("$file") ;;
+        *) files+=("$repo_root/$file") ;;
+    esac
+done
+
+bazel run //tools:scalafmt -- --config "$repo_root/.scalafmt.conf" -i "${files[@]}"

scripts/sync_bazel_xcode.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Keeps Bazel macOS builds in sync with the installed Xcode version.
+#
+# Needed on macOS runners and developer machines because Bazel's generated
+# local_config_xcode/local_config_apple_cc repositories bake in the discovered
+# Xcode version. If Xcode is upgraded in place, the DEVELOPER_DIR path stays the
+# same, so Bazel can otherwise keep using stale Xcode metadata.
+#
+# 1. Writes .bazelrc.xcode with macOS-scoped flags:
+#    - action_env for remote cache key invalidation
+#    - DEVELOPER_DIR pointing to the active Xcode
+#
+# 2. Runs `bazel clean --expunge` when the version actually changes, because
+#    local_config_apple_cc (a cached repository rule) bakes in the old version
+#    and can only be refreshed by clearing the output base.
+#
+# .bazelrc imports the generated file via: try-import %workspace%/.bazelrc.xcode
+
+set -euo pipefail
+
+DEVELOPER_DIR=""
+if [ -d "/Applications/Xcode.app/Contents/Developer" ]; then
+    DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
+else
+    DEVELOPER_DIR=$(xcode-select -p 2>/dev/null || true)
+fi
+
+XCODE_BUILD_VERSION=$(DEVELOPER_DIR="$DEVELOPER_DIR" xcodebuild -version 2>/dev/null | awk '/Build version/ {print $3}' || true)
+
+if [ -z "$XCODE_BUILD_VERSION" ]; then
+    echo "ERROR: Could not detect full Xcode build version."
+    echo "mactools/Sparkle builds require full Xcode, not just Command Line Tools."
+    echo "Install Xcode at /Applications/Xcode.app or select it with xcode-select."
+    exit 1
+fi
+
+BAZELRC_XCODE=".bazelrc.xcode"
+EXPECTED_LINE="common:macos --action_env=XCODE_BUILD_VERSION=${XCODE_BUILD_VERSION}"
+
+# Check if the file already has the right version (first line is the version marker)
+if [ -f "$BAZELRC_XCODE" ]; then
+    CURRENT_FIRST_LINE=$(head -1 "$BAZELRC_XCODE")
+    if [ "$CURRENT_FIRST_LINE" = "$EXPECTED_LINE" ]; then
+        exit 0
+    fi
+fi
+
+# Xcode version changed (or first run) — expunge local cache to clear
+# stale local_config_apple_cc, then write the new config
+OLD_VERSION="unknown"
+if [ -f "$BAZELRC_XCODE" ]; then
+    OLD_VERSION=$(sed -n 's/.*XCODE_BUILD_VERSION=//p' "$BAZELRC_XCODE" | head -1)
+fi
+echo "Xcode build version changed: ${OLD_VERSION} -> ${XCODE_BUILD_VERSION}"
+echo "Running bazel clean --expunge to clear stale toolchain config..."
+bazel clean --expunge 2>/dev/null || true
+
+cat > "$BAZELRC_XCODE" << EOF
+${EXPECTED_LINE}
+common:macos --repo_env=DEVELOPER_DIR=${DEVELOPER_DIR}
+EOF
+
+if [ -n "${GITHUB_ENV:-}" ]; then
+    echo "DEVELOPER_DIR=${DEVELOPER_DIR}" >> "$GITHUB_ENV"
+fi
+
+echo "Updated ${BAZELRC_XCODE} — next macOS Bazel build will rebuild with Xcode ${XCODE_BUILD_VERSION}"

sparkle_workspace/.bazelversion

@@ -1 +0,0 @@
-7.7.1

sparkle_workspace/.gitignore

@@ -1,2 +0,0 @@
-# Bazel symlinks
-bazel-*

sparkle_workspace/MODULE.bazel

@@ -1,28 +0,0 @@
-module(name = "sparkle_workspace")
-
-# Minimal dependencies for building SparklePlugin
-# This workspace is isolated from the main workspace to avoid
-# rules_swift version conflicts between grpc and rules_apple
-
-bazel_dep(name = "apple_support", version = "1.21.1", repo_name = "build_bazel_apple_support")
-bazel_dep(name = "rules_apple", version = "4.3.3", repo_name = "build_bazel_rules_apple")
-
-# Register Apple CC toolchain for Objective-C compilation
-apple_cc_configure = use_extension(
-    "@build_bazel_apple_support//crosstool:setup.bzl",
-    "apple_cc_configure_extension",
-)
-use_repo(apple_cc_configure, "local_config_apple_cc")
-
-# Sparkle framework for macOS auto-updates
-http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-SPARKLE_VERSION = "2.6.4"
-
-http_archive(
-    name = "sparkle",
-    build_file = "//:external/BUILD.sparkle",
-    sha256 = "50612a06038abc931f16011d7903b8326a362c1074dabccb718404ce8e585f0b",
-    strip_prefix = "",
-    url = "https://github.com/sparkle-project/Sparkle/releases/download/%s/Sparkle-%s.tar.xz" % (SPARKLE_VERSION, SPARKLE_VERSION),
-)

sparkle_workspace/MODULE.bazel.lock

@@ -1,451 +0,0 @@
-{
-  "lockFileVersion": 13,
-  "registryFileHashes": {
-    "https://bcr.bazel.build/bazel_registry.json": "8a28e4aff06ee60aed2a8c281907fb8bcbf3b753c91fb5a5c57da3215d5b3497",
-    "https://bcr.bazel.build/modules/abseil-cpp/20210324.2/MODULE.bazel": "7cd0312e064fde87c8d1cd79ba06c876bd23630c83466e9500321be55c96ace2",
-    "https://bcr.bazel.build/modules/abseil-cpp/20211102.0/MODULE.bazel": "70390338f7a5106231d20620712f7cccb659cd0e9d073d1991c038eb9fc57589",
-    "https://bcr.bazel.build/modules/abseil-cpp/20230125.1/MODULE.bazel": "89047429cb0207707b2dface14ba7f8df85273d484c2572755be4bab7ce9c3a0",
-    "https://bcr.bazel.build/modules/abseil-cpp/20230802.0.bcr.1/MODULE.bazel": "1c8cec495288dccd14fdae6e3f95f772c1c91857047a098fad772034264cc8cb",
-    "https://bcr.bazel.build/modules/abseil-cpp/20230802.0/MODULE.bazel": "d253ae36a8bd9ee3c5955384096ccb6baf16a1b1e93e858370da0a3b94f77c16",
-    "https://bcr.bazel.build/modules/abseil-cpp/20230802.1/MODULE.bazel": "fa92e2eb41a04df73cdabeec37107316f7e5272650f81d6cc096418fe647b915",
-    "https://bcr.bazel.build/modules/abseil-cpp/20240116.1/MODULE.bazel": "37bcdb4440fbb61df6a1c296ae01b327f19e9bb521f9b8e26ec854b6f97309ed",
-    "https://bcr.bazel.build/modules/abseil-cpp/20240116.1/source.json": "9be551b8d4e3ef76875c0d744b5d6a504a27e3ae67bc6b28f46415fd2d2957da",
-    "https://bcr.bazel.build/modules/apple_support/1.11.1/MODULE.bazel": "1843d7cd8a58369a444fc6000e7304425fba600ff641592161d9f15b179fb896",
-    "https://bcr.bazel.build/modules/apple_support/1.15.1/MODULE.bazel": "a0556fefca0b1bb2de8567b8827518f94db6a6e7e7d632b4c48dc5f865bc7c85",
-    "https://bcr.bazel.build/modules/apple_support/1.21.1/MODULE.bazel": "5809fa3efab15d1f3c3c635af6974044bac8a4919c62238cce06acee8a8c11f1",
-    "https://bcr.bazel.build/modules/apple_support/1.23.1/MODULE.bazel": "53763fed456a968cf919b3240427cf3a9d5481ec5466abc9d5dc51bc70087442",
-    "https://bcr.bazel.build/modules/apple_support/1.23.1/source.json": "d888b44312eb0ad2c21a91d026753f330caa48a25c9b2102fae75eb2b0dcfdd2",
-    "https://bcr.bazel.build/modules/bazel_features/1.1.1/MODULE.bazel": "27b8c79ef57efe08efccbd9dd6ef70d61b4798320b8d3c134fd571f78963dbcd",
-    "https://bcr.bazel.build/modules/bazel_features/1.11.0/MODULE.bazel": "f9382337dd5a474c3b7d334c2f83e50b6eaedc284253334cf823044a26de03e8",
-    "https://bcr.bazel.build/modules/bazel_features/1.15.0/MODULE.bazel": "d38ff6e517149dc509406aca0db3ad1efdd890a85e049585b7234d04238e2a4d",
-    "https://bcr.bazel.build/modules/bazel_features/1.17.0/MODULE.bazel": "039de32d21b816b47bd42c778e0454217e9c9caac4a3cf8e15c7231ee3ddee4d",
-    "https://bcr.bazel.build/modules/bazel_features/1.18.0/MODULE.bazel": "1be0ae2557ab3a72a57aeb31b29be347bcdc5d2b1eb1e70f39e3851a7e97041a",
-    "https://bcr.bazel.build/modules/bazel_features/1.19.0/MODULE.bazel": "59adcdf28230d220f0067b1f435b8537dd033bfff8db21335ef9217919c7fb58",
-    "https://bcr.bazel.build/modules/bazel_features/1.21.0/MODULE.bazel": "675642261665d8eea09989aa3b8afb5c37627f1be178382c320d1b46afba5e3b",
-    "https://bcr.bazel.build/modules/bazel_features/1.27.0/MODULE.bazel": "621eeee06c4458a9121d1f104efb80f39d34deff4984e778359c60eaf1a8cb65",
-    "https://bcr.bazel.build/modules/bazel_features/1.28.0/MODULE.bazel": "4b4200e6cbf8fa335b2c3f43e1d6ef3e240319c33d43d60cc0fbd4b87ece299d",
-    "https://bcr.bazel.build/modules/bazel_features/1.3.0/MODULE.bazel": "cdcafe83ec318cda34e02948e81d790aab8df7a929cec6f6969f13a489ccecd9",
-    "https://bcr.bazel.build/modules/bazel_features/1.30.0/MODULE.bazel": "a14b62d05969a293b80257e72e597c2da7f717e1e69fa8b339703ed6731bec87",
-    "https://bcr.bazel.build/modules/bazel_features/1.30.0/source.json": "b07e17f067fe4f69f90b03b36ef1e08fe0d1f3cac254c1241a1818773e3423bc",
-    "https://bcr.bazel.build/modules/bazel_features/1.4.1/MODULE.bazel": "e45b6bb2350aff3e442ae1111c555e27eac1d915e77775f6fdc4b351b758b5d7",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.0.3/MODULE.bazel": "bcb0fd896384802d1ad283b4e4eb4d718eebd8cb820b0a2c3a347fb971afd9d8",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.1.1/MODULE.bazel": "1add3e7d93ff2e6998f9e118022c84d163917d912f5afafb3058e3d2f1545b5e",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.2.0/MODULE.bazel": "44fe84260e454ed94ad326352a698422dbe372b21a1ac9f3eab76eb531223686",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.2.1/MODULE.bazel": "f35baf9da0efe45fa3da1696ae906eea3d615ad41e2e3def4aeb4e8bc0ef9a7a",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.3.0/MODULE.bazel": "20228b92868bf5cfc41bda7afc8a8ba2a543201851de39d990ec957b513579c5",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.4.1/MODULE.bazel": "a0dcb779424be33100dcae821e9e27e4f2901d9dfd5333efe5ac6a8d7ab75e1d",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.4.2/MODULE.bazel": "3bd40978e7a1fac911d5989e6b09d8f64921865a45822d8b09e815eaa726a651",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.5.0/MODULE.bazel": "32880f5e2945ce6a03d1fbd588e9198c0a959bb42297b2cfaf1685b7bc32e138",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.6.1/MODULE.bazel": "8fdee2dbaace6c252131c00e1de4b165dc65af02ea278476187765e1a617b917",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.7.0/MODULE.bazel": "0db596f4563de7938de764cc8deeabec291f55e8ec15299718b93c4423e9796d",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.7.1/MODULE.bazel": "3120d80c5861aa616222ec015332e5f8d3171e062e3e804a2a0253e1be26e59b",
-    "https://bcr.bazel.build/modules/bazel_skylib/1.7.1/source.json": "f121b43eeefc7c29efbd51b83d08631e2347297c95aac9764a701f2a6a2bb953",
-    "https://bcr.bazel.build/modules/buildozer/7.1.2/MODULE.bazel": "2e8dd40ede9c454042645fd8d8d0cd1527966aa5c919de86661e62953cd73d84",
-    "https://bcr.bazel.build/modules/buildozer/7.1.2/source.json": "c9028a501d2db85793a6996205c8de120944f50a0d570438fcae0457a5f9d1f8",
-    "https://bcr.bazel.build/modules/google_benchmark/1.8.2/MODULE.bazel": "a70cf1bba851000ba93b58ae2f6d76490a9feb74192e57ab8e8ff13c34ec50cb",
-    "https://bcr.bazel.build/modules/googletest/1.11.0/MODULE.bazel": "3a83f095183f66345ca86aa13c58b59f9f94a2f81999c093d4eeaa2d262d12f4",
-    "https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/MODULE.bazel": "22c31a561553727960057361aa33bf20fb2e98584bc4fec007906e27053f80c6",
-    "https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/source.json": "41e9e129f80d8c8bf103a7acc337b76e54fad1214ac0a7084bf24f4cd924b8b4",
-    "https://bcr.bazel.build/modules/googletest/1.14.0/MODULE.bazel": "cfbcbf3e6eac06ef9d85900f64424708cc08687d1b527f0ef65aa7517af8118f",
-    "https://bcr.bazel.build/modules/jsoncpp/1.9.5/MODULE.bazel": "31271aedc59e815656f5736f282bb7509a97c7ecb43e927ac1a37966e0578075",
-    "https://bcr.bazel.build/modules/jsoncpp/1.9.5/source.json": "4108ee5085dd2885a341c7fab149429db457b3169b86eb081fa245eadf69169d",
-    "https://bcr.bazel.build/modules/libpfm/4.11.0/MODULE.bazel": "45061ff025b301940f1e30d2c16bea596c25b176c8b6b3087e92615adbd52902",
-    "https://bcr.bazel.build/modules/nlohmann_json/3.6.1/MODULE.bazel": "6f7b417dcc794d9add9e556673ad25cb3ba835224290f4f848f8e2db1e1fca74",
-    "https://bcr.bazel.build/modules/nlohmann_json/3.6.1/source.json": "f448c6e8963fdfa7eb831457df83ad63d3d6355018f6574fb017e8169deb43a9",
-    "https://bcr.bazel.build/modules/platforms/0.0.10/MODULE.bazel": "8cb8efaf200bdeb2150d93e162c40f388529a25852b332cec879373771e48ed5",
-    "https://bcr.bazel.build/modules/platforms/0.0.11/MODULE.bazel": "0daefc49732e227caa8bfa834d65dc52e8cc18a2faf80df25e8caea151a9413f",
-    "https://bcr.bazel.build/modules/platforms/0.0.11/source.json": "f7e188b79ebedebfe75e9e1d098b8845226c7992b307e28e1496f23112e8fc29",
-    "https://bcr.bazel.build/modules/platforms/0.0.4/MODULE.bazel": "9b328e31ee156f53f3c416a64f8491f7eb731742655a47c9eec4703a71644aee",
-    "https://bcr.bazel.build/modules/platforms/0.0.5/MODULE.bazel": "5733b54ea419d5eaf7997054bb55f6a1d0b5ff8aedf0176fef9eea44f3acda37",
-    "https://bcr.bazel.build/modules/platforms/0.0.6/MODULE.bazel": "ad6eeef431dc52aefd2d77ed20a4b353f8ebf0f4ecdd26a807d2da5aa8cd0615",
-    "https://bcr.bazel.build/modules/platforms/0.0.7/MODULE.bazel": "72fd4a0ede9ee5c021f6a8dd92b503e089f46c227ba2813ff183b71616034814",
-    "https://bcr.bazel.build/modules/platforms/0.0.8/MODULE.bazel": "9f142c03e348f6d263719f5074b21ef3adf0b139ee4c5133e2aa35664da9eb2d",
-    "https://bcr.bazel.build/modules/platforms/0.0.9/MODULE.bazel": "4a87a60c927b56ddd67db50c89acaa62f4ce2a1d2149ccb63ffd871d5ce29ebc",
-    "https://bcr.bazel.build/modules/protobuf/21.7/MODULE.bazel": "a5a29bb89544f9b97edce05642fac225a808b5b7be74038ea3640fae2f8e66a7",
-    "https://bcr.bazel.build/modules/protobuf/27.0/MODULE.bazel": "7873b60be88844a0a1d8f80b9d5d20cfbd8495a689b8763e76c6372998d3f64c",
-    "https://bcr.bazel.build/modules/protobuf/29.0-rc2/MODULE.bazel": "6241d35983510143049943fc0d57937937122baf1b287862f9dc8590fc4c37df",
-    "https://bcr.bazel.build/modules/protobuf/29.0-rc3/MODULE.bazel": "33c2dfa286578573afc55a7acaea3cada4122b9631007c594bf0729f41c8de92",
-    "https://bcr.bazel.build/modules/protobuf/29.0-rc3/source.json": "c16a6488fb279ef578da7098e605082d72ed85fc8d843eaae81e7d27d0f4625d",
-    "https://bcr.bazel.build/modules/protobuf/3.19.0/MODULE.bazel": "6b5fbb433f760a99a22b18b6850ed5784ef0e9928a72668b66e4d7ccd47db9b0",
-    "https://bcr.bazel.build/modules/protobuf/3.19.6/MODULE.bazel": "9233edc5e1f2ee276a60de3eaa47ac4132302ef9643238f23128fea53ea12858",
-    "https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/MODULE.bazel": "88af1c246226d87e65be78ed49ecd1e6f5e98648558c14ce99176da041dc378e",
-    "https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/source.json": "be4789e951dd5301282729fe3d4938995dc4c1a81c2ff150afc9f1b0504c6022",
-    "https://bcr.bazel.build/modules/re2/2023-09-01/MODULE.bazel": "cb3d511531b16cfc78a225a9e2136007a48cf8a677e4264baeab57fe78a80206",
-    "https://bcr.bazel.build/modules/re2/2023-09-01/source.json": "e044ce89c2883cd957a2969a43e79f7752f9656f6b20050b62f90ede21ec6eb4",
-    "https://bcr.bazel.build/modules/rules_android/0.1.1/MODULE.bazel": "48809ab0091b07ad0182defb787c4c5328bd3a278938415c00a7b69b50c4d3a8",
-    "https://bcr.bazel.build/modules/rules_android/0.1.1/source.json": "e6986b41626ee10bdc864937ffb6d6bf275bb5b9c65120e6137d56e6331f089e",
-    "https://bcr.bazel.build/modules/rules_apple/4.3.3/MODULE.bazel": "c5c2c4adeeac5f3f2f9b7f16abfa8be7ffefa596171d0d92bed4cae9ade0a498",
-    "https://bcr.bazel.build/modules/rules_apple/4.3.3/source.json": "3cb1d69c8243ffcc42ecbf84ae8b9cccd7b1e2f091b0aee5a3e9c9a45267f312",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.1/MODULE.bazel": "cb2aa0747f84c6c3a78dad4e2049c154f08ab9d166b1273835a8174940365647",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.10/MODULE.bazel": "ec1705118f7eaedd6e118508d3d26deba2a4e76476ada7e0e3965211be012002",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.11/MODULE.bazel": "9f249c5624a4788067b96b8b896be10c7e8b4375dc46f6d8e1e51100113e0992",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.13/MODULE.bazel": "0e8529ed7b323dad0775ff924d2ae5af7640b23553dfcd4d34344c7e7a867191",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.15/MODULE.bazel": "6704c35f7b4a72502ee81f61bf88706b54f06b3cbe5558ac17e2e14666cd5dcc",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.16/MODULE.bazel": "7661303b8fc1b4d7f532e54e9d6565771fea666fbdf839e0a86affcd02defe87",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.2/MODULE.bazel": "6915987c90970493ab97393024c156ea8fb9f3bea953b2f3ec05c34f19b5695c",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.6/MODULE.bazel": "abf360251023dfe3efcef65ab9d56beefa8394d4176dd29529750e1c57eaa33f",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.8/MODULE.bazel": "964c85c82cfeb6f3855e6a07054fdb159aced38e99a5eecf7bce9d53990afa3e",
-    "https://bcr.bazel.build/modules/rules_cc/0.0.9/MODULE.bazel": "836e76439f354b89afe6a911a7adf59a6b2518fafb174483ad78a2a2fde7b1c5",
-    "https://bcr.bazel.build/modules/rules_cc/0.1.2/MODULE.bazel": "557ddc3a96858ec0d465a87c0a931054d7dcfd6583af2c7ed3baf494407fd8d0",
-    "https://bcr.bazel.build/modules/rules_cc/0.1.2/source.json": "53fcb09b5816c83ca60d9d7493faf3bfaf410dfc2f15deb52d6ddd146b8d43f0",
-    "https://bcr.bazel.build/modules/rules_foreign_cc/0.9.0/MODULE.bazel": "c9e8c682bf75b0e7c704166d79b599f93b72cfca5ad7477df596947891feeef6",
-    "https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/MODULE.bazel": "40c97d1144356f52905566c55811f13b299453a14ac7769dfba2ac38192337a8",
-    "https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/source.json": "c8b1e2c717646f1702290959a3302a178fb639d987ab61d548105019f11e527e",
-    "https://bcr.bazel.build/modules/rules_java/4.0.0/MODULE.bazel": "5a78a7ae82cd1a33cef56dc578c7d2a46ed0dca12643ee45edbb8417899e6f74",
-    "https://bcr.bazel.build/modules/rules_java/5.3.5/MODULE.bazel": "a4ec4f2db570171e3e5eb753276ee4b389bae16b96207e9d3230895c99644b86",
-    "https://bcr.bazel.build/modules/rules_java/6.5.2/MODULE.bazel": "1d440d262d0e08453fa0c4d8f699ba81609ed0e9a9a0f02cd10b3e7942e61e31",
-    "https://bcr.bazel.build/modules/rules_java/7.10.0/MODULE.bazel": "530c3beb3067e870561739f1144329a21c851ff771cd752a49e06e3dc9c2e71a",
-    "https://bcr.bazel.build/modules/rules_java/7.12.2/MODULE.bazel": "579c505165ee757a4280ef83cda0150eea193eed3bef50b1004ba88b99da6de6",
-    "https://bcr.bazel.build/modules/rules_java/7.2.0/MODULE.bazel": "06c0334c9be61e6cef2c8c84a7800cef502063269a5af25ceb100b192453d4ab",
-    "https://bcr.bazel.build/modules/rules_java/7.6.1/MODULE.bazel": "2f14b7e8a1aa2f67ae92bc69d1ec0fa8d9f827c4e17ff5e5f02e91caa3b2d0fe",
-    "https://bcr.bazel.build/modules/rules_java/7.6.5/MODULE.bazel": "481164be5e02e4cab6e77a36927683263be56b7e36fef918b458d7a8a1ebadb1",
-    "https://bcr.bazel.build/modules/rules_java/8.3.2/MODULE.bazel": "7336d5511ad5af0b8615fdc7477535a2e4e723a357b6713af439fe8cf0195017",
-    "https://bcr.bazel.build/modules/rules_java/8.5.1/MODULE.bazel": "d8a9e38cc5228881f7055a6079f6f7821a073df3744d441978e7a43e20226939",
-    "https://bcr.bazel.build/modules/rules_java/8.5.1/source.json": "db1a77d81b059e0f84985db67a22f3f579a529a86b7997605be3d214a0abe38e",
-    "https://bcr.bazel.build/modules/rules_jvm_external/4.4.2/MODULE.bazel": "a56b85e418c83eb1839819f0b515c431010160383306d13ec21959ac412d2fe7",
-    "https://bcr.bazel.build/modules/rules_jvm_external/5.1/MODULE.bazel": "33f6f999e03183f7d088c9be518a63467dfd0be94a11d0055fe2d210f89aa909",
-    "https://bcr.bazel.build/modules/rules_jvm_external/5.2/MODULE.bazel": "d9351ba35217ad0de03816ef3ed63f89d411349353077348a45348b096615036",
-    "https://bcr.bazel.build/modules/rules_jvm_external/6.3/MODULE.bazel": "c998e060b85f71e00de5ec552019347c8bca255062c990ac02d051bb80a38df0",
-    "https://bcr.bazel.build/modules/rules_jvm_external/6.3/source.json": "6f5f5a5a4419ae4e37c35a5bb0a6ae657ed40b7abc5a5189111b47fcebe43197",
-    "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/MODULE.bazel": "d269a01a18ee74d0335450b10f62c9ed81f2321d7958a2934e44272fe82dcef3",
-    "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/source.json": "2faa4794364282db7c06600b7e5e34867a564ae91bda7cae7c29c64e9466b7d5",
-    "https://bcr.bazel.build/modules/rules_license/0.0.3/MODULE.bazel": "627e9ab0247f7d1e05736b59dbb1b6871373de5ad31c3011880b4133cafd4bd0",
-    "https://bcr.bazel.build/modules/rules_license/0.0.7/MODULE.bazel": "088fbeb0b6a419005b89cf93fe62d9517c0a2b8bb56af3244af65ecfe37e7d5d",
-    "https://bcr.bazel.build/modules/rules_license/1.0.0/MODULE.bazel": "a7fda60eefdf3d8c827262ba499957e4df06f659330bbe6cdbdb975b768bb65c",
-    "https://bcr.bazel.build/modules/rules_license/1.0.0/source.json": "a52c89e54cc311196e478f8382df91c15f7a2bfdf4c6cd0e2675cc2ff0b56efb",
-    "https://bcr.bazel.build/modules/rules_pkg/0.7.0/MODULE.bazel": "df99f03fc7934a4737122518bb87e667e62d780b610910f0447665a7e2be62dc",
-    "https://bcr.bazel.build/modules/rules_pkg/1.0.1/MODULE.bazel": "5b1df97dbc29623bccdf2b0dcd0f5cb08e2f2c9050aab1092fd39a41e82686ff",
-    "https://bcr.bazel.build/modules/rules_pkg/1.0.1/source.json": "bd82e5d7b9ce2d31e380dd9f50c111d678c3bdaca190cb76b0e1c71b05e1ba8a",
-    "https://bcr.bazel.build/modules/rules_proto/4.0.0/MODULE.bazel": "a7a7b6ce9bee418c1a760b3d84f83a299ad6952f9903c67f19e4edd964894e06",
-    "https://bcr.bazel.build/modules/rules_proto/5.3.0-21.7/MODULE.bazel": "e8dff86b0971688790ae75528fe1813f71809b5afd57facb44dad9e8eca631b7",
-    "https://bcr.bazel.build/modules/rules_proto/6.0.2/MODULE.bazel": "ce916b775a62b90b61888052a416ccdda405212b6aaeb39522f7dc53431a5e73",
-    "https://bcr.bazel.build/modules/rules_proto/6.0.2/source.json": "17a2e195f56cb28d6bbf763e49973d13890487c6945311ed141e196fb660426d",
-    "https://bcr.bazel.build/modules/rules_python/0.10.2/MODULE.bazel": "cc82bc96f2997baa545ab3ce73f196d040ffb8756fd2d66125a530031cd90e5f",
-    "https://bcr.bazel.build/modules/rules_python/0.22.1/MODULE.bazel": "26114f0c0b5e93018c0c066d6673f1a2c3737c7e90af95eff30cfee38d0bbac7",
-    "https://bcr.bazel.build/modules/rules_python/0.23.1/MODULE.bazel": "49ffccf0511cb8414de28321f5fcf2a31312b47c40cc21577144b7447f2bf300",
-    "https://bcr.bazel.build/modules/rules_python/0.25.0/MODULE.bazel": "72f1506841c920a1afec76975b35312410eea3aa7b63267436bfb1dd91d2d382",
-    "https://bcr.bazel.build/modules/rules_python/0.28.0/MODULE.bazel": "cba2573d870babc976664a912539b320cbaa7114cd3e8f053c720171cde331ed",
-    "https://bcr.bazel.build/modules/rules_python/0.31.0/MODULE.bazel": "93a43dc47ee570e6ec9f5779b2e64c1476a6ce921c48cc9a1678a91dd5f8fd58",
-    "https://bcr.bazel.build/modules/rules_python/0.4.0/MODULE.bazel": "9208ee05fd48bf09ac60ed269791cf17fb343db56c8226a720fbb1cdf467166c",
-    "https://bcr.bazel.build/modules/rules_python/1.3.0/MODULE.bazel": "8361d57eafb67c09b75bf4bbe6be360e1b8f4f18118ab48037f2bd50aa2ccb13",
-    "https://bcr.bazel.build/modules/rules_python/1.3.0/source.json": "25932f917cd279c7baefa6cb1d3fa8750a7a29de522024449b19af6eab51f4a0",
-    "https://bcr.bazel.build/modules/rules_shell/0.2.0/MODULE.bazel": "fda8a652ab3c7d8fee214de05e7a9916d8b28082234e8d2c0094505c5268ed3c",
-    "https://bcr.bazel.build/modules/rules_shell/0.3.0/MODULE.bazel": "de4402cd12f4cc8fda2354fce179fdb068c0b9ca1ec2d2b17b3e21b24c1a937b",
-    "https://bcr.bazel.build/modules/rules_shell/0.3.0/source.json": "c55ed591aa5009401ddf80ded9762ac32c358d2517ee7820be981e2de9756cf3",
-    "https://bcr.bazel.build/modules/rules_swift/1.16.0/MODULE.bazel": "4a09f199545a60d09895e8281362b1ff3bb08bbde69c6fc87aff5b92fcc916ca",
-    "https://bcr.bazel.build/modules/rules_swift/2.4.0/MODULE.bazel": "1639617eb1ede28d774d967a738b4a68b0accb40650beadb57c21846beab5efd",
-    "https://bcr.bazel.build/modules/rules_swift/2.4.0/source.json": "a6577f57f9febbdc015a01f2a8f3487422032f134d6c61d18ed8e8ca3b9acc7c",
-    "https://bcr.bazel.build/modules/stardoc/0.5.1/MODULE.bazel": "1a05d92974d0c122f5ccf09291442580317cdd859f07a8655f1db9a60374f9f8",
-    "https://bcr.bazel.build/modules/stardoc/0.5.3/MODULE.bazel": "c7f6948dae6999bf0db32c1858ae345f112cacf98f174c7a8bb707e41b974f1c",
-    "https://bcr.bazel.build/modules/stardoc/0.7.0/MODULE.bazel": "05e3d6d30c099b6770e97da986c53bd31844d7f13d41412480ea265ac9e8079c",
-    "https://bcr.bazel.build/modules/stardoc/0.7.2/MODULE.bazel": "fc152419aa2ea0f51c29583fab1e8c99ddefd5b3778421845606ee628629e0e5",
-    "https://bcr.bazel.build/modules/stardoc/0.7.2/source.json": "58b029e5e901d6802967754adf0a9056747e8176f017cfe3607c0851f4d42216",
-    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/MODULE.bazel": "5e463fbfba7b1701d957555ed45097d7f984211330106ccd1352c6e0af0dcf91",
-    "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/source.json": "32bd87e5f4d7acc57c5b2ff7c325ae3061d5e242c0c4c214ae87e0f1c13e54cb",
-    "https://bcr.bazel.build/modules/upb/0.0.0-20220923-a547704/MODULE.bazel": "7298990c00040a0e2f121f6c32544bab27d4452f80d9ce51349b1a28f3005c43",
-    "https://bcr.bazel.build/modules/zlib/1.2.11/MODULE.bazel": "07b389abc85fdbca459b69e2ec656ae5622873af3f845e1c9d80fe179f3effa0",
-    "https://bcr.bazel.build/modules/zlib/1.2.12/MODULE.bazel": "3b1a8834ada2a883674be8cbd36ede1b6ec481477ada359cd2d3ddc562340b27",
-    "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.3/MODULE.bazel": "af322bc08976524477c79d1e45e241b6efbeb918c497e8840b8ab116802dda79",
-    "https://bcr.bazel.build/modules/zlib/1.3.1.bcr.3/source.json": "2be409ac3c7601245958cd4fcdff4288be79ed23bd690b4b951f500d54ee6e7d",
-    "https://bcr.bazel.build/modules/zlib/1.3.1/MODULE.bazel": "751c9940dcfe869f5f7274e1295422a34623555916eb98c174c1e945594bf198"
-  },
-  "selectedYankedVersions": {},
-  "moduleExtensions": {
-    "@@rules_java~//java:rules_java_deps.bzl%compatibility_proxy": {
-      "general": {
-        "bzlTransitiveDigest": "C4xqrMy1wN4iuTN6Z2eCm94S5XingHhD6uwrIXvCxVI=",
-        "usagesDigest": "pwHZ+26iLgQdwvdZeA5wnAjKnNI3y6XO2VbhOTeo5h8=",
-        "recordedFileInputs": {},
-        "recordedDirentsInputs": {},
-        "envVariables": {},
-        "generatedRepoSpecs": {
-          "compatibility_proxy": {
-            "bzlFile": "@@rules_java~//java:rules_java_deps.bzl",
-            "ruleClassName": "_compatibility_proxy_repo_rule",
-            "attributes": {}
-          }
-        },
-        "recordedRepoMappingEntries": [
-          [
-            "rules_java~",
-            "bazel_tools",
-            "bazel_tools"
-          ]
-        ]
-      }
-    },
-    "@@rules_kotlin~//src/main/starlark/core/repositories:bzlmod_setup.bzl%rules_kotlin_extensions": {
-      "general": {
-        "bzlTransitiveDigest": "eecmTsmdIQveoA97hPtH3/Ej/kugbdCI24bhXIXaly8=",
-        "usagesDigest": "aJF6fLy82rR95Ff5CZPAqxNoFgOMLMN5ImfBS0nhnkg=",
-        "recordedFileInputs": {},
-        "recordedDirentsInputs": {},
-        "envVariables": {},
-        "generatedRepoSpecs": {
-          "com_github_jetbrains_kotlin_git": {
-            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:compiler.bzl",
-            "ruleClassName": "kotlin_compiler_git_repository",
-            "attributes": {
-              "urls": [
-                "https://github.com/JetBrains/kotlin/releases/download/v1.9.23/kotlin-compiler-1.9.23.zip"
-              ],
-              "sha256": "93137d3aab9afa9b27cb06a824c2324195c6b6f6179d8a8653f440f5bd58be88"
-            }
-          },
-          "com_github_jetbrains_kotlin": {
-            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:compiler.bzl",
-            "ruleClassName": "kotlin_capabilities_repository",
-            "attributes": {
-              "git_repository_name": "com_github_jetbrains_kotlin_git",
-              "compiler_version": "1.9.23"
-            }
-          },
-          "com_github_google_ksp": {
-            "bzlFile": "@@rules_kotlin~//src/main/starlark/core/repositories:ksp.bzl",
-            "ruleClassName": "ksp_compiler_plugin_repository",
-            "attributes": {
-              "urls": [
-                "https://github.com/google/ksp/releases/download/1.9.23-1.0.20/artifacts.zip"
-              ],
-              "sha256": "ee0618755913ef7fd6511288a232e8fad24838b9af6ea73972a76e81053c8c2d",
-              "strip_version": "1.9.23-1.0.20"
-            }
-          },
-          "com_github_pinterest_ktlint": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_file",
-            "attributes": {
-              "sha256": "01b2e0ef893383a50dbeb13970fe7fa3be36ca3e83259e01649945b09d736985",
-              "urls": [
-                "https://github.com/pinterest/ktlint/releases/download/1.3.0/ktlint"
-              ],
-              "executable": true
-            }
-          },
-          "rules_android": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "sha256": "cd06d15dd8bb59926e4d65f9003bfc20f9da4b2519985c27e190cddc8b7a7806",
-              "strip_prefix": "rules_android-0.1.1",
-              "urls": [
-                "https://github.com/bazelbuild/rules_android/archive/v0.1.1.zip"
-              ]
-            }
-          }
-        },
-        "recordedRepoMappingEntries": [
-          [
-            "rules_kotlin~",
-            "bazel_tools",
-            "bazel_tools"
-          ]
-        ]
-      }
-    },
-    "@@rules_python~//python/uv:uv.bzl%uv": {
-      "general": {
-        "bzlTransitiveDigest": "Xpqjnjzy6zZ90Es9Wa888ZLHhn7IsNGbph/e6qoxzw8=",
-        "usagesDigest": "qI5PVlIum/YAnGJg5oXGHzDkMFWt2aNSUZY4G8PBbic=",
-        "recordedFileInputs": {},
-        "recordedDirentsInputs": {},
-        "envVariables": {},
-        "generatedRepoSpecs": {
-          "uv": {
-            "bzlFile": "@@rules_python~//python/uv/private:uv_toolchains_repo.bzl",
-            "ruleClassName": "uv_toolchains_repo",
-            "attributes": {
-              "toolchain_type": "'@@rules_python~//python/uv:uv_toolchain_type'",
-              "toolchain_names": [
-                "none"
-              ],
-              "toolchain_implementations": {
-                "none": "'@@rules_python~//python:none'"
-              },
-              "toolchain_compatible_with": {
-                "none": [
-                  "@platforms//:incompatible"
-                ]
-              },
-              "toolchain_target_settings": {}
-            }
-          }
-        },
-        "recordedRepoMappingEntries": [
-          [
-            "rules_python~",
-            "platforms",
-            "platforms"
-          ]
-        ]
-      }
-    },
-    "@@rules_swift~//swift:extensions.bzl%non_module_deps": {
-      "general": {
-        "bzlTransitiveDigest": "l+Zu+SMObRQy3DG2LEw0eGVPkYRnyVj+M1QyR5AAFmM=",
-        "usagesDigest": "l2vIL7SL4tJqHIVLWd78Y/ym+r0II64lmvoX8o+0Bb0=",
-        "recordedFileInputs": {},
-        "recordedDirentsInputs": {},
-        "envVariables": {},
-        "generatedRepoSpecs": {
-          "com_github_apple_swift_protobuf": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-protobuf/archive/1.20.2.tar.gz"
-              ],
-              "sha256": "3fb50bd4d293337f202d917b6ada22f9548a0a0aed9d9a4d791e6fbd8a246ebb",
-              "strip_prefix": "swift-protobuf-1.20.2/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_protobuf/BUILD.overlay"
-            }
-          },
-          "com_github_grpc_grpc_swift": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/grpc/grpc-swift/archive/1.16.0.tar.gz"
-              ],
-              "sha256": "58b60431d0064969f9679411264b82e40a217ae6bd34e17096d92cc4e47556a5",
-              "strip_prefix": "grpc-swift-1.16.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_grpc_grpc_swift/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_docc_symbolkit": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-docc-symbolkit/archive/refs/tags/swift-5.10-RELEASE.tar.gz"
-              ],
-              "sha256": "de1d4b6940468ddb53b89df7aa1a81323b9712775b0e33e8254fa0f6f7469a97",
-              "strip_prefix": "swift-docc-symbolkit-swift-5.10-RELEASE",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_docc_symbolkit/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_nio": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-nio/archive/2.42.0.tar.gz"
-              ],
-              "sha256": "e3304bc3fb53aea74a3e54bd005ede11f6dc357117d9b1db642d03aea87194a0",
-              "strip_prefix": "swift-nio-2.42.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_nio_http2": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-nio-http2/archive/1.26.0.tar.gz"
-              ],
-              "sha256": "f0edfc9d6a7be1d587e5b403f2d04264bdfae59aac1d74f7d974a9022c6d2b25",
-              "strip_prefix": "swift-nio-http2-1.26.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_http2/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_nio_transport_services": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-nio-transport-services/archive/1.15.0.tar.gz"
-              ],
-              "sha256": "f3498dafa633751a52b9b7f741f7ac30c42bcbeb3b9edca6d447e0da8e693262",
-              "strip_prefix": "swift-nio-transport-services-1.15.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_transport_services/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_nio_extras": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-nio-extras/archive/1.4.0.tar.gz"
-              ],
-              "sha256": "4684b52951d9d9937bb3e8ccd6b5daedd777021ef2519ea2f18c4c922843b52b",
-              "strip_prefix": "swift-nio-extras-1.4.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_extras/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_log": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-log/archive/1.4.4.tar.gz"
-              ],
-              "sha256": "48fe66426c784c0c20031f15dc17faf9f4c9037c192bfac2f643f65cb2321ba0",
-              "strip_prefix": "swift-log-1.4.4/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_log/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_nio_ssl": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-nio-ssl/archive/2.23.0.tar.gz"
-              ],
-              "sha256": "4787c63f61dd04d99e498adc3d1a628193387e41efddf8de19b8db04544d016d",
-              "strip_prefix": "swift-nio-ssl-2.23.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_nio_ssl/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_collections": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-collections/archive/1.0.4.tar.gz"
-              ],
-              "sha256": "d9e4c8a91c60fb9c92a04caccbb10ded42f4cb47b26a212bc6b39cc390a4b096",
-              "strip_prefix": "swift-collections-1.0.4/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_collections/BUILD.overlay"
-            }
-          },
-          "com_github_apple_swift_atomics": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "urls": [
-                "https://github.com/apple/swift-atomics/archive/1.1.0.tar.gz"
-              ],
-              "sha256": "1bee7f469f7e8dc49f11cfa4da07182fbc79eab000ec2c17bfdce468c5d276fb",
-              "strip_prefix": "swift-atomics-1.1.0/",
-              "build_file": "@@rules_swift~//third_party:com_github_apple_swift_atomics/BUILD.overlay"
-            }
-          },
-          "build_bazel_rules_swift_index_import": {
-            "bzlFile": "@@bazel_tools//tools/build_defs/repo:http.bzl",
-            "ruleClassName": "http_archive",
-            "attributes": {
-              "build_file": "@@rules_swift~//third_party:build_bazel_rules_swift_index_import/BUILD.overlay",
-              "canonical_id": "index-import-5.8",
-              "urls": [
-                "https://github.com/MobileNativeFoundation/index-import/releases/download/5.8.0.1/index-import.tar.gz"
-              ],
-              "sha256": "28c1ffa39d99e74ed70623899b207b41f79214c498c603915aef55972a851a15"
-            }
-          },
-          "build_bazel_rules_swift_local_config": {
-            "bzlFile": "@@rules_swift~//swift/internal:swift_autoconfiguration.bzl",
-            "ruleClassName": "swift_autoconfiguration",
-            "attributes": {}
-          }
-        },
-        "recordedRepoMappingEntries": [
-          [
-            "rules_swift~",
-            "bazel_tools",
-            "bazel_tools"
-          ]
-        ]
-      }
-    }
-  }
-}

sparkle_workspace/WORKSPACE.bazel

@@ -1,3 +0,0 @@
-# This file marks sparkle_workspace as a separate Bazel workspace.
-# It prevents Bazel from looking up to the parent directory's workspace.
-# The actual dependencies are defined in MODULE.bazel (bzlmod).

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

@@ -66,6 +66,14 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "shardok_latency_trace",
+    srcs = ["ShardokLatencyTrace.cpp"],
+    hdrs = ["ShardokLatencyTrace.hpp"],
+    copts = COPTS,
+    visibility = ["//visibility:public"],
+)
+
 cc_library(
     name = "repeated_proto_utils",
     srcs = [],

src/main/cpp/net/eagle0/common/RandomGenerator.cpp

@@ -88,6 +88,11 @@ StdLibraryGenerator::StdLibraryGenerator() : RandomGenerator() {
     engine.seed(static_cast<std::mt19937_64::result_type>(std::time(nullptr)));
 }
 
+StdLibraryGenerator::StdLibraryGenerator(const std::mt19937_64::result_type seed)
+    : RandomGenerator() {
+    engine.seed(seed);
+}
+
 auto StdLibraryGenerator::IntBetween(const int min, const int max) -> int {
     std::uniform_int_distribution<int> unifInt(min, max - 1);
     return unifInt(engine);

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

@@ -51,6 +51,7 @@ private:
 
 public:
     StdLibraryGenerator();
+    explicit StdLibraryGenerator(std::mt19937_64::result_type seed);
 
     auto IntBetween(int min, int max) -> int override;  // inclusive, exclusive (min<=return<max)
 };

src/main/cpp/net/eagle0/common/ShardokLatencyTrace.cpp

@@ -0,0 +1,101 @@
+#include "ShardokLatencyTrace.hpp"
+
+#include <cstdlib>
+#include <iostream>
+#include <mutex>
+#include <sstream>
+
+namespace net::eagle0::common {
+namespace {
+
+auto ReadEnvEnabled() -> bool {
+    const char* value = std::getenv("EAGLE0_SHARDOK_LATENCY_TRACE");
+    if (value == nullptr) { return false; }
+    const std::string text(value);
+    return text == "1" || text == "true" || text == "TRUE" || text == "yes" || text == "YES";
+}
+
+auto TraceEnabled() -> bool {
+    static const bool enabled = ReadEnvEnabled();
+    return enabled;
+}
+
+auto ReadGameFilter() -> std::string {
+    const char* value = std::getenv("EAGLE0_SHARDOK_LATENCY_GAME_ID");
+    return value == nullptr ? "" : std::string(value);
+}
+
+auto GameFilter() -> const std::string& {
+    static const std::string filter = ReadGameFilter();
+    return filter;
+}
+
+auto JsonEscape(std::string_view value) -> std::string {
+    std::ostringstream out;
+    for (const char c : value) {
+        switch (c) {
+            case '"': out << "\\\""; break;
+            case '\\': out << "\\\\"; break;
+            case '\n': out << "\\n"; break;
+            case '\r': out << "\\r"; break;
+            case '\t': out << "\\t"; break;
+            default: out << c; break;
+        }
+    }
+    return out.str();
+}
+
+auto LogMutex() -> std::mutex& {
+    static auto mutex = new std::mutex();
+    return *mutex;
+}
+
+}  // namespace
+
+auto ShardokLatencyTraceEnabledForGame(std::string_view gameId) -> bool {
+    if (!TraceEnabled()) { return false; }
+    const std::string& filter = GameFilter();
+    return filter.empty() || filter == gameId;
+}
+
+void EmitShardokLatencyTrace(
+        std::string_view event,
+        std::string_view gameId,
+        const ShardokLatencyFields& fields,
+        std::chrono::steady_clock::duration duration) {
+    if (!ShardokLatencyTraceEnabledForGame(gameId)) { return; }
+
+    const auto durationMs =
+            std::chrono::duration_cast<std::chrono::microseconds>(duration).count() / 1000.0;
+
+    std::ostringstream out;
+    out << "{\"event\":\"shardok_latency\","
+        << "\"component\":\"shardok\","
+        << "\"span\":\"" << JsonEscape(event) << "\","
+        << "\"game_id\":\"" << JsonEscape(gameId) << "\","
+        << "\"duration_ms\":" << durationMs;
+    for (const auto& [key, value] : fields) {
+        out << ",\"" << JsonEscape(key) << "\":\"" << JsonEscape(value) << "\"";
+    }
+    out << "}";
+
+    std::scoped_lock lock(LogMutex());
+    std::cerr << out.str() << std::endl;
+}
+
+ScopedShardokLatencyTrace::ScopedShardokLatencyTrace(
+        std::string event,
+        std::string gameId,
+        ShardokLatencyFields fields)
+    : event_(std::move(event)),
+      gameId_(std::move(gameId)),
+      fields_(std::move(fields)) {
+    if (ShardokLatencyTraceEnabledForGame(gameId_)) { start_ = std::chrono::steady_clock::now(); }
+}
+
+ScopedShardokLatencyTrace::~ScopedShardokLatencyTrace() {
+    if (!start_.has_value()) { return; }
+    EmitShardokLatencyTrace(event_, gameId_, fields_, std::chrono::steady_clock::now() - *start_);
+}
+
+}  // namespace net::eagle0::common

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

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <chrono>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace net::eagle0::common {
+
+using ShardokLatencyFields = std::vector<std::pair<std::string, std::string>>;
+
+auto ShardokLatencyTraceEnabledForGame(std::string_view gameId) -> bool;
+
+void EmitShardokLatencyTrace(
+        std::string_view event,
+        std::string_view gameId,
+        const ShardokLatencyFields& fields,
+        std::chrono::steady_clock::duration duration);
+
+class ScopedShardokLatencyTrace {
+public:
+    ScopedShardokLatencyTrace(
+            std::string event,
+            std::string gameId,
+            ShardokLatencyFields fields = {});
+    ~ScopedShardokLatencyTrace();
+
+    ScopedShardokLatencyTrace(const ScopedShardokLatencyTrace&) = delete;
+    auto operator=(const ScopedShardokLatencyTrace&) -> ScopedShardokLatencyTrace& = delete;
+    ScopedShardokLatencyTrace(ScopedShardokLatencyTrace&&) = delete;
+    auto operator=(ScopedShardokLatencyTrace&&) -> ScopedShardokLatencyTrace& = delete;
+
+private:
+    std::string event_;
+    std::string gameId_;
+    ShardokLatencyFields fields_;
+    std::optional<std::chrono::steady_clock::time_point> start_;
+};
+
+}  // namespace net::eagle0::common

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

@@ -13,6 +13,7 @@
 #include <cstring>
 #include <fstream>
 #include <sstream>
+#include <stdexcept>
 #include <string>
 #include <vector>
 
@@ -147,6 +148,9 @@ public:
 
     static auto FromPath(const string& path) -> byte_vector {
         std::ifstream inputFileStream(path, std::ios::binary | std::ios::ate);
+        if (!inputFileStream.is_open()) {
+            throw std::runtime_error("Failed to open file: " + path);
+        }
         const std::streamsize size = inputFileStream.tellg();
         inputFileStream.seekg(0, std::ios::beg);
         byte_vector serializedGame((size_t(size)));

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

@@ -21,7 +21,14 @@ namespace shardok::mcts {
 
 AbstractMCTSAI::AbstractMCTSAI(MCTSPlayerId playerId, MCTSConfig config)
     : playerId_(playerId),
-      config_(config) {}
+      config_(config),
+      randomEngine_(config.randomSeed == 0 ? std::random_device{}() : config.randomSeed) {}
+
+void AbstractMCTSAI::SetConfig(const MCTSConfig& newConfig) {
+    config_ = newConfig;
+    std::lock_guard lock(randomEngineMutex_);
+    randomEngine_.seed(newConfig.randomSeed == 0 ? std::random_device{}() : newConfig.randomSeed);
+}
 
 auto AbstractMCTSAI::Search(
         const MCTSGameEngine& engine,
@@ -350,22 +357,19 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
         // 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++) {
+            for (size_t i = 0; i < node->outcomeProbabilities.size(); i++) {
                 const double prob = node->outcomeProbabilities[i];
-                const double childImmediate = node->children[i]->immediateScore;
+                const double childImmediate = i < node->children.size()
+                                                      ? node->children[i]->immediateScore
+                                                      : node->unvisitedOutcomeScore;
                 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;
             }
+            node->immediateScore = expectedImmediate;
+            // 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();
@@ -396,8 +400,14 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
 
     const auto& action = nodeActions[actionIndex];
 
-    const double actionWeight =
-            actionIndex < actionWeights.size() ? actionWeights[actionIndex] : 1.0;
+    double totalActionWeight = 0.0;
+    for (const double weight : actionWeights) { totalActionWeight += std::max(0.0, weight); }
+
+    const double rawActionWeight =
+            actionIndex < actionWeights.size() ? std::max(0.0, actionWeights[actionIndex]) : 1.0;
+    const double actionWeight = totalActionWeight > 0.0
+                                        ? rawActionWeight / totalActionWeight
+                                        : 1.0 / static_cast<double>(nodeActions.size());
 
     // Check if this action requires a chance node
     if (action->requiresChanceNode()) {
@@ -417,15 +427,16 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
         // Get outcome information from engine
         const auto outcomeInfo = engine.getBinaryOutcomeInfo(*node->gameState, *action);
 
-        // Set up outcome metadata (2 outcomes for binary actions)
+        // Set up outcome metadata.
         chanceNode->outcomeProbabilities = outcomeInfo.getProbabilities();
         chanceNode->outcomeRolls = outcomeInfo.getRepresentativeRolls();
-        chanceNode->totalActions = 2;  // Binary: success and failure
+        chanceNode->totalActions = chanceNode->outcomeProbabilities.size();
 
         // 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;
+        chanceNode->unvisitedOutcomeScore = chanceNode->immediateScore;
 
         // Set parent and add to children
         chanceNode->parent = node;
@@ -602,29 +613,20 @@ auto AbstractMCTSAI::MCTSBackpropagation(
             // 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
+            bool hasVisitedChild = false;
 
+            for (size_t i = 0; i < node->outcomeProbabilities.size(); i++) {
                 const double probability = node->outcomeProbabilities[i];
-                const double childValue = child->lookaheadScore;
+                double childValue = node->unvisitedOutcomeScore;
+                if (i < node->children.size() && node->children[i]->visitCount > 0) {
+                    childValue = node->children[i]->lookaheadScore;
+                    hasVisitedChild = true;
+                }
                 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;
-                }
+            if (hasVisitedChild) {
                 node->lookaheadScore = expectedValue;
             } else {
                 // No outcomes visited yet, fall back to average
@@ -705,23 +707,21 @@ auto AbstractMCTSAI::SelectSimulationAction(
                 "MCTS tree building or game state");
     }
 
-    thread_local std::mt19937 gen(std::random_device{}());
-
     switch (config_.simulationPolicy) {
         case MCTSSimulationPolicy::RANDOM: {
             std::uniform_int_distribution<size_t> dis(0, actions.size() - 1);
-            return dis(gen);
+            return SampleDistribution(dis);
         }
 
         case MCTSSimulationPolicy::FILTERED_RANDOM: {
             if (const auto filteredIndices = engine.filterActions(actions, state);
                 !filteredIndices.empty()) {
                 std::uniform_int_distribution<size_t> dis(0, filteredIndices.size() - 1);
-                return filteredIndices[dis(gen)];
+                return filteredIndices[SampleDistribution(dis)];
             }
             // Fall back to random
             std::uniform_int_distribution<size_t> dis(0, actions.size() - 1);
-            return dis(gen);
+            return SampleDistribution(dis);
         }
 
         case MCTSSimulationPolicy::BEST_IMMEDIATE: {
@@ -790,7 +790,7 @@ auto AbstractMCTSAI::SelectSimulationAction(
 
             // Select based on weights
             std::discrete_distribution<> dis(weights.begin(), weights.end());
-            return scores[dis(gen)].first;
+            return scores[SampleDistribution(dis)].first;
         }
 
         case MCTSSimulationPolicy::WEIGHTED_HEURISTIC: {
@@ -820,13 +820,13 @@ auto AbstractMCTSAI::SelectSimulationAction(
 
             // Select based on heuristic weights using discrete_distribution
             std::discrete_distribution<> dis(validWeights.begin(), validWeights.end());
-            return validIndices[dis(gen)];
+            return validIndices[SampleDistribution(dis)];
         }
     }
 
     // Default to random
     std::uniform_int_distribution<size_t> dis(0, actions.size() - 1);
-    return dis(gen);
+    return SampleDistribution(dis);
 }
 
 auto AbstractMCTSAI::FindNodeAtDepthWithHash(

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

@@ -7,6 +7,8 @@
 
 #include <chrono>
 #include <memory>
+#include <mutex>
+#include <random>
 #include <unordered_map>
 #include <vector>
 
@@ -41,7 +43,7 @@ public:
 
     // Configuration
     [[nodiscard]] auto GetConfig() const -> const MCTSConfig& { return config_; }
-    void SetConfig(const MCTSConfig& newConfig) { config_ = newConfig; }
+    void SetConfig(const MCTSConfig& newConfig);
 
     [[nodiscard]] auto FindNodeAtDepthWithHash(
             const MCTSNode* root,
@@ -51,6 +53,8 @@ public:
 private:
     MCTSPlayerId playerId_;
     MCTSConfig config_;
+    mutable std::mt19937 randomEngine_;
+    mutable std::mutex randomEngineMutex_;
 
     // Transposition table: maps state hash -> minimum depth at which state was reached
     // Used to detect and penalize longer paths to the same game state
@@ -85,6 +89,13 @@ private:
             const std::vector<std::unique_ptr<MCTSAction>>& actions,
             bool isMaximizing) const -> size_t;
 
+    template<typename Distribution>
+    [[nodiscard]] auto SampleDistribution(Distribution& distribution) const ->
+            typename Distribution::result_type {
+        std::lock_guard lock(randomEngineMutex_);
+        return distribution(randomEngine_);
+    }
+
     // Logging
     static auto LogSearchResults(
             const MCTSNode* rootNode,
@@ -103,4 +114,4 @@ private:
 }  // namespace mcts
 }  // namespace shardok
 
-#endif  // EAGLE0_ABSTRACT_MCTSAI_HPP
+#endif  // EAGLE0_ABSTRACT_MCTSAI_HPP

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

@@ -6,6 +6,7 @@ cc_library(
     copts = COPTS,
     visibility = [
         "//src/main/cpp/net/eagle0/shardok/ai/mcts:__subpackages__",
+        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:__pkg__",
         "//src/test/cpp/net/eagle0/common/mcts:__subpackages__",
         "//src/test/cpp/net/eagle0/shardok/ai/mcts:__subpackages__",
     ],

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

@@ -54,6 +54,7 @@ struct MCTSNode {
     // 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
+    double unvisitedOutcomeScore = 0.0;        // Default value for outcomes not expanded yet
 
     // Game context
     MCTSPlayerId playerId;
@@ -274,4 +275,4 @@ struct MCTSNode {
 }  // namespace mcts
 }  // namespace shardok
 
-#endif  // EAGLE0_ABSTRACT_MCTSNODE_HPP
+#endif  // EAGLE0_ABSTRACT_MCTSNODE_HPP

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

@@ -51,10 +51,11 @@ struct MCTSConfig {
                                      // When evaluating a leaf at playerFlips < maxSimulationFlips,
                                      // simulate forward to this phase for fair comparison
                                      // (default 0 = evaluate leaves as-is, backward compatible)
+    uint32_t randomSeed = 0;         // 0 = seed nondeterministically
     std::string debugDumpPath = "";  // If non-empty, dump MCTS tree to this file path
 };
 
 }  // namespace mcts
 }  // namespace shardok
 
-#endif  // EAGLE0_MCTS_TYPES_HPP
+#endif  // EAGLE0_MCTS_TYPES_HPP

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

@@ -54,6 +54,12 @@ static auto IsDeterministic(const CommandType type) -> bool {
     }
 }
 
+static auto RandomnessSampleForRepeat(const int repeatIteration, const int maxRepeatCount)
+        -> double {
+    if (maxRepeatCount <= 1) { return 0.5; }
+    return static_cast<double>(repeatIteration) / static_cast<double>(maxRepeatCount - 1);
+}
+
 // Helper function to sort commands by score
 static auto CommandSorter(
         const AICommandEvaluator::IndexAndScore& l,
@@ -85,15 +91,15 @@ auto AICommandEvaluator::PerformLookahead(
         const ScoreValue currentUtility,
         const AIStrategy& attackerStrategy,
         const CoordsSet& allCastleCoords,
-        std::chrono::steady_clock::time_point deadline) const -> std::future<ScoreValue> {
+        std::chrono::steady_clock::time_point deadline) const -> std::future<EvaluationResult> {
     // Check transposition table before expensive computation
     auto cachedScore =
             g_transpositionTable.probe(innerEngine->GetCurrentGameState(), remainingLookahead, pid);
 
     if (cachedScore.has_value()) {
         // Return cached result immediately
-        std::promise<ScoreValue> p;
-        p.set_value(*cachedScore);
+        std::promise<EvaluationResult> p;
+        p.set_value(EvaluationResult{.score = *cachedScore, .completed = true});
         return p.get_future();
     }
     const auto nextUtility = currentUtility;
@@ -105,8 +111,8 @@ auto AICommandEvaluator::PerformLookahead(
         // table
         g_transpositionTable.store(innerEngine->GetCurrentGameState(), 1, pid, nextUtility);
 
-        std::promise<ScoreValue> p;
-        p.set_value(nextUtility);
+        std::promise<EvaluationResult> p;
+        p.set_value(EvaluationResult{.score = nextUtility, .completed = true});
         return p.get_future();
     }
 
@@ -131,16 +137,18 @@ auto AICommandEvaluator::PerformLookahead(
                  innerEngine,
                  pid,
                  nextUtility,
-                 remainingLookahead]() mutable -> ScoreValue {
-                    const auto [index, type, lookaheadScore, immediateScore] =
-                            bestCommandFuture.get();
+                 remainingLookahead]() mutable -> EvaluationResult {
+                    const auto bestCommand = bestCommandFuture.get();
+                    if (!bestCommand.completed) {
+                        return EvaluationResult{.score = nextUtility, .completed = false};
+                    }
 
                     ScoreValue resultScore;
-                    if (auto& nextCommand =
-                                innerEngine->GetAvailableCommandsForAIPlayer(pid)->at(index);
+                    if (auto& nextCommand = innerEngine->GetAvailableCommandsForAIPlayer(pid)->at(
+                                bestCommand.index);
                         nextCommand->GetCommandType() !=
                         net::eagle0::shardok::common::END_TURN_COMMAND) {
-                        resultScore = immediateScore;
+                        resultScore = bestCommand.immediateScore;
                     } else {
                         resultScore = nextUtility;
                     }
@@ -152,7 +160,7 @@ auto AICommandEvaluator::PerformLookahead(
                             pid,
                             resultScore);
 
-                    return resultScore;
+                    return EvaluationResult{.score = resultScore, .completed = true};
                 });
     }
 
@@ -160,8 +168,8 @@ auto AICommandEvaluator::PerformLookahead(
     g_transpositionTable
             .store(innerEngine->GetCurrentGameState(), remainingLookahead, pid, nextUtility);
 
-    std::promise<ScoreValue> p;
-    p.set_value(nextUtility);
+    std::promise<EvaluationResult> p;
+    p.set_value(EvaluationResult{.score = nextUtility, .completed = true});
     return p.get_future();
 }
 
@@ -180,10 +188,10 @@ auto AICommandEvaluator::EvaluateWithRandomness(
 
     // Check if we've exceeded the deadline
     if (std::chrono::steady_clock::now() > deadline) {
-        // Return with a default score and an empty future that resolves immediately
-        std::promise<ScoreValue> p;
-        p.set_value(0.0);  // Default timeout score
+        std::promise<EvaluationResult> p;
+        p.set_value(EvaluationResult{.score = 0.0, .completed = false});
         returnValue.immediateScore = 0.0;
+        returnValue.completed = false;
         returnValue.lookaheadScore = p.get_future();
         return returnValue;
     }
@@ -198,11 +206,12 @@ auto AICommandEvaluator::EvaluateWithRandomness(
             allCastleCoords);
 
     returnValue.immediateScore = innerUtility;
+    returnValue.completed = true;
 
     if (remainingLookahead <= 0) {
-        std::promise<ScoreValue> p;
+        std::promise<EvaluationResult> p;
         returnValue.lookaheadScore = p.get_future();
-        p.set_value(innerUtility);
+        p.set_value(EvaluationResult{.score = innerUtility, .completed = true});
     } else {
         auto lookaheadLambda = [this,
                                 pid,
@@ -213,7 +222,7 @@ auto AICommandEvaluator::EvaluateWithRandomness(
                                 attackerStrategy,
                                 innerUtility,
                                 &allCastleCoords,
-                                deadline]() -> ScoreValue {
+                                deadline]() -> EvaluationResult {
             auto lookaheadFuture = PerformLookahead(
                     pid,
                     isDefender,
@@ -231,7 +240,7 @@ auto AICommandEvaluator::EvaluateWithRandomness(
         auto launchPolicy = remainingLookahead == 1 ? std::launch::async : std::launch::deferred;
         returnValue.lookaheadScore = std::async(launchPolicy, lookaheadLambda);
 #else
-        std::promise<ScoreValue> p;
+        std::promise<EvaluationResult> p;
         returnValue.lookaheadScore = p.get_future();
         auto lambdaResult = lookaheadLambda();
         p.set_value(lambdaResult);
@@ -316,7 +325,8 @@ auto AICommandEvaluator::FindBestCommand(
         size_t index;
         CommandType type;
         ScoreValue immediateScore;
-        std::vector<std::future<ScoreValue>> lookaheadFutures;
+        bool immediateCompleted = true;
+        std::vector<std::future<EvaluationResult>> lookaheadFutures;
     };
 
     std::vector<CommandEvaluation> commandEvaluations(commandCount);
@@ -330,12 +340,12 @@ auto AICommandEvaluator::FindBestCommand(
         commandEvaluations[index].type = guessedCommandType;
 
         if (guessedCommandType == net::eagle0::shardok::common::END_TURN_COMMAND) {
-            std::promise<ScoreValue> p;
+            std::promise<EvaluationResult> p;
             commandEvaluations[index].lookaheadFutures.push_back(p.get_future());
-            p.set_value(currentUtility);
+            p.set_value(EvaluationResult{.score = currentUtility, .completed = true});
             commandEvaluations[index].immediateScore = currentUtility;
         } else if (IsDeterministic(guessedCommandType)) {
-            auto [immediateScore, lookaheadScore] = EvaluateWithRandomness(
+            auto evaluation = EvaluateWithRandomness(
                     pid,
                     isDefender,
                     originalIndex,
@@ -347,14 +357,16 @@ auto AICommandEvaluator::FindBestCommand(
                     allCastleCoords,
                     deadline);
 
-            commandEvaluations[index].immediateScore = immediateScore;
-            commandEvaluations[index].lookaheadFutures.push_back(std::move(lookaheadScore));
+            commandEvaluations[index].immediateScore = evaluation.immediateScore;
+            commandEvaluations[index].immediateCompleted = evaluation.completed;
+            commandEvaluations[index].lookaheadFutures.push_back(
+                    std::move(evaluation.lookaheadScore));
         } else if (guessedDescriptor->HasOdds()) {
             const auto successChancePercentile = guessedDescriptor->GetOddsPercentile();
             const double successChance = static_cast<double>(successChancePercentile) / 100.0;
 
             // Success attempt uses 1.0 - (successChance / 2) as the roll
-            auto [successImmediateScore, successLookaheadScore] = EvaluateWithRandomness(
+            auto successEvaluation = EvaluateWithRandomness(
                     pid,
                     isDefender,
                     originalIndex,
@@ -368,7 +380,7 @@ auto AICommandEvaluator::FindBestCommand(
                     deadline);
 
             // Failure attempt uses the average of (1 - successChance) and 0 as the roll
-            auto [failureImmediateScore, failureLookaheadScore] = EvaluateWithRandomness(
+            auto failureEvaluation = EvaluateWithRandomness(
                     pid,
                     isDefender,
                     originalIndex,
@@ -381,24 +393,35 @@ auto AICommandEvaluator::FindBestCommand(
                     allCastleCoords,
                     deadline);
 
-            commandEvaluations[index].immediateScore =
-                    std::lerp(failureImmediateScore, successImmediateScore, successChance);
+            commandEvaluations[index].immediateCompleted =
+                    failureEvaluation.completed && successEvaluation.completed;
+            commandEvaluations[index].immediateScore = std::lerp(
+                    failureEvaluation.immediateScore,
+                    successEvaluation.immediateScore,
+                    successChance);
 
-            auto successSF = successLookaheadScore.share();
-            auto failureSF = failureLookaheadScore.share();
+            auto successSF = successEvaluation.lookaheadScore.share();
+            auto failureSF = failureEvaluation.lookaheadScore.share();
             commandEvaluations[index].lookaheadFutures.push_back(std::async(
                     std::launch::deferred,
-                    [successSF, failureSF, successChance]() -> double {
-                        return std::lerp(failureSF.get(), successSF.get(), successChance);
+                    [successSF, failureSF, successChance]() -> EvaluationResult {
+                        const auto failure = failureSF.get();
+                        const auto success = successSF.get();
+                        if (!failure.completed || !success.completed) {
+                            return EvaluationResult{.score = 0.0, .completed = false};
+                        }
+                        return EvaluationResult{
+                                .score = std::lerp(failure.score, success.score, successChance),
+                                .completed = true};
                     }));
         } else {
             ScoreValue sum = 0.0;
-            for (int repeatIteration = 0; repeatIteration < maxRepeatCount; repeatIteration++) {
+            const int sampleCount = std::max(1, maxRepeatCount);
+            for (int repeatIteration = 0; repeatIteration < sampleCount; repeatIteration++) {
                 // In each iteration, use a double from [0, 1] as the random roll
-                auto sequence = std::vector{
-                        static_cast<double>(repeatIteration) /
-                        static_cast<double>(maxRepeatCount - 1)};
-                auto [immediateScore, lookaheadScore] = EvaluateWithRandomness(
+                auto sequence =
+                        std::vector{RandomnessSampleForRepeat(repeatIteration, sampleCount)};
+                auto evaluation = EvaluateWithRandomness(
                         pid,
                         isDefender,
                         originalIndex,
@@ -410,10 +433,12 @@ auto AICommandEvaluator::FindBestCommand(
                         allCastleCoords,
                         deadline);
 
-                sum += immediateScore;
-                commandEvaluations[index].lookaheadFutures.push_back(std::move(lookaheadScore));
+                if (!evaluation.completed) { commandEvaluations[index].immediateCompleted = false; }
+                sum += evaluation.immediateScore;
+                commandEvaluations[index].lookaheadFutures.push_back(
+                        std::move(evaluation.lookaheadScore));
             }
-            commandEvaluations[index].immediateScore = sum / maxRepeatCount;
+            commandEvaluations[index].immediateScore = sum / sampleCount;
         }
     }
 
@@ -427,19 +452,33 @@ auto AICommandEvaluator::FindBestCommand(
                 // Wait for all futures and compute final scores
                 for (auto& eval : evals) {
                     ScoreValue totalLookaheadScore = 0.0;
+                    bool completed = eval.immediateCompleted;
                     for (auto& future : eval.lookaheadFutures) {
-                        totalLookaheadScore += future.get();
+                        const auto lookahead = future.get();
+                        if (!lookahead.completed) { completed = false; }
+                        totalLookaheadScore += lookahead.score;
                     }
                     ScoreValue avgLookaheadScore =
                             eval.lookaheadFutures.empty()
                                     ? eval.immediateScore
                                     : totalLookaheadScore / eval.lookaheadFutures.size();
 
+                    if (!completed) { continue; }
+
                     allResults.push_back(IndexAndScore{
                             .index = eval.index,
                             .type = eval.type,
                             .lookaheadScore = avgLookaheadScore,
-                            .immediateScore = eval.immediateScore});
+                            .immediateScore = eval.immediateScore,
+                            .completed = true});
+                }
+                if (allResults.empty()) {
+                    return IndexAndScore{
+                            .index = 0,
+                            .type = net::eagle0::shardok::common::UNKNOWN_COMMAND,
+                            .lookaheadScore = 0.0,
+                            .immediateScore = 0.0,
+                            .completed = false};
                 }
                 // Find the best command using the existing sorter
                 auto bestIt = std::ranges::max_element(allResults, CommandSorter);
@@ -457,12 +496,12 @@ auto AICommandEvaluator::EvaluateCommand(
         const ScoreValue currentUtility,
         const CoordsSet& allCastleCoords,
         const size_t commandIndex,
-        std::chrono::steady_clock::time_point deadline) const -> std::future<ScoreValue> {
+        std::chrono::steady_clock::time_point deadline) const -> std::future<EvaluationResult> {
     const CommandListSPtr guessedDescriptors = guessedEngine.GetAvailableCommandsForAIPlayer(pid);
 
     if (commandIndex >= guessedDescriptors->size()) {
-        std::promise<ScoreValue> p;
-        p.set_value(currentUtility);
+        std::promise<EvaluationResult> p;
+        p.set_value(EvaluationResult{.score = currentUtility, .completed = true});
         return p.get_future();
     }
 
@@ -470,11 +509,11 @@ auto AICommandEvaluator::EvaluateCommand(
 
     if (const auto guessedCommandType = guessedDescriptor->GetCommandType();
         guessedCommandType == net::eagle0::shardok::common::END_TURN_COMMAND) {
-        std::promise<ScoreValue> p;
-        p.set_value(currentUtility);
+        std::promise<EvaluationResult> p;
+        p.set_value(EvaluationResult{.score = currentUtility, .completed = true});
         return p.get_future();
     } else if (IsDeterministic(guessedCommandType)) {
-        auto [immediateScore, lookaheadScore] = EvaluateWithRandomness(
+        auto evaluation = EvaluateWithRandomness(
                 pid,
                 isDefender,
                 commandIndex,
@@ -485,13 +524,13 @@ auto AICommandEvaluator::EvaluateCommand(
                 attackerStrategy,
                 allCastleCoords,
                 deadline);
-        return std::move(lookaheadScore);
+        return std::move(evaluation.lookaheadScore);
     } else if (guessedDescriptor->HasOdds()) {
         const auto successChancePercentile = guessedDescriptor->GetOddsPercentile();
         const double successChance = static_cast<double>(successChancePercentile) / 100.0;
 
         // Success attempt
-        auto [successImmediateScore, successLookaheadScore] = EvaluateWithRandomness(
+        auto successEvaluation = EvaluateWithRandomness(
                 pid,
                 isDefender,
                 commandIndex,
@@ -504,7 +543,7 @@ auto AICommandEvaluator::EvaluateCommand(
                 deadline);
 
         // Failure attempt
-        auto [failureImmediateScore, failureLookaheadScore] = EvaluateWithRandomness(
+        auto failureEvaluation = EvaluateWithRandomness(
                 pid,
                 isDefender,
                 commandIndex,
@@ -517,20 +556,29 @@ auto AICommandEvaluator::EvaluateCommand(
                 deadline);
 
         // Return weighted average of success and failure
-        auto successSF = successLookaheadScore.share();
-        auto failureSF = failureLookaheadScore.share();
-        return std::async(std::launch::deferred, [successSF, failureSF, successChance]() -> double {
-            return std::lerp(failureSF.get(), successSF.get(), successChance);
-        });
+        auto successSF = successEvaluation.lookaheadScore.share();
+        auto failureSF = failureEvaluation.lookaheadScore.share();
+        return std::async(
+                std::launch::deferred,
+                [successSF, failureSF, successChance]() -> EvaluationResult {
+                    const auto failure = failureSF.get();
+                    const auto success = successSF.get();
+                    if (!failure.completed || !success.completed) {
+                        return EvaluationResult{.score = 0.0, .completed = false};
+                    }
+                    return EvaluationResult{
+                            .score = std::lerp(failure.score, success.score, successChance),
+                            .completed = true};
+                });
     } else {
         // For non-deterministic commands without odds, use multiple attempts
-        std::vector<std::future<ScoreValue>> lookaheadFutures;
-        lookaheadFutures.reserve(maxRepeatCount);
+        std::vector<std::future<EvaluationResult>> lookaheadFutures;
+        const int sampleCount = std::max(1, maxRepeatCount);
+        lookaheadFutures.reserve(sampleCount);
 
-        for (int repeatIteration = 0; repeatIteration < maxRepeatCount; repeatIteration++) {
-            auto sequence = std::vector{
-                    static_cast<double>(repeatIteration) / static_cast<double>(maxRepeatCount - 1)};
-            auto [immediateScore, lookaheadScore] = EvaluateWithRandomness(
+        for (int repeatIteration = 0; repeatIteration < sampleCount; repeatIteration++) {
+            auto sequence = std::vector{RandomnessSampleForRepeat(repeatIteration, sampleCount)};
+            auto evaluation = EvaluateWithRandomness(
                     pid,
                     isDefender,
                     commandIndex,
@@ -542,17 +590,25 @@ auto AICommandEvaluator::EvaluateCommand(
                     allCastleCoords,
                     deadline);
 
-            lookaheadFutures.push_back(std::move(lookaheadScore));
+            lookaheadFutures.push_back(std::move(evaluation.lookaheadScore));
         }
 
         // Return a future that computes the average when needed
         return std::async(
                 std::launch::deferred,
                 [lookaheadFutures = std::move(lookaheadFutures),
-                 maxRepeatCount]() mutable -> double {
+                 sampleCount]() mutable -> EvaluationResult {
                     ScoreValue total = 0.0;
-                    for (auto& future : lookaheadFutures) { total += future.get(); }
-                    return total / maxRepeatCount;
+                    bool completed = true;
+                    for (auto& future : lookaheadFutures) {
+                        const auto result = future.get();
+                        if (!result.completed) { completed = false; }
+                        total += result.score;
+                    }
+                    if (!completed) { return EvaluationResult{.score = 0.0, .completed = false}; }
+                    return EvaluationResult{
+                            .score = total / static_cast<ScoreValue>(sampleCount),
+                            .completed = true};
                 });
     }
 }

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

@@ -38,6 +38,11 @@ public:
             BattalionTypeGetter battalionTypeGetter);  // Pass by value
 
     /// Evaluates the score for a particular command index with lookahead.
+    struct EvaluationResult {
+        ScoreValue score;
+        bool completed;
+    };
+
     [[nodiscard]] auto EvaluateCommand(
             PlayerId pid,
             bool isDefender,
@@ -48,7 +53,7 @@ public:
             ScoreValue currentUtility,
             const CoordsSet& allCastleCoords,
             size_t commandIndex,
-            std::chrono::steady_clock::time_point deadline) const -> std::future<ScoreValue>;
+            std::chrono::steady_clock::time_point deadline) const -> std::future<EvaluationResult>;
 
     /// Find the best command among all available commands at the given depth.
     struct IndexAndScore {
@@ -56,6 +61,7 @@ public:
         CommandType type;
         ScoreValue lookaheadScore;
         ScoreValue immediateScore;
+        bool completed;
     };
 
     [[nodiscard]] auto FindBestCommand(
@@ -76,7 +82,8 @@ private:
 
     struct ImmediateAndLookaheadScore {
         ScoreValue immediateScore;
-        std::future<ScoreValue> lookaheadScore;
+        bool completed;
+        std::future<EvaluationResult> lookaheadScore;
     };
 
     /// Recursive lookahead calculator
@@ -89,7 +96,7 @@ private:
             ScoreValue currentUtility,
             const AIStrategy& attackerStrategy,
             const CoordsSet& allCastleCoords,
-            std::chrono::steady_clock::time_point deadline) const -> std::future<ScoreValue>;
+            std::chrono::steady_clock::time_point deadline) const -> std::future<EvaluationResult>;
 
     /// Evaluate single command execution with randomness handling
     [[nodiscard]] auto EvaluateWithRandomness(

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

@@ -32,6 +32,32 @@ CoordsSet AICommandFilter::BuildEnemyLocations(const GameStateW& gameState, Play
     return enemyLocations;
 }
 
+std::vector<size_t> AICommandFilter::FilterLoopingCommands(
+        const CommandListSPtr& commands,
+        const GameStateW& gameState) {
+    std::vector<size_t> filteredIndices;
+    filteredIndices.reserve(commands->size());
+
+    for (size_t i = 0; i < commands->size(); ++i) {
+        const auto& cmd = (*commands)[i];
+
+        bool shouldFilter = false;
+
+        if (cmd->GetCommandType() == CommandType::METEOR_TARGET_COMMAND ||
+            cmd->GetCommandType() == CommandType::METEOR_CANCEL_COMMAND) {
+            const int unitId = cmd->GetActorUnitId();
+            const Unit* unit = gameState->units()->Get(unitId);
+            if (unit->attached_hero().profession_info().cast_target().row() > -1) {
+                shouldFilter = true;
+            }
+        }
+
+        if (!shouldFilter) { filteredIndices.push_back(i); }
+    }
+
+    return filteredIndices;
+}
+
 std::vector<size_t> AICommandFilter::FilterCommands(
         const CommandListSPtr& commands,
         PlayerId pid,
@@ -49,15 +75,47 @@ std::vector<size_t> AICommandFilter::FilterCommands(
     // Calculate minimum distance to enemies once for all filters
     const double minDistToEnemies = MinDistanceToEnemyUnits(gameState, pid, enemyLocations);
 
+    bool hasAvailablePlacementCommand = false;
+    for (const auto& cmd : *commands) {
+        if (cmd->GetCommandType() == CommandType::PLACE_UNIT_COMMAND ||
+            cmd->GetCommandType() == CommandType::PLACE_HIDDEN_UNIT_COMMAND) {
+            hasAvailablePlacementCommand = true;
+            break;
+        }
+    }
+
+    bool playerHasReserveUnits = false;
+    for (const Unit* unit : *gameState->units()) {
+        if (unit->player_id() == pid &&
+            unit->status() == net::eagle0::shardok::storage::fb::UnitStatus_RESERVE_UNIT) {
+            playerHasReserveUnits = true;
+            break;
+        }
+    }
+
     for (size_t i = 0; i < commands->size(); ++i) {
         const auto& cmd = (*commands)[i];
 
+        if (cmd->GetCommandType() == CommandType::END_PLAYER_SETUP_COMMAND &&
+            hasAvailablePlacementCommand && playerHasReserveUnits) {
+            continue;
+        }
+
         // Always allow END_TURN commands
         if (cmd->GetCommandType() == CommandType::END_TURN_COMMAND) {
             filteredIndices.push_back(i);
             continue;
         }
 
+        // Setup placement commands should always remain available. The movement/spell heuristics
+        // below are combat-oriented and can otherwise filter every placement for an in-reserve
+        // unit, making MCTS think ending setup is the only good option.
+        if (cmd->GetCommandType() == CommandType::PLACE_UNIT_COMMAND ||
+            cmd->GetCommandType() == CommandType::PLACE_HIDDEN_UNIT_COMMAND) {
+            filteredIndices.push_back(i);
+            continue;
+        }
+
         // Filter obviously bad moves
         bool shouldFilter = false;
 
@@ -138,6 +196,17 @@ bool AICommandFilter::IsWastefulAction(
             break;
         }
 
+        case CommandType::METEOR_TARGET_COMMAND:
+        case CommandType::METEOR_CANCEL_COMMAND: {
+            // Filter out re-target/cancel when the mage already has a target.
+            // Re-targeting exists for human misclick correction; the AI commits
+            // to its first target choice and doesn't need to reconsider.
+            const int unitId = cmd.GetActorUnitId();
+            const Unit* unit = gameState->units()->Get(unitId);
+            if (unit->attached_hero().profession_info().cast_target().row() > -1) { return true; }
+            break;
+        }
+
         case CommandType::START_FIRE_COMMAND: {
             // Fire spell filtering - be very restrictive for attackers
             // Fire only affects adjacent tiles and lasts multiple rounds
@@ -386,6 +455,35 @@ bool AICommandFilter::IsWastefulAction(
             break;
         }
 
+        case CommandType::FEAR_COMMAND: {
+            // Solo attackers gain nothing from Fear: the target is stunned for a round but
+            // there is no teammate to capitalize, and the caster ends its turn no closer to
+            // killing units or capturing castles. Defenders, by contrast, benefit from stalling,
+            // so this restriction only applies to the attacking side.
+            //
+            // Exception: if the victim is standing on a fire tile, stunning locks them in place
+            // while the fire modifier keeps chewing through their unit value — the burn does the
+            // work that a follow-up attacker would normally provide.
+            if (isDefender) { break; }
+            if (CountPlayerUnits(gameState, pid) > 1) { break; }
+
+            const int targetRow = cmd.GetTargetRow();
+            const int targetCol = cmd.GetTargetColumn();
+            if (targetRow < 0 || targetCol < 0) {
+                throw ShardokInternalErrorException(
+                        "FEAR_COMMAND missing required target information");
+            }
+
+            const Coords victimLocation(
+                    static_cast<int8_t>(targetRow),
+                    static_cast<int8_t>(targetCol));
+            const auto* victimTerrain = GetTerrain(gameState->hex_map(), victimLocation);
+            if (!victimTerrain->modifier().fire().present()) {
+                return true;  // Solo attacker fear with no fire-follow-up is a wasted action
+            }
+            break;
+        }
+
         case CommandType::EXTINGUISH_FIRE_COMMAND: {
             // Extinguish fire filtering - don't extinguish fires on enemy-occupied tiles
             const int targetRow = cmd.GetTargetRow();
@@ -602,4 +700,4 @@ bool AICommandFilter::WouldAbandonCriticalCastle(
     return false;
 }
 
-}  // namespace shardok
+}  // namespace shardok

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

@@ -44,6 +44,18 @@ public:
             const APDCache& apdCache,
             const BattalionTypeGetter& battalionTypeLookup);
 
+    /**
+     * Lightweight filter for the root of the search tree.
+     * Only removes commands that are genuinely never useful (e.g. meteor
+     * re-targeting when a target is already set), as opposed to the full
+     * heuristic filter which aggressively prunes for lookahead performance.
+     * The full filter could miss good moves at the root that only look
+     * bad locally but prove worthwhile with deeper search.
+     */
+    static std::vector<size_t> FilterLoopingCommands(
+            const CommandListSPtr& commands,
+            const GameStateW& gameState);
+
 private:
     // Helper to build enemy locations once for efficiency
     static CoordsSet BuildEnemyLocations(const GameStateW& gameState, PlayerId pid);

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

@@ -15,11 +15,11 @@ enum class AIAlgorithmType {
 
 // Enum for scoring calculator selection
 enum class ScoringCalculatorType {
-    STANDARD,       // Default: Unbounded raw scores
-    NORMALIZED,     // Normalized scores in [0, 1] range for ML training
-    MCTS_OPTIMIZED  // Bounded linear scores tuned for MCTS
+    STANDARD,        // Default: Unbounded raw scores
+    MCTS_OPTIMIZED,  // Bounded linear scores tuned for MCTS
+    EXPERIMENTAL     // Standard-derived scorer selected by experiment id
 };
 
 }  // namespace shardok
 
-#endif  // EAGLE0_AI_CONFIG_HPP
+#endif  // EAGLE0_AI_CONFIG_HPP

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

@@ -84,6 +84,7 @@ auto AIDefenderStrategySelector::BestDefenderStrategy(
     //  * the defender has way, way fewer troops
     // other considerations we should have but do not presently:
     //  * the attacker is close to the defender / castles
+
     if (canFlee && roundsRemaining > 2 &&
         defenderTroops < MAXIMUM_RATIO_FOR_DEFENDER_TO_FLEE * attackerTroops &&
         attackerNonUndeadUnitNotRequiringWaterCrossingCount >= criticalTileCoords.size()) {

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

@@ -0,0 +1,23 @@
+//
+// Temporary AI experiment switches used by benchmark-only EXPERIMENTAL runs.
+//
+
+#ifndef EAGLE0_AI_EXPERIMENT_CONFIG_HPP
+#define EAGLE0_AI_EXPERIMENT_CONFIG_HPP
+
+#include <cstdlib>
+#include <string>
+
+namespace shardok {
+
+inline auto CurrentAIExperimentId() -> int {
+    const char* rawValue = std::getenv("SHARDOK_SCORING_EXPERIMENT_ID");
+    if (rawValue == nullptr || std::string(rawValue).empty()) { return 0; }
+    return std::atoi(rawValue);
+}
+
+inline auto IsAIExperiment(const int id) -> bool { return CurrentAIExperimentId() == id; }
+
+}  // namespace shardok
+
+#endif  // EAGLE0_AI_EXPERIMENT_CONFIG_HPP

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

@@ -5,7 +5,6 @@
 #include "AIUnitScoreCalculator.hpp"
 
 #include <algorithm>
-#include <cstdlib>
 
 #include "AIAttackLocations.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexMapUtils.hpp"
@@ -33,7 +32,9 @@ constexpr double kMeteorCastRoundMultiplier = 1.5;
 constexpr double kMeteorCastInsufficientVigorMultiplier = 0.5;
 constexpr double kMeteorCastleMultiplier = 2.0;
 constexpr double kLightningPossibleValue = 0.05;
-constexpr double kArcheryPossibleValue = 38;
+constexpr double kExpectedArcheryVolleyTargetValueFraction = 0.16;
+constexpr double kImmediateArcheryThreatMultiplier = 0.5;
+constexpr double kFutureArcheryThreatMultiplier = 0.25;
 constexpr double kReduceFortifiedPossibleValue = 50;
 constexpr double kReduceUnfortifiedPossibleValue = 12;
 constexpr double kFearPossibleValue = 38;
@@ -101,9 +102,24 @@ auto ContextFreeUnitValue(const Unit *unit) -> ScoreValue {
     return battalionValue + heroValue;
 }
 
-auto archeryValue(const Unit * /*unit*/) -> double {
-    // TODO: make this depend on the value of the targets
-    return kArcheryPossibleValue;
+auto bestEnemyUnitValue(const vector<const Unit *> &enemyUnits) -> double {
+    double bestTargetValue = 0.0;
+    for (const Unit *enemyUnit : enemyUnits) {
+        bestTargetValue = std::max(bestTargetValue, ContextFreeUnitValue(enemyUnit));
+    }
+    return bestTargetValue;
+}
+
+auto expectedImpactArcheryValue(const vector<const Unit *> &enemyUnits, const bool canShootNow)
+        -> double {
+    const double expectedVolleyImpact =
+            kExpectedArcheryVolleyTargetValueFraction * bestEnemyUnitValue(enemyUnits);
+    return expectedVolleyImpact *
+           (canShootNow ? kImmediateArcheryThreatMultiplier : kFutureArcheryThreatMultiplier);
+}
+
+auto archeryValue(const vector<const Unit *> &enemyUnits, const bool canShootNow) -> double {
+    return expectedImpactArcheryValue(enemyUnits, canShootNow);
 }
 
 auto reduceValue(const Unit *unit, const Terrain *unitTerrain) -> double {
@@ -116,10 +132,7 @@ auto reduceValue(const Unit *unit, const Terrain *unitTerrain) -> double {
         return 0.0;
 }
 
-auto fearValue(const Unit * /*unit*/) -> double {
-    // TODO: make this depend on the value of the targets
-    return kFearPossibleValue;
-}
+auto fearValue(const vector<const Unit *> &) -> double { return kFearPossibleValue; }
 
 auto lightningValue(const Unit *unit) -> double {
     // TODO: make this depend on the value of the targets
@@ -265,11 +278,13 @@ auto GetRangedAttackBonus(
         const vector<const Unit *> &attackerUnits,
         const vector<const Unit *> &defenderUnits,
         const int meteorRange,
-        const double minVigorToCast) -> double {
+        const double minVigorToCast,
+        const ActionPoints archeryActionPointCost) -> double {
     vector<double> rangedAttackValues{};
 
     const auto &enemyUnits = isAttacker ? defenderUnits : attackerUnits;
     const auto &friendlyUnits = isAttacker ? attackerUnits : defenderUnits;
+    const bool canShootNow = unit->remaining_action_points() >= archeryActionPointCost;
 
     const auto &unitLocation = unit->location();
 
@@ -306,19 +321,19 @@ auto GetRangedAttackBonus(
         unit->attached_hero().profession_info().profession() ==
                 net::eagle0::shardok::storage::fb::Profession_NECROMANCER &&
         unit->attached_hero().control_info().controlled_unit_id() != -1) {
-        rangedAttackValues.push_back(fearValue(unit));
+        rangedAttackValues.push_back(fearValue(enemyUnits));
     }
 
     if (attackLocations.ArcheryLocations().Contains(unitLocation) &&
         unit->volleys_remaining() > 0) {
-        rangedAttackValues.push_back(archeryValue(unit));
+        rangedAttackValues.push_back(archeryValue(enemyUnits, canShootNow));
     }
 
     // Longbowmen in castle can archer adjacent
     if (attackLocations.AdjacentLocations().Contains(unitLocation) &&
         unit->volleys_remaining() > 0 && terrain->modifier().castle().present() &&
         unit->battalion().type() == net::eagle0::shardok::storage::fb::BattalionTypeId_LONGBOWMEN) {
-        rangedAttackValues.push_back(archeryValue(unit));
+        rangedAttackValues.push_back(archeryValue(enemyUnits, canShootNow));
     }
 
     if (rangedAttackValues.empty()) return 0.0;
@@ -338,7 +353,8 @@ auto UnitValue(
         const CoordsSet &locationsInDangerFromEnemy,
         const ActionPointDistances *distances,
         int meteorRange,
-        double meteorCastVigorCost) -> ScoreValue {
+        double meteorCastVigorCost,
+        ActionPoints archeryActionPointCost) -> ScoreValue {
     const auto &location = unit->location();
     if (location.row() < 0) return 0;  // unplaced unit
 
@@ -382,7 +398,8 @@ auto UnitValue(
             attackerUnits,
             defenderUnits,
             meteorRange,
-            meteorCastVigorCost);
+            meteorCastVigorCost,
+            archeryActionPointCost);
 
     // scouting values
     // attack range

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

@@ -32,7 +32,8 @@ auto GetRangedAttackBonus(
         const vector<const Unit *> &attackerUnits,
         const vector<const Unit *> &defenderUnits,
         int meteorRange,
-        double minVigorToCast) -> double;
+        double minVigorToCast,
+        ActionPoints archeryActionPointCost = 0) -> double;
 
 auto UnitValue(
         const Unit *unit,
@@ -47,7 +48,8 @@ auto UnitValue(
         const CoordsSet &locationsInDangerFromEnemy,
         const ActionPointDistances *distances,
         int meteorRange,
-        double meteorCastVigorCost) -> ScoreValue;
+        double meteorCastVigorCost,
+        ActionPoints archeryActionPointCost = 0) -> ScoreValue;
 
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/ai/AI_SCORING_SYSTEM.md

@@ -156,7 +156,9 @@ The system uses recursive lookahead with:
 - `kProfessionValue`: 200
 
 ### Ranged Attack Values
-- `kArcheryPossibleValue`: 38
+- Archery position value: expected-impact based. A unit that can shoot now gets half of
+  `0.16 * best target unit value`; a unit in archery range that cannot shoot yet gets one
+  quarter of that expected volley value.
 - `kMeteorDirectTargetingEnemy`: 2 per soldier
 - `kMeteorSplashTargetingEnemy`: 1 per soldier
 - `kLightningPossibleValue`: 0.05 per soldier
@@ -762,4 +764,4 @@ MCTSAI ai(playerId, isDefender, strategy, castleCoords, apdCache, alCache, confi
 - Higher `immediateScoreTieBreakThreshold` to emphasize direct paths
 - `BEST_IMMEDIATE` simulation for most predictable behavior
 
-The configuration system allows fine-tuning MCTS behavior for different scenarios while maintaining compatibility with the existing AI infrastructure.
+The configuration system allows fine-tuning MCTS behavior for different scenarios while maintaining compatibility with the existing AI infrastructure.

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

@@ -11,6 +11,13 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "ai_experiment_config",
+    hdrs = ["AIExperimentConfig.hpp"],
+    copts = COPTS,
+    visibility = ["//src/main/cpp/net/eagle0/shardok/ai:__subpackages__"],
+)
+
 cc_library(
     name = "ai_attacker_strategy_selector",
     srcs = ["AIAttackerStrategySelector.cpp"],
@@ -84,6 +91,7 @@ cc_library(
     ],
     deps = [
         ":ai_attack_locations",
+        ":ai_experiment_config",
         ":ai_score_utilities",
         ":ai_strategy",
         ":ai_water_crossing_calculator",
@@ -196,6 +204,7 @@ cc_library(
     ],
     deps = [
         ":ai_command_filter",
+        ":ai_experiment_config",
         ":ai_strategy",
         ":transposition_table",
         "//src/main/cpp/net/eagle0/common:sequence_random_generator",
@@ -272,6 +281,7 @@ cc_library(
     ],
     deps = [
         ":ai_attack_locations",
+        ":ai_experiment_config",
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
     ],
@@ -348,6 +358,7 @@ cc_library(
         ":ai_attacker_strategy_selector",
         ":ai_command_evaluator",
         ":ai_defender_strategy_selector",
+        ":ai_experiment_config",
         ":ai_time_budget",
         ":ai_water_crossing_command_chooser",
         "//src/main/cpp/net/eagle0/common:time_utils",
@@ -385,7 +396,6 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/ai/mcts:shardok_mcts_ai",  # MCTS with abstraction layer
         "//src/main/cpp/net/eagle0/shardok/ai/score:ai_score_calculator_interface",
         "//src/main/cpp/net/eagle0/shardok/ai/score:mcts_optimized_ai_score_calculator",  # Bounded linear scorer for MCTS
-        "//src/main/cpp/net/eagle0/shardok/ai/score:normalized_ai_score_calculator",  # Normalized [0,1] scorer for ML training
         "//src/main/cpp/net/eagle0/shardok/ai/score:standard_ai_score_calculator",  # Standard unbounded scorer (default)
         "//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/cpp/net/eagle0/shardok/ai/IterativeDeepeningAI.cpp

@@ -11,7 +11,9 @@
 
 #include "AIAttackerStrategySelector.hpp"
 #include "AICommandEvaluator.hpp"
+#include "AICommandFilter.hpp"
 #include "TranspositionTable.hpp"
+#include "src/main/cpp/net/eagle0/shardok/ai/AIExperimentConfig.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/AIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
 
@@ -59,6 +61,12 @@ auto IterativeDeepeningAI::IterativeSearch(
         return result;
     }
 
+    // Lightweight root filter: only remove genuinely never-useful commands
+    // (e.g. meteor re-targeting). The full aggressive filter is reserved for
+    // lookahead where pruning is a performance optimization, not a decision.
+    const std::vector<size_t> rootFilteredIndices =
+            AICommandFilter::FilterLoopingCommands(commands, state);
+
     // Check if we're in SET_UP phase and enforce maximum depth limit
     bool isSetupPhase =
             (state->status()->state() ==
@@ -90,7 +98,8 @@ auto IterativeDeepeningAI::IterativeSearch(
         std::vector<size_t> sortedIndices = GetCommandsSortedByPreviousDepth(
                 currentDepth,
                 scoresByDepth,
-                highestDepthCompleted);
+                highestDepthCompleted,
+                rootFilteredIndices);
 
         size_t evaluatedCount = 0;
         bool allEvaluated = true;
@@ -122,6 +131,10 @@ auto IterativeDeepeningAI::IterativeSearch(
         // Now wait for all futures and collect results
         for (auto& [cmdIndex, future] : futures) {
             auto cmdResult = future.get();
+            if (!cmdResult.searchCompleted) {
+                allEvaluated = false;
+                continue;
+            }
 
             // Ensure scoresByDepth[cmdIndex] has enough space
             if (scoresByDepth[cmdIndex].size() <= currentDepth) {
@@ -213,7 +226,7 @@ auto IterativeDeepeningAI::IterativeSearch(
             }
 
             // If all evaluated commands had unchanged scores, we've hit END_TURN in lookahead
-            if (scoresUnchanged && unchangedCount == evaluatedCount) {
+            if (!IsAIExperiment(26) && scoresUnchanged && unchangedCount == evaluatedCount) {
                 completionReason = EvaluationCompletionReason::RAN_OUT_OF_COMMANDS;
                 break;
             }
@@ -243,7 +256,9 @@ auto IterativeDeepeningAI::IterativeSearch(
         completionReason = EvaluationCompletionReason::RAN_OUT_OF_COMMANDS;
     }
 
-    // Select best result from highest depth achieved for each command
+    // Select best result from the highest completed depth achieved for each command. Commands that
+    // timed out at a depth are not recorded for that depth, so partial deeper work can help without
+    // letting timeout fallback scores compete.
     result = SelectBestResult(scoresByDepth, highestDepthCompleted);
     result.minimumDepthCompleted = result.depthAchieved >= timeBudget.minDepthRequired;
     result.searchCompleted = result.minimumDepthCompleted;
@@ -334,7 +349,9 @@ auto IterativeDeepeningAI::SearchCommandAtDepthWithEngine(
     // Deduct adjusted time from remaining budget
     timeBudget.remainingBudget -= adjustedElapsedMs;
 
-    result.bestScore = commandScore;
+    result.bestScore = commandScore.score;
+    result.searchCompleted = commandScore.completed;
+    result.minimumDepthCompleted = commandScore.completed;
 
     std::promise<SearchResult> p;
     p.set_value(result);
@@ -344,15 +361,15 @@ auto IterativeDeepeningAI::SearchCommandAtDepthWithEngine(
 auto IterativeDeepeningAI::GetCommandsSortedByPreviousDepth(
         const size_t currentDepth,
         const std::vector<std::vector<ScoreValue>>& scoresByDepth,
-        const std::vector<size_t>& highestDepthCompleted) -> std::vector<size_t> {
-    std::vector<size_t> indices(scoresByDepth.size());
-    std::iota(indices.begin(), indices.end(), 0);
-
+        const std::vector<size_t>& highestDepthCompleted,
+        const std::vector<size_t>& filteredIndices) -> std::vector<size_t> {
     if (currentDepth == 1) {
-        // For depth 1, return natural order
-        return indices;
+        // For depth 1, preserve the upstream command-factory priority order.
+        return filteredIndices;
     }
 
+    std::vector<size_t> indices = filteredIndices;
+
     // Sort by score at previous depth
     const size_t prevDepth = currentDepth - 1;
     std::ranges::sort(indices, [&](const size_t a, const size_t b) {
@@ -384,10 +401,20 @@ auto IterativeDeepeningAI::SelectBestResult(
     result.bestScore = -std::numeric_limits<ScoreValue>::infinity();
     result.searchCompleted = false;
 
+    size_t selectionDepth = 0;
+    if (IsAIExperiment(24)) {
+        selectionDepth = std::numeric_limits<size_t>::max();
+        for (const size_t depth : highestDepthCompleted) {
+            if (depth > 0) { selectionDepth = std::min(selectionDepth, depth); }
+        }
+        if (selectionDepth == std::numeric_limits<size_t>::max()) { selectionDepth = 0; }
+    }
+
     // Find the command with best score at its highest evaluated depth
     for (size_t i = 0; i < scoresByDepth.size(); ++i) {
         if (highestDepthCompleted[i] > 0) {
-            const size_t depth = highestDepthCompleted[i];
+            const size_t depth = selectionDepth > 0 ? selectionDepth : highestDepthCompleted[i];
+            if (highestDepthCompleted[i] < depth || scoresByDepth[i].size() <= depth) { continue; }
             if (ScoreValue score = scoresByDepth[i][depth]; score > result.bestScore) {
                 result.bestScore = score;
                 result.bestCommandIndex = i;
@@ -399,4 +426,4 @@ auto IterativeDeepeningAI::SelectBestResult(
     return result;
 }
 
-}  // namespace shardok
+}  // namespace shardok

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

@@ -101,7 +101,8 @@ private:
     [[nodiscard]] static std::vector<size_t> GetCommandsSortedByPreviousDepth(
             size_t currentDepth,
             const std::vector<std::vector<ScoreValue>>& scoresByDepth,
-            const std::vector<size_t>& highestDepthCompleted);
+            const std::vector<size_t>& highestDepthCompleted,
+            const std::vector<size_t>& filteredIndices);
 
     [[nodiscard]] static SearchResult SelectBestResult(
             const std::vector<std::vector<ScoreValue>>& scoresByDepth,
@@ -110,4 +111,4 @@ private:
 
 }  // namespace shardok
 
-#endif  // EAGLE0_ITERATIVEDEEPENINGAI_HPP
+#endif  // EAGLE0_ITERATIVEDEEPENINGAI_HPP

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

@@ -32,7 +32,6 @@
 #include "IterativeDeepeningAI.hpp"
 #include "mcts/ShardokMCTSAI.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/MCTSOptimizedAIScoreCalculator.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/score/NormalizedAIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/StandardAIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexMapUtils.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/view_filters/GameStateGuesser.hpp"
@@ -299,12 +298,12 @@ auto ShardokAIClient::StandardChooseCommandIndex(
     // Create scorer for actual scoring during search - type selected at construction
     std::unique_ptr<AIScoreCalculator> scorer;
     switch (scoringCalculatorType) {
-        case ScoringCalculatorType::NORMALIZED:
-            scorer = MakeNormalizedAIScoreCalculator(settingsGetter, apdCache, alCache);
-            break;
         case ScoringCalculatorType::MCTS_OPTIMIZED:
             scorer = MakeMCTSOptimizedAIScoreCalculator(settingsGetter, apdCache, alCache);
             break;
+        case ScoringCalculatorType::EXPERIMENTAL:
+            scorer = MakeExperimentalAIScoreCalculator(settingsGetter, apdCache, alCache);
+            break;
         case ScoringCalculatorType::STANDARD:
         default: scorer = MakeStandardAIScoreCalculator(settingsGetter, apdCache, alCache); break;
     }

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

@@ -21,6 +21,22 @@
 
 namespace shardok::mcts {
 
+namespace {
+
+auto IsDefenderPlayer(const GameStateW& gameState, const PlayerId playerId) -> bool {
+    for (const auto* pi : *gameState->player_infos()) {
+        if (pi->player_id() == playerId) { return pi->is_defender(); }
+    }
+    return false;
+}
+
+auto LegalActionsCacheKey(const uint64_t stateHash, const bool rootIsDefender) -> uint64_t {
+    constexpr uint64_t kDefenderRoleHash = 0x9e3779b97f4a7c15ULL;
+    return rootIsDefender ? stateHash ^ kDefenderRoleHash : stateHash;
+}
+
+}  // namespace
+
 // 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<
@@ -223,13 +239,14 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
     // Time hash computation
     const auto hashStart = std::chrono::high_resolution_clock::now();
     const uint64_t stateHash = shardokState->hash();
+    const uint64_t cacheKey = LegalActionsCacheKey(stateHash, isDefender_);
     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);
 
     // Check transposition table for cached legal actions
-    if (auto it = legalActionsCache_.find(stateHash); it != legalActionsCache_.end()) {
+    if (auto it = legalActionsCache_.find(cacheKey); it != legalActionsCache_.end()) {
         cacheHits_.fetch_add(1, std::memory_order_relaxed);
 
         // Use cached engine
@@ -304,7 +321,7 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
     const std::vector<size_t> filteredIndices = AICommandFilter::FilterCommands(
             commands,
             currentPlayer,
-            isDefender_,
+            IsDefenderPlayer(shardokState->getShardokState(), currentPlayer),
             shardokState->getShardokState(),
             *apdCache_,
             [this](BattalionTypeId typeId) {
@@ -362,7 +379,7 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
     // 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,
+            cacheKey,
             [&](typename decltype(legalActionsCache_)::value_type& v) {
                 // Update existing entry
                 v.second.filteredIndices = filteredIndices;
@@ -370,7 +387,7 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
             },
             [&](const typename decltype(legalActionsCache_)::constructor& ctor) {
                 // Create new entry
-                ctor(stateHash, LegalActionsCache{filteredIndices, engine});
+                ctor(cacheKey, LegalActionsCache{filteredIndices, engine});
             });
 
     return actions;
@@ -416,14 +433,8 @@ std::vector<double> ShardokGameEngine::getActionWeights(
 
     // 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;
-        }
-    }
+    const bool currentPlayerIsDefender = IsDefenderPlayer(gameState, currentPlayer);
 
     // Use AIHeuristicWeighting for fast O(1) context-aware command weighting
     std::vector<double> weights;

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

@@ -110,8 +110,19 @@ bool ShardokGameState::equals(const MCTSGameState& other) const {
 }
 
 MCTSPlayerId ShardokGameState::getWinner() const {
-    // Note: FlatBuffer doesn't have a winner field
-    // In practice, this would need to determine winner from victory conditions
+    if (!state_->status() ||
+        state_->status()->state() !=
+                net::eagle0::shardok::storage::fb::GameStatus_::State_VICTORY) {
+        return -1;
+    }
+
+    const auto* winningIds = state_->status()->winning_shardok_ids();
+    if (!winningIds || winningIds->empty()) { return -1; }
+
+    for (const PlayerId winningPid : *winningIds) {
+        if (winningPid >= 0) { return winningPid; }
+    }
+
     return -1;  // No winner
 }
 

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

@@ -41,31 +41,6 @@ cc_library(
     ],
 )
 
-cc_library(
-    name = "normalized_ai_score_calculator",
-    srcs = ["NormalizedAIScoreCalculator.cpp"],
-    hdrs = ["NormalizedAIScoreCalculator.hpp"],
-    copts = COPTS,
-    visibility = [
-        "//src/main/cpp/net/eagle0/shardok/ai:__subpackages__",
-        "//src/main/cpp/net/eagle0/shardok/ai_performance_runner:__pkg__",
-        "//src/test/cpp/net/eagle0/shardok/ai:__subpackages__",
-    ],
-    deps = [
-        ":ai_score_calculator_interface",
-        ":ai_victory_condition_score_calculator",
-        "//src/main/cpp/net/eagle0/shardok/ai:ai_strategy",
-        "//src/main/cpp/net/eagle0/shardok/ai:ai_unit_score_calculator",
-        "//src/main/cpp/net/eagle0/shardok/ai:ai_water_crossing_calculator",
-        "//src/main/cpp/net/eagle0/shardok/ai/score/private:abstract_ai_score_calculator",
-        "//src/main/cpp/net/eagle0/shardok/ai/score/private:ai_score_calculator_shared_utilities",
-        "//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/map:coords_set",
-        "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
-    ],
-)
-
 cc_library(
     name = "standard_ai_score_calculator",
     srcs = ["StandardAIScoreCalculator.cpp"],
@@ -79,6 +54,7 @@ cc_library(
     deps = [
         ":ai_score_calculator_interface",
         ":ai_victory_condition_score_calculator",
+        "//src/main/cpp/net/eagle0/shardok/ai:ai_experiment_config",
         "//src/main/cpp/net/eagle0/shardok/ai:ai_strategy",
         "//src/main/cpp/net/eagle0/shardok/ai:ai_unit_score_calculator",
         "//src/main/cpp/net/eagle0/shardok/ai:ai_water_crossing_calculator",

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

@@ -59,6 +59,7 @@ public:
     MCTSOptimizedAIScoreCalculator(
             int maxRounds,
             ActionPoints braveWaterCost,
+            ActionPoints archeryActionPointCost,
             int meteorRange,
             double meteorCastVigorCost,
             int minimumFleeOddsThreshold,
@@ -69,6 +70,7 @@ public:
         : AbstractAIScoreCalculator(
                   maxRounds,
                   braveWaterCost,
+                  archeryActionPointCost,
                   meteorRange,
                   meteorCastVigorCost,
                   minimumFleeOddsThreshold,
@@ -236,6 +238,7 @@ auto MakeMCTSOptimizedAIScoreCalculator(
     return std::make_unique<MCTSOptimizedAIScoreCalculator>(
             settingsGetter.Backing().max_rounds(),
             settingsGetter.Backing().brave_water_action_point_cost(),
+            settingsGetter.Backing().archery_action_point_cost(),
             settingsGetter.Backing().meteor_range(),
             settingsGetter.Backing().meteor_cast_vigor_cost(),
             settingsGetter.Backing().ai_minimum_flee_odds_threshold(),

src/main/cpp/net/eagle0/shardok/ai/score/MCTS_SCORING_DESIGN.md

@@ -5,7 +5,7 @@
 We need a scoring algorithm that makes MCTS perform well by providing score differences in the right range:
 
 - **Standard Scorer**: Returns unbounded relative scores. Small differences get amplified in MCTS UCB formula, causing over-exploitation (commits to 1-2 high-scoring nodes too early).
-- **Normalized Scorer**: Returns scores in [0,1] range with power transformation (exponent=0.1). Differences are too compressed (~0.02-0.05), causing over-exploration (all nodes explored equally, AI makes bad choices).
+- **Retired bounded-ratio scorer**: Returned scores in [0,1] range with power transformation (exponent=0.1). Differences were too compressed (~0.02-0.05), causing over-exploration (all nodes explored equally, AI made bad choices).
 
 ### MCTS Requirements
 
@@ -32,9 +32,9 @@ This means individual scores should differ by **0.5 to 2.0** between meaningfull
 - Range: 0 (all captured) to -3000 (all held, far away)
 
 ### Terminal States
-- Victory: INT_MAX (or 1.0 for normalized)
-- Defeat: INT_MIN (or 0.0 for normalized)
-- Flee/Draw: 0 (or 0.5 for normalized)
+- Victory: INT_MAX
+- Defeat: INT_MIN
+- Flee/Draw: 0
 - Captured unit: -10,000
 - Captured VIP: -25,000
 
@@ -257,7 +257,7 @@ This progression is ideal:
 
 This avoids both pathologies:
 - Not over-exploiting (like Standard scorer which overcommitted to tiny early differences)
-- Not over-exploring (like Normalized scorer which explored equally even with large advantages)
+- Not over-exploring like the retired bounded-ratio scorer, which explored equally even with large advantages
 
 ## Why MCTS Needs Stronger Signal Than Minimax
 
@@ -281,11 +281,11 @@ This gives MCTS the right balance: explore when moves are similar, exploit when
 
 ## Implementation Notes
 
-1. **Use same calculation structure**: Inherit from AbstractAIScoreCalculator like Standard and Normalized
+1. **Use same calculation structure**: Inherit from AbstractAIScoreCalculator like Standard
 2. **Reuse unit scoring**: Use existing CalculateUnitsScoreComponents and victory condition calculators
 3. **Only change combination**: Override CombineAttackerScores, CombineDefenderScores, etc.
 4. **Bounded terminals**: Use ±1000 instead of INT_MAX/MIN for numerical stability
-5. **No transformation**: Unlike Normalized, don't apply power transformation - linear scaling is sufficient
+5. **No transformation**: Do not apply power transformation - linear scaling is sufficient
 6. **Scale constants tuned for MCTS**: 10x larger than naive normalization to provide appropriate signal strength
 
 ## Testing with Integration Tests
@@ -383,6 +383,5 @@ Once the scorer passes integration tests with IterativeDeepeningAI, then integra
 
 - `BoundedLinearAIScoreCalculator`
 - `MCTSOptimizedAIScoreCalculator`
-- `LinearNormalizedAIScoreCalculator`
 
 Recommend: **`MCTSOptimizedAIScoreCalculator`** to clearly indicate purpose.

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

@@ -1,252 +0,0 @@
-//
-// Normalized [0,1] implementation of AIScoreCalculator
-//
-
-#include "NormalizedAIScoreCalculator.hpp"
-
-#include <cmath>
-#include <unordered_map>
-
-#include "private/AIScoreCalculatorSharedUtilities.hpp"
-#include "private/AbstractAIScoreCalculator.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/AIAttackLocations.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/AIScoreUtilities.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/AIStrategy.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/AIUnitScoreCalculator.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/action_point_distances/ActionPointDistancesCache.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
-
-namespace shardok {
-
-using net::eagle0::shardok::storage::fb::BattalionTypeId;
-
-// Bring shared utilities into scope
-using score_calculator_internal::UnitsScoreComponents;
-
-/// Normalized implementation of AIScoreCalculator that produces scores in [0, 1] range.
-/// Inherits from AbstractAIScoreCalculator to share common functionality.
-class NormalizedAIScoreCalculator : public AbstractAIScoreCalculator {
-public:
-    NormalizedAIScoreCalculator(
-            int maxRounds,
-            ActionPoints braveWaterCost,
-            int meteorRange,
-            double meteorCastVigorCost,
-            int minimumFleeOddsThreshold,
-            int desperateFleeThreshold,
-            std::vector<BattalionTypeSPtr> battalionTypes,
-            const APDCache &apdCache,
-            const ALCache &alCache)
-        : AbstractAIScoreCalculator(
-                  maxRounds,
-                  braveWaterCost,
-                  meteorRange,
-                  meteorCastVigorCost,
-                  minimumFleeOddsThreshold,
-                  desperateFleeThreshold,
-                  std::move(battalionTypes),
-                  apdCache,
-                  alCache) {}
-
-    [[nodiscard]] auto GuessedStateScore(
-            bool isDefender,
-            const GameStateW &state,
-            const AIStrategy &aiStrategy,
-            const CoordsSet &allCastleCoords) const -> ScoreValue override;
-
-    // Implement pure virtual methods from AbstractAIScoreCalculator
-    [[nodiscard]] auto InterpretDefenderOutcome(GameOutcome outcome) const -> ScoreValue override;
-    [[nodiscard]] auto InterpretAttackerOutcome(GameOutcome outcome) const -> ScoreValue override;
-
-    [[nodiscard]] auto AttackerFleeStrategyScoreForState(const GameStateW &gameState) const
-            -> ScoreValue override;
-
-    [[nodiscard]] auto CombineAttackerScores(
-            const UnitsScoreComponents &components,
-            double victoryConditionScore,
-            int roundsRemaining) const -> ScoreValue override;
-
-    [[nodiscard]] auto CombineDefenderScatterScores(const UnitsScoreComponents &components) const
-            -> ScoreValue override;
-
-    [[nodiscard]] auto CombineDefenderHoldCastlesScores(
-            const UnitsScoreComponents &components,
-            double victoryConditionScore,
-            int roundsRemaining) const -> ScoreValue override;
-
-private:
-    [[nodiscard]] auto DefenderFleeStrategyScoreForState(const GameStateW &gameState) const
-            -> ScoreValue override;
-
-    /// Applies power transformation to spread out compressed scores for MCTS.
-    /// Maps [0,1] → [0,1] but pushes values away from 0.5 toward the extremes.
-    /// Terminal states (0.0, 1.0) are unchanged.
-    [[nodiscard]] auto TransformForMCTS(ScoreValue score) const -> ScoreValue;
-};
-
-// Implementation of NormalizedAIScoreCalculator methods
-
-auto NormalizedAIScoreCalculator::InterpretDefenderOutcome(GameOutcome outcome) const
-        -> ScoreValue {
-    switch (outcome) {
-        case GameOutcome::DEFENDER_VICTORY: return 1.0;
-        case GameOutcome::ATTACKER_VICTORY: return 0.0;
-        case GameOutcome::DRAW: return 0.5;
-        case GameOutcome::FLEE_OUTCOME: return 0.5;
-    }
-    throw ShardokInternalErrorException("Unknown GameOutcome");
-}
-
-auto NormalizedAIScoreCalculator::InterpretAttackerOutcome(GameOutcome outcome) const
-        -> ScoreValue {
-    switch (outcome) {
-        case GameOutcome::ATTACKER_VICTORY: return 1.0;
-        case GameOutcome::DEFENDER_VICTORY: return 0.0;
-        case GameOutcome::DRAW: return 0.5;
-        case GameOutcome::FLEE_OUTCOME: return 0.5;
-    }
-    throw ShardokInternalErrorException("Unknown GameOutcome");
-}
-
-auto NormalizedAIScoreCalculator::CombineDefenderScatterScores(
-        const UnitsScoreComponents &components) const -> ScoreValue {
-    // For defender, we flip the perspective: defenderValue is (1), attackerValue is (2)
-    const double defenderValue = components.defenderUnitsValue;
-    const double attackerValue = components.attackerUnitsValue;
-
-    // No victory condition for scatter strategy
-    const double denominator = defenderValue + attackerValue;
-    if (denominator == 0.0) { return 0.5; }
-
-    return defenderValue / denominator;
-}
-
-auto NormalizedAIScoreCalculator::CombineDefenderHoldCastlesScores(
-        const UnitsScoreComponents &components,
-        const double victoryConditionScore,
-        const int /*roundsRemaining*/) const -> ScoreValue {
-    // For defender, flip perspective
-    const double defenderValue = components.defenderUnitsValue;
-    const double attackerValue = components.attackerUnitsValue;
-
-    // Apply normalization
-    double numerator;
-    double denominator;
-
-    if (victoryConditionScore >= 0) {
-        numerator = defenderValue + victoryConditionScore;
-        denominator = defenderValue + attackerValue + victoryConditionScore;
-    } else {
-        numerator = defenderValue;
-        denominator = defenderValue + attackerValue - victoryConditionScore;
-    }
-
-    if (denominator == 0.0) { return 0.5; }
-
-    return numerator / denominator;
-}
-
-auto NormalizedAIScoreCalculator::DefenderFleeStrategyScoreForState(
-        const GameStateW & /*gameState*/) const -> ScoreValue {
-    // FLEE strategy doesn't fit the [0,1] model well - return 0.5
-    return 0.5;
-}
-
-auto NormalizedAIScoreCalculator::AttackerFleeStrategyScoreForState(
-        const GameStateW & /*gameState*/) const -> ScoreValue {
-    // FLEE strategy doesn't fit the [0,1] model well - return 0.5
-    return 0.5;
-}
-
-auto NormalizedAIScoreCalculator::CombineAttackerScores(
-        const UnitsScoreComponents &components,
-        const double victoryConditionScore,
-        const int /*roundsRemaining*/) const -> ScoreValue {
-    const double attackerUnitsValue = components.attackerUnitsValue;
-    const double defenderUnitsValue = components.defenderUnitsValue;
-
-    // Apply normalization formula
-    double numerator;
-    double denominator;
-
-    if (victoryConditionScore >= 0) {
-        // Positive victory condition: add to numerator
-        numerator = attackerUnitsValue + victoryConditionScore;
-        denominator = attackerUnitsValue + defenderUnitsValue + victoryConditionScore;
-    } else {
-        // Negative victory condition: subtract from denominator (making it larger)
-        numerator = attackerUnitsValue;
-        denominator = attackerUnitsValue + defenderUnitsValue - victoryConditionScore;
-    }
-
-    // Handle edge case of all zeros
-    if (denominator == 0.0) { return 0.5; }
-
-    return numerator / denominator;
-}
-
-auto NormalizedAIScoreCalculator::TransformForMCTS(ScoreValue score) const -> ScoreValue {
-    // Power transformation exponent - lower values spread scores more toward extremes
-    // Tuned for MCTS: balances exploration vs exploitation
-    // - Too low (e.g., 0.3): over-exploitation like standard scorer
-    // - Too high (e.g., 0.9): over-exploration like untransformed normalized
-    // - 0.6-0.7: sweet spot for MCTS
-    constexpr double EXPONENT = 0.1;
-
-    if (score > 0.5) {
-        // Map [0.5, 1.0] → [0.5, 1.0] with power curve
-        // (score - 0.5) * 2.0 maps to [0, 1], apply power, then scale back
-        return 0.5 + 0.5 * std::pow((score - 0.5) * 2.0, EXPONENT);
-    } else {
-        // Map [0.0, 0.5] → [0.0, 0.5] with power curve (symmetric)
-        return 0.5 - 0.5 * std::pow((0.5 - score) * 2.0, EXPONENT);
-    }
-}
-
-auto NormalizedAIScoreCalculator::GuessedStateScore(
-        const bool isDefender,
-        const GameStateW &state,
-        const AIStrategy &aiStrategy,
-        const CoordsSet &allCastleCoords) const -> ScoreValue {
-    const int roundsRemaining = GetMaxRounds() - state->current_round();
-
-    ScoreValue rawScore;
-    if (isDefender) {
-        rawScore = DefenderScoreForState(state, aiStrategy, allCastleCoords, roundsRemaining);
-    } else {
-        rawScore = AttackerScoreForState(state, aiStrategy, allCastleCoords, roundsRemaining);
-    }
-
-    // Apply power transformation to spread out scores for MCTS
-    return TransformForMCTS(rawScore);
-}
-
-// Factory function implementation
-auto MakeNormalizedAIScoreCalculator(
-        const SettingsGetter &settingsGetter,
-        const APDCache &apdCache,
-        const ALCache &alCache) -> std::unique_ptr<AIScoreCalculator> {
-    // Extract all battalion types into a vector indexed by BattalionTypeId
-    std::vector<BattalionTypeSPtr> battalionTypes(BattalionTypeId::BattalionTypeId_MAX + 1);
-    for (int typeId = BattalionTypeId::BattalionTypeId_MIN;
-         typeId <= BattalionTypeId::BattalionTypeId_MAX;
-         typeId++) {
-        auto battalionTypeId = static_cast<BattalionTypeId>(typeId);
-        battalionTypes[battalionTypeId] = settingsGetter.GetBattalionType(battalionTypeId);
-    }
-
-    return std::make_unique<NormalizedAIScoreCalculator>(
-            settingsGetter.Backing().max_rounds(),
-            settingsGetter.Backing().brave_water_action_point_cost(),
-            settingsGetter.Backing().meteor_range(),
-            settingsGetter.Backing().meteor_cast_vigor_cost(),
-            settingsGetter.Backing().ai_minimum_flee_odds_threshold(),
-            settingsGetter.Backing().ai_desperate_flee_threshold(),
-            std::move(battalionTypes),
-            apdCache,
-            alCache);
-}
-
-}  // namespace shardok

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

@@ -1,44 +0,0 @@
-//
-// Normalized [0,1] implementation of AIScoreCalculator
-//
-
-#ifndef EAGLE0_NORMALIZEDAISCORECALCULATOR_HPP
-#define EAGLE0_NORMALIZEDAISCORECALCULATOR_HPP
-
-#include <memory>
-
-#include "src/main/cpp/net/eagle0/shardok/ai/AIAttackLocations.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
-
-namespace shardok {
-
-// Forward declarations
-class AIScoreCalculator;
-
-using APDCache = std::shared_ptr<ActionPointDistancesCache>;
-using ALCache = std::unique_ptr<AttackLocationsCache>;
-
-/// Factory function to create a NormalizedAIScoreCalculator.
-/// Returns a unique_ptr to AIScoreCalculator to hide the implementation.
-///
-/// The normalized scorer produces scores in the range [0, 1] where:
-/// - 0.0 = complete defender victory
-/// - 1.0 = complete attacker victory
-/// - 0.5 = neutral/draw state
-///
-/// Terminal states (victory/defeat) always return 1.0 or 0.0.
-/// Non-terminal states use asymmetric normalization:
-/// - If victory condition >= 0:
-///   score = (attackerUnits + victoryCondition) / (attackerUnits + defenderUnits +
-///   victoryCondition)
-/// - If victory condition < 0:
-///   score = attackerUnits / (attackerUnits + defenderUnits - victoryCondition)
-[[nodiscard]] auto MakeNormalizedAIScoreCalculator(
-        const SettingsGetter& settingsGetter,
-        const APDCache& apdCache,
-        const ALCache& alCache) -> std::unique_ptr<AIScoreCalculator>;
-
-}  // namespace shardok
-
-#endif  // EAGLE0_NORMALIZEDAISCORECALCULATOR_HPP

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

@@ -4,14 +4,17 @@
 
 #include "StandardAIScoreCalculator.hpp"
 
+#include <algorithm>
 #include <atomic>
 #include <chrono>
+#include <cmath>
 #include <unordered_map>
 
 #include "private/AIScoreCalculatorSharedUtilities.hpp"
 #include "private/AbstractAIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIAttackGroups.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIAttackLocations.hpp"
+#include "src/main/cpp/net/eagle0/shardok/ai/AIExperimentConfig.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIScoreUtilities.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIStrategy.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIUnitScoreCalculator.hpp"
@@ -67,6 +70,68 @@ struct AttackerScorePerformanceLogger {
     }
 };
 
+struct StandardScoringExperiment {
+    double attackerUnitsScale = 1.0;
+    double defenderUnitsScale = 1.0;
+    double victoryConditionScale = 1.0;
+    double unitsBaseMultiplierScale = 1.0;
+    double attackerRoundMultiplier = 1.0;
+    double defenderRoundAdvantageScale = 1.0;
+};
+
+auto ExperimentalScoringId() -> int { return CurrentAIExperimentId(); }
+
+auto ScoringExperimentForId(const int id) -> StandardScoringExperiment {
+    StandardScoringExperiment experiment;
+
+    switch (id) {
+        case 1: experiment.attackerUnitsScale = 1.05; break;
+        case 2: experiment.attackerUnitsScale = 1.10; break;
+        case 3: experiment.attackerUnitsScale = 0.95; break;
+        case 4: experiment.attackerUnitsScale = 0.90; break;
+        case 5: experiment.defenderUnitsScale = 0.95; break;
+        case 6: experiment.defenderUnitsScale = 0.90; break;
+        case 7: experiment.defenderUnitsScale = 1.05; break;
+        case 8: experiment.defenderUnitsScale = 1.10; break;
+        case 9: experiment.victoryConditionScale = 1.10; break;
+        case 10: experiment.victoryConditionScale = 1.25; break;
+        case 11: experiment.victoryConditionScale = 0.90; break;
+        case 12: experiment.victoryConditionScale = 0.75; break;
+        case 13: experiment.unitsBaseMultiplierScale = 0.90; break;
+        case 14: experiment.unitsBaseMultiplierScale = 1.10; break;
+        case 15: experiment.attackerRoundMultiplier = 0.90; break;
+        case 16: experiment.attackerRoundMultiplier = 0.75; break;
+        case 17: experiment.defenderRoundAdvantageScale = 0.50; break;
+        case 18: experiment.defenderRoundAdvantageScale = 0.0; break;
+        case 19:
+            experiment.attackerUnitsScale = 1.10;
+            experiment.victoryConditionScale = 1.10;
+            break;
+        case 20:
+            experiment.defenderUnitsScale = 0.90;
+            experiment.victoryConditionScale = 1.10;
+            break;
+        default: break;
+    }
+
+    return experiment;
+}
+
+auto AdjustDefenderUnitsForExperiment(
+        double defenderUnitsValue,
+        const int roundsRemaining,
+        const int maxRounds,
+        const StandardScoringExperiment &experiment) -> double {
+    const double currentRound = static_cast<double>(maxRounds - roundsRemaining);
+    const double standardAdvantage = 1.0 + currentRound / 31.0;
+    if (standardAdvantage <= 0.0) { return defenderUnitsValue * experiment.defenderUnitsScale; }
+
+    const double unadjustedDefenderValue = defenderUnitsValue / standardAdvantage;
+    const double adjustedAdvantage =
+            1.0 + experiment.defenderRoundAdvantageScale * currentRound / 31.0;
+    return unadjustedDefenderValue * adjustedAdvantage * experiment.defenderUnitsScale;
+}
+
 std::atomic<int> AttackerScorePerformanceLogger::callCount{0};
 std::atomic<double> AttackerScorePerformanceLogger::intervalTime{0.0};
 std::atomic<double> AttackerScorePerformanceLogger::totalTime{0.0};
@@ -95,23 +160,27 @@ public:
     StandardAIScoreCalculator(
             int maxRounds,
             ActionPoints braveWaterCost,
+            ActionPoints archeryActionPointCost,
             int meteorRange,
             double meteorCastVigorCost,
             int minimumFleeOddsThreshold,
             int desperateFleeThreshold,
             std::vector<BattalionTypeSPtr> battalionTypes,
             const APDCache &apdCache,
-            const ALCache &alCache)
+            const ALCache &alCache,
+            StandardScoringExperiment experiment = {})
         : AbstractAIScoreCalculator(
                   maxRounds,
                   braveWaterCost,
+                  archeryActionPointCost,
                   meteorRange,
                   meteorCastVigorCost,
                   minimumFleeOddsThreshold,
                   desperateFleeThreshold,
                   std::move(battalionTypes),
                   apdCache,
-                  alCache) {}
+                  alCache),
+          experiment_(experiment) {}
 
     [[nodiscard]] auto GuessedStateScore(
             bool isDefender,
@@ -151,6 +220,8 @@ private:
 
     [[nodiscard]] auto DefenderFleeStrategyScoreForState(const GameStateW &gameState) const
             -> ScoreValue override;
+
+    StandardScoringExperiment experiment_;
 };
 
 // Implementation of StandardAIScoreCalculator methods
@@ -159,7 +230,7 @@ auto StandardAIScoreCalculator::InterpretDefenderOutcome(GameOutcome outcome) co
     switch (outcome) {
         case GameOutcome::DEFENDER_VICTORY: return INT_MAX;
         case GameOutcome::ATTACKER_VICTORY: return INT_MIN;
-        case GameOutcome::DRAW: return 0;
+        case GameOutcome::DRAW: return INT_MAX;
         case GameOutcome::FLEE_OUTCOME: return 0;
     }
     throw ShardokInternalErrorException("Unknown GameOutcome");
@@ -169,7 +240,7 @@ auto StandardAIScoreCalculator::InterpretAttackerOutcome(GameOutcome outcome) co
     switch (outcome) {
         case GameOutcome::ATTACKER_VICTORY: return INT_MAX;
         case GameOutcome::DEFENDER_VICTORY: return INT_MIN;
-        case GameOutcome::DRAW: return 0;
+        case GameOutcome::DRAW: return INT_MIN;
         case GameOutcome::FLEE_OUTCOME: return 0;
     }
     throw ShardokInternalErrorException("Unknown GameOutcome");
@@ -241,10 +312,20 @@ auto StandardAIScoreCalculator::CombineAttackerScores(
         const UnitsScoreComponents &components,
         const double victoryConditionScore,
         const int roundsRemaining) const -> ScoreValue {
-    const double unitsDifference = components.attackerUnitsValue - components.defenderUnitsValue;
-    const double unitsMultiplier =
-            static_cast<double>(roundsRemaining) / static_cast<double>(GetMaxRounds());
-    return UNITS_BASE_MULTIPLIER * unitsMultiplier * unitsDifference + victoryConditionScore;
+    const double attackerUnitsValue =
+            components.attackerUnitsValue * experiment_.attackerUnitsScale;
+    const double defenderUnitsValue = AdjustDefenderUnitsForExperiment(
+            components.defenderUnitsValue,
+            roundsRemaining,
+            GetMaxRounds(),
+            experiment_);
+    const double unitsDifference = attackerUnitsValue - defenderUnitsValue;
+    // Keep tactical unit value relevant late in the battle. The previous time decay could make
+    // attackers undervalue decisive combat near the round limit.
+    const double unitsMultiplier = experiment_.attackerRoundMultiplier;
+    return UNITS_BASE_MULTIPLIER * experiment_.unitsBaseMultiplierScale * unitsMultiplier *
+                   unitsDifference +
+           victoryConditionScore * experiment_.victoryConditionScale;
 }
 
 auto StandardAIScoreCalculator::GuessedStateScore(
@@ -261,10 +342,11 @@ auto StandardAIScoreCalculator::GuessedStateScore(
 }
 
 // Factory function implementation
-auto MakeStandardAIScoreCalculator(
+auto MakeStandardAIScoreCalculatorWithExperiment(
         const SettingsGetter &settingsGetter,
         const APDCache &apdCache,
-        const ALCache &alCache) -> std::unique_ptr<AIScoreCalculator> {
+        const ALCache &alCache,
+        const StandardScoringExperiment &experiment) -> std::unique_ptr<AIScoreCalculator> {
     // Extract all battalion types into a vector indexed by BattalionTypeId
     std::vector<BattalionTypeSPtr> battalionTypes(BattalionTypeId::BattalionTypeId_MAX + 1);
     for (int typeId = BattalionTypeId::BattalionTypeId_MIN;
@@ -277,13 +359,37 @@ auto MakeStandardAIScoreCalculator(
     return std::make_unique<StandardAIScoreCalculator>(
             settingsGetter.Backing().max_rounds(),
             settingsGetter.Backing().brave_water_action_point_cost(),
+            settingsGetter.Backing().archery_action_point_cost(),
             settingsGetter.Backing().meteor_range(),
             settingsGetter.Backing().meteor_cast_vigor_cost(),
             settingsGetter.Backing().ai_minimum_flee_odds_threshold(),
             settingsGetter.Backing().ai_desperate_flee_threshold(),
             std::move(battalionTypes),
             apdCache,
-            alCache);
+            alCache,
+            experiment);
+}
+
+auto MakeStandardAIScoreCalculator(
+        const SettingsGetter &settingsGetter,
+        const APDCache &apdCache,
+        const ALCache &alCache) -> std::unique_ptr<AIScoreCalculator> {
+    return MakeStandardAIScoreCalculatorWithExperiment(
+            settingsGetter,
+            apdCache,
+            alCache,
+            StandardScoringExperiment{});
+}
+
+auto MakeExperimentalAIScoreCalculator(
+        const SettingsGetter &settingsGetter,
+        const APDCache &apdCache,
+        const ALCache &alCache) -> std::unique_ptr<AIScoreCalculator> {
+    return MakeStandardAIScoreCalculatorWithExperiment(
+            settingsGetter,
+            apdCache,
+            alCache,
+            ScoringExperimentForId(ExperimentalScoringId()));
 }
 
 }  // namespace shardok

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

@@ -26,6 +26,12 @@ using ALCache = std::unique_ptr<AttackLocationsCache>;
         const APDCache& apdCache,
         const ALCache& alCache) -> std::unique_ptr<AIScoreCalculator>;
 
+/// Factory function to create the environment-selected experimental scorer.
+[[nodiscard]] auto MakeExperimentalAIScoreCalculator(
+        const SettingsGetter& settingsGetter,
+        const APDCache& apdCache,
+        const ALCache& alCache) -> std::unique_ptr<AIScoreCalculator>;
+
 }  // namespace shardok
 
 #endif  // EAGLE0_STANDARDAISCORECALCULATOR_HPP

src/main/cpp/net/eagle0/shardok/ai/score/private/AIScoreCalculatorSharedUtilities.hpp

@@ -40,7 +40,7 @@ constexpr double kMaxProximityBuf = 1.5;
 constexpr double kDistanceDebufRatio = 8.0;
 
 /// Structure to hold separated attacker/defender unit scores
-/// Used by NormalizedAIScoreCalculator to apply asymmetric normalization
+/// Used by scorers that combine attacker and defender unit values separately.
 struct UnitsScoreComponents {
     double attackerUnitsValue;
     double defenderUnitsValue;

src/main/cpp/net/eagle0/shardok/ai/score/private/AbstractAIScoreCalculator.cpp

@@ -157,7 +157,8 @@ auto AbstractAIScoreCalculator::CalculateUnitsScoreComponents(
                 locationsCausingDanger,
                 notBravingApd,
                 GetMeteorRange(),
-                GetMeteorCastVigorCost());
+                GetMeteorCastVigorCost(),
+                GetArcheryActionPointCost());
 
         attackerUnitsValue += distanceMultiplier * uv;
     }
@@ -188,7 +189,8 @@ auto AbstractAIScoreCalculator::CalculateUnitsScoreComponents(
                 locationsCausingDangerForAttacker,
                 defenderNotBravingApd,
                 GetMeteorRange(),
-                GetMeteorCastVigorCost());
+                GetMeteorCastVigorCost(),
+                GetArcheryActionPointCost());
 
         double distanceMultiplier = 1.0;
 
@@ -251,7 +253,7 @@ auto AbstractAIScoreCalculator::CalculateUnitsScoreComponents(
                                                       braveWaterCost)
                                             : nullptr,
                                     cachedHexMap);
-                            if (thisDistance < closestDistanceToEnemy) {
+                            if (thisDistance < closestDistanceToFriendly) {
                                 closestDistanceToFriendly = thisDistance;
                             }
                         }
@@ -506,9 +508,7 @@ auto AbstractAIScoreCalculator::AttackerScoreForState(
     const ScoreValue victoryConditionTotal =
             CalculateAttackerVictoryConditionScore(gameState, attackerStrategy, castleCoords);
 
-    // Combine scores using subclass-specific logic
-    // Standard: uses difference and multiplier
-    // Normalized: uses normalization formula
+    // Combine scores using subclass-specific logic.
     return CombineAttackerScores(components, victoryConditionTotal, roundsRemaining);
 }
 

src/main/cpp/net/eagle0/shardok/ai/score/private/AbstractAIScoreCalculator.hpp

@@ -44,6 +44,7 @@ protected:
     AbstractAIScoreCalculator(
             int maxRounds,
             ActionPoints braveWaterCost,
+            ActionPoints archeryActionPointCost,
             int meteorRange,
             double meteorCastVigorCost,
             int minimumFleeOddsThreshold,
@@ -53,6 +54,7 @@ protected:
             const ALCache &alCache)
         : maxRounds_(maxRounds),
           braveWaterCost_(braveWaterCost),
+          archeryActionPointCost_(archeryActionPointCost),
           meteorRange_(meteorRange),
           meteorCastVigorCost_(meteorCastVigorCost),
           minimumFleeOddsThreshold_(minimumFleeOddsThreshold),
@@ -70,6 +72,9 @@ protected:
     [[nodiscard]] auto GetApdCache() const -> const APDCache & { return apdCache_; }
     [[nodiscard]] auto GetAlCache() const -> const ALCache & { return alCache_; }
     [[nodiscard]] auto GetBraveWaterCost() const -> ActionPoints { return braveWaterCost_; }
+    [[nodiscard]] auto GetArcheryActionPointCost() const -> ActionPoints {
+        return archeryActionPointCost_;
+    }
     [[nodiscard]] auto GetMaxRounds() const -> int { return maxRounds_; }
     [[nodiscard]] auto GetMeteorRange() const -> int { return meteorRange_; }
     [[nodiscard]] auto GetMeteorCastVigorCost() const -> double { return meteorCastVigorCost_; }
@@ -146,9 +151,8 @@ protected:
             -> ScoreValue = 0;
 
     // Pure virtual method for combining units score and victory condition score
-    // This is where Standard and Normalized diverge in their scoring approach
-    // Standard: uses difference and applies multiplier
-    // Normalized: uses normalization formula with separate attacker/defender values
+    // This is where concrete scorers combine unit value and victory condition pressure.
+    // Standard uses the raw unit-value difference; MCTS-optimized uses bounded scaling.
     [[nodiscard]] virtual auto CombineAttackerScores(
             const UnitsScoreComponents &components,
             double victoryConditionScore,
@@ -158,6 +162,7 @@ private:
     // Scalar settings extracted from SettingsGetter
     int maxRounds_;
     ActionPoints braveWaterCost_;
+    ActionPoints archeryActionPointCost_;
     int meteorRange_;
     double meteorCastVigorCost_;
     int minimumFleeOddsThreshold_;

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

@@ -54,30 +54,38 @@ std::unique_ptr<BattleConfigProto> AiBattleConfigLoader::CreateDefaultPerfConfig
     // Basic setup matching Unity's "Perf" configuration
     config->set_map_name("Alah");
     config->set_month(month);
-    config->set_max_rounds(40);
-    config->set_random_seed(0);  // Use system random
+    config->set_max_rounds(31);
+    config->set_random_seed(1);
+    config->set_use_configured_placements(false);
+    config->set_apply_forced_commands(true);
 
     // Attacker configuration - 6 Longbowmen units with professions 1-6
     PlayerConfig* attacker = config->mutable_attacker();
     attacker->set_ai_algorithm(AIAlgorithmType::ITERATIVE_DEEPENING);
+    attacker->set_scoring_calculator(
+            net::eagle0::shardok::ai_battle_simulator::ScoringCalculatorType::STANDARD);
 
     for (int profession = 1; profession <= 6; ++profession) {
         UnitConfig* unit = attacker->add_units();
         unit->set_profession(profession);
-        unit->set_battalion_type_id(4);             // Longbowmen (battalion type 4)
-        unit->set_starting_position_index(0);       // Attackers use position 0
+        unit->set_battalion_type_id(4);        // Longbowmen (battalion type 4)
+        unit->set_starting_position_index(0);  // Attackers use position 0
+        unit->set_can_flee(true);
         unit->mutable_battalion()->set_size(1000);  // Match client battalion size
     }
 
     // Defender configuration - 6 Light Infantry units with NO_PROFESSION (profession 14)
     PlayerConfig* defender = config->mutable_defender();
     defender->set_ai_algorithm(AIAlgorithmType::ITERATIVE_DEEPENING);
+    defender->set_scoring_calculator(
+            net::eagle0::shardok::ai_battle_simulator::ScoringCalculatorType::STANDARD);
 
     for (int i = 0; i < 6; ++i) {
         UnitConfig* unit = defender->add_units();
-        unit->set_profession(14);                   // NO_PROFESSION to match client battles
-        unit->set_battalion_type_id(0);             // Light Infantry (battalion type 0)
-        unit->set_starting_position_index(-1);      // Defenders use position -1
+        unit->set_profession(14);               // NO_PROFESSION to match client battles
+        unit->set_battalion_type_id(0);         // Light Infantry (battalion type 0)
+        unit->set_starting_position_index(-1);  // Defenders use position -1
+        unit->set_can_flee(true);
         unit->mutable_battalion()->set_size(1000);  // Match client battalion size
     }