merge: refresh ng_compare for logical game clock

hwe/compare/monthly_event_trace.php

@@ -16,6 +16,18 @@ require_once 'lib.php';
 require_once 'func.php';
 require_once __DIR__ . '/turn_state_snapshot.php';
 
+function comparisonGameTick(mixed $value, string $label): int
+{
+    if (is_int($value)) {
+        return GameClock::requireSafeTick($value);
+    }
+    if (!is_string($value) || $value === '') {
+        throw new \InvalidArgumentException("{$label} must be a game tick or projected date string");
+    }
+    $gameStorage = KVStorage::getStorage(DB::db(), 'game_env');
+    return GameClock::fromStorage($gameStorage)->dateTimeToTick(new \DateTimeImmutable($value));
+}
+
 /** @param array<string, mixed> $values */
 function comparisonMonthlyPatch(string $table, int $id, array $values): void
 {
@@ -1073,6 +1085,14 @@ function comparisonMonthlyEventTraceMain(): void
         if (!is_array($environment)) {
             throw new \InvalidArgumentException('environment must be an object');
         }
+        foreach (['starttime', 'turntime'] as $timeKey) {
+            if (array_key_exists($timeKey, $environment)) {
+                $environment[$timeKey] = comparisonGameTick(
+                    $environment[$timeKey],
+                    "environment.{$timeKey}",
+                );
+            }
+        }
         $year = $environment['year'] ?? null;
         $month = $environment['month'] ?? null;
         $startYear = $environment['startyear'] ?? null;
@@ -1089,9 +1109,6 @@ function comparisonMonthlyEventTraceMain(): void
                 'turnterm' => $environment['turnterm'] ?? $gameStorage->turnterm,
             ];
             if (isset($environment['starttime'])) {
-                if (!is_string($environment['starttime']) || $environment['starttime'] === '') {
-                    throw new \InvalidArgumentException('environment.starttime must be a non-empty string');
-                }
                 $environmentValues['starttime'] = $environment['starttime'];
             }
             foreach ($environmentValues as $key => $value) {
@@ -1232,12 +1249,12 @@ function comparisonMonthlyEventTraceMain(): void
             if (
                 !is_int($turnterm)
                 || $turnterm <= 0
-                || !is_string($turntime)
+                || !is_int($turntime)
                 || !is_int($showImgLevel)
                 || !is_array($fiction)
             ) {
                 throw new \InvalidArgumentException(
-                    "{$actionName} requires positive turnterm, string turntime, integer show_img_level, and array fiction",
+                    "{$actionName} requires positive turnterm, game-tick turntime, integer show_img_level, and array fiction",
                 );
             }
             $actionEnvironment += [
@@ -1267,7 +1284,7 @@ function comparisonMonthlyEventTraceMain(): void
             ))));
         } elseif ($actionName === 'MonthlyBoundary') {
             $turntime = $environment['turntime'] ?? null;
-            if (!is_string($turntime) || $turntime === '') {
+            if (!is_int($turntime)) {
                 throw new \InvalidArgumentException('MonthlyBoundary requires turntime');
             }
             $gameStorage = KVStorage::getStorage($db, 'game_env');