Trace general command cooldown state

hwe/compare/turn_state_snapshot.php

@@ -53,6 +53,36 @@ function comparisonOptionalCode(mixed $value): ?string
     return $value;
 }
 
+/** @return list<array{generalId: int, actionName: string}> */
+function comparisonGeneralCooldownSelectors(mixed $value, string $label): array
+{
+    if ($value === null) {
+        return [];
+    }
+    if (!is_array($value)) {
+        throw new \InvalidArgumentException("{$label} must be an array");
+    }
+    $result = [];
+    foreach ($value as $entry) {
+        if (!is_array($entry)) {
+            throw new \InvalidArgumentException("{$label} entries must be objects");
+        }
+        $generalId = $entry['generalId'] ?? null;
+        $actionName = $entry['actionName'] ?? null;
+        if (!is_int($generalId) || $generalId < 1 || !is_string($actionName) || $actionName === '') {
+            throw new \InvalidArgumentException(
+                "{$label} entries require a positive generalId and non-empty actionName",
+            );
+        }
+        $result["{$generalId}:{$actionName}"] = [
+            'generalId' => $generalId,
+            'actionName' => $actionName,
+        ];
+    }
+    ksort($result, SORT_STRING);
+    return array_values($result);
+}
+
 /** @param array<string, mixed> $row */
 function comparisonPickRow(array $row, array $mapping, array $jsonKeys = []): array
 {
@@ -98,6 +128,10 @@ function comparisonTurnStateSnapshot(array $request): array
     $nationIds = comparisonIntegerList($observe['nationIds'] ?? [], 'nationIds');
     $logAfterId = $observe['logAfterId'] ?? 0;
     $messageAfterId = $observe['messageAfterId'] ?? 0;
+    $generalCooldownSelectors = comparisonGeneralCooldownSelectors(
+        $observe['generalCooldowns'] ?? [],
+        'generalCooldowns',
+    );
     if (!is_int($logAfterId) || $logAfterId < 0 || !is_int($messageAfterId) || $messageAfterId < 0) {
         throw new \InvalidArgumentException('logAfterId and messageAfterId must be non-negative integers');
     }
@@ -116,6 +150,19 @@ function comparisonTurnStateSnapshot(array $request): array
         'init_month',
         'develcost',
     ]);
+    $nextExecuteStorage = KVStorage::getStorage($db, 'next_execute');
+    $nextExecuteStorage->resetCache();
+    $generalCooldowns = array_map(
+        static function (array $selector) use ($nextExecuteStorage): array {
+            $key = "next_execute_{$selector['generalId']}_{$selector['actionName']}";
+            $value = $nextExecuteStorage->getValue($key);
+            return [
+                ...$selector,
+                'nextAvailableTurn' => is_int($value) ? $value : null,
+            ];
+        },
+        $generalCooldownSelectors,
+    );
 
     $generals = array_map(
         static function (array $row): array {
@@ -362,6 +409,7 @@ function comparisonTurnStateSnapshot(array $request): array
             'initYear' => (int)$worldValues['init_year'],
             'initMonth' => (int)$worldValues['init_month'],
             'develCost' => (int)$worldValues['develcost'],
+            'generalCooldowns' => $generalCooldowns,
         ],
         'generals' => $generals,
         'cities' => $cities,