From e00ff5f1a50bbc06a2fe2279485898b67fd07c3b Mon Sep 17 00:00:00 2001
From: Dan Crosby <dan@danielcrosby.net>
Date: Tue, 9 Jun 2026 16:47:52 -0700
Subject: [PATCH] Report Eagle cache load rejection reasons

---
 .../eagle0/Assets/Eagle/EagleGameModel.cs     |  4 +-
 .../Assets/Eagle/EagleGameStateDiskCache.cs   | 58 ++++++++++++++++---
 2 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameModel.cs b/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameModel.cs
index dd12a93f3f..db277c3d01 100644
--- a/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameModel.cs
+++ b/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameModel.cs
@@ -278,7 +278,9 @@ namespace eagle {
             var cachedState = EagleGameStateDiskCache.Load(GameId, factionId);
             if (cachedState == null) {
                 _connectionLogger.LogLine(
-                        $"[STATE_CACHE] Cache miss game={GameId} player={factionId?.ToString() ?? "spectator"}");
+                        $"[STATE_CACHE] Cache miss game={GameId} " +
+                        $"player={factionId?.ToString() ?? "spectator"} " +
+                        $"reason={EagleGameStateDiskCache.LastLoadDiagnostic}");
                 return;
             }
 
diff --git a/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameStateDiskCache.cs b/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameStateDiskCache.cs
index a4968def68..ef55c3548b 100644
--- a/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameStateDiskCache.cs
+++ b/src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/EagleGameStateDiskCache.cs
@@ -43,25 +43,66 @@ namespace eagle {
         }
 
         private static string _cacheDirectory;
+        public static string LastLoadDiagnostic { get; private set; }
 
         public static CachedGameState Load(long gameId, int? playerId) {
             EnsureCacheDirectoryInitialized();
 
             var path = CachePath(gameId, playerId);
-            if (!File.Exists(path)) { return null; }
+            LastLoadDiagnostic = $"path={path}";
+            if (!File.Exists(path)) {
+                LastLoadDiagnostic = $"file not found at {path}";
+                return null;
+            }
 
             try {
                 var cache = JsonUtility.FromJson<CacheFile>(File.ReadAllText(path));
-                if (cache == null || cache.schemaVersion != CurrentSchemaVersion) { return null; }
-                if (cache.gameId != gameId) { return null; }
-                if (cache.hasPlayerId != playerId.HasValue) { return null; }
-                if (cache.hasPlayerId && cache.playerId != playerId.Value) { return null; }
-                if (cache.unfilteredResultCount <= 0) { return null; }
-                if (String.IsNullOrEmpty(cache.gameStateViewBase64)) { return null; }
+                if (cache == null) {
+                    LastLoadDiagnostic = $"cache JSON parsed to null at {path}";
+                    return null;
+                }
+                if (cache.schemaVersion != CurrentSchemaVersion) {
+                    LastLoadDiagnostic =
+                            $"schema mismatch at {path}: cache={cache.schemaVersion} current={CurrentSchemaVersion}";
+                    return null;
+                }
+                if (cache.gameId != gameId) {
+                    LastLoadDiagnostic =
+                            $"game id mismatch at {path}: cache={cache.gameId} requested={gameId}";
+                    return null;
+                }
+                if (cache.hasPlayerId != playerId.HasValue) {
+                    LastLoadDiagnostic =
+                            $"player presence mismatch at {path}: cacheHas={cache.hasPlayerId} requestedHas={playerId.HasValue}";
+                    return null;
+                }
+                if (cache.hasPlayerId && cache.playerId != playerId.Value) {
+                    LastLoadDiagnostic =
+                            $"player id mismatch at {path}: cache={cache.playerId} requested={playerId.Value}";
+                    return null;
+                }
+                if (cache.unfilteredResultCount <= 0) {
+                    LastLoadDiagnostic =
+                            $"invalid unfiltered count at {path}: {cache.unfilteredResultCount}";
+                    return null;
+                }
+                if (String.IsNullOrEmpty(cache.gameStateViewBase64)) {
+                    LastLoadDiagnostic = $"missing GameStateView payload at {path}";
+                    return null;
+                }
 
                 var bytes = Convert.FromBase64String(cache.gameStateViewBase64);
                 var gameStateView = GameStateView.Parser.ParseFrom(bytes);
-                if (gameStateView.GameId != gameId) { return null; }
+                if (gameStateView.GameId == 0) {
+                    gameStateView.GameId = gameId;
+                } else if (gameStateView.GameId != gameId) {
+                    LastLoadDiagnostic =
+                            $"GameStateView game id mismatch at {path}: view={gameStateView.GameId} requested={gameId}";
+                    return null;
+                }
+
+                LastLoadDiagnostic =
+                        $"loaded {path} count={cache.unfilteredResultCount} shardokGames={cache.shardokGames?.Count ?? 0}";
 
                 return new CachedGameState {
                     GameStateView = gameStateView,
@@ -69,6 +110,7 @@ namespace eagle {
                     ShardokGames = LoadShardokGames(cache.shardokGames)
                 };
             } catch (Exception e) {
+                LastLoadDiagnostic = $"exception loading {path}: {e}";
                 Debug.LogWarning($"Failed to load Eagle game state cache for game {gameId}: {e}");
                 TryDelete(path);
                 return null;