test(compare): trace deterministic monthly seed progression

src/sammo/RandUtil.php

@@ -4,13 +4,36 @@ namespace sammo;
 
 class RandUtil
 {
+    private ?int $traceGeneralId = null;
+    private int $traceSequence = 0;
+
     public function __construct(public readonly RNG $rng)
     {
     }
 
+    public function setTraceGeneralId(?int $generalId): void
+    {
+        $this->traceGeneralId = $generalId;
+    }
+
+    private function trace(string $method, mixed $result): void
+    {
+        if ($this->traceGeneralId === null) {
+            return;
+        }
+        fwrite(STDOUT, 'AI_RNG_TRACE ' . json_encode([
+            'generalId' => $this->traceGeneralId,
+            'sequence' => $this->traceSequence++,
+            'method' => $method,
+            'result' => $result,
+        ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . "\n");
+    }
+
     public function nextFloat1(): float
     {
-        return $this->rng->nextFloat1();
+        $result = $this->rng->nextFloat1();
+        $this->trace('nextFloat1', $result);
+        return $result;
     }
 
     public function nextRange(int|float $min, int|float $max): float
@@ -25,16 +48,22 @@ class RandUtil
         if ($range > $this->rng->getMaxInt()) {
             throw new \InvalidArgumentException("Invalid random int range");
         }
-        return $this->rng->nextInt($range) + $min;
+        $result = $this->rng->nextInt($range) + $min;
+        $this->trace('nextRangeInt', $result);
+        return $result;
     }
 
     public function nextInt(?int $max = null): int{
-        return $this->rng->nextInt($max);
+        $result = $this->rng->nextInt($max);
+        $this->trace('nextInt', $result);
+        return $result;
     }
 
     public function nextBit(): bool
     {
-        return $this->rng->nextBits(1) !== "\0";
+        $result = $this->rng->nextBits(1) !== "\0";
+        $this->trace('nextBit', $result);
+        return $result;
     }
 
     public function nextBool(int|float $prob = 0.5): bool
@@ -97,7 +126,7 @@ class RandUtil
         if(!$keys){
             throw new \InvalidArgumentException();
         }
-        $keyIdx = $this->rng->nextInt(count($keys) - 1);
+        $keyIdx = $this->nextInt(count($keys) - 1);
         return $items[$keys[$keyIdx]];
     }
 

src/sammo/TimeUtil.php

@@ -7,6 +7,19 @@ use phpDocumentor\Reflection\Types\Boolean;
 class TimeUtil
 {
 
+    private static function comparisonNow(): ?\DateTimeImmutable
+    {
+        $comparisonNow = getenv('REF_COMPARISON_NOW');
+        if (
+            getenv('REF_DETERMINISTIC_INSTALL_ENABLED') !== '1'
+            || !is_string($comparisonNow)
+            || $comparisonNow === ''
+        ) {
+            return null;
+        }
+        return new \DateTimeImmutable($comparisonNow);
+    }
+
     /** @deprecated */
     public static function DateToday()
     {
@@ -87,7 +100,7 @@ class TimeUtil
 
     public static function now(bool $withFraction = false): string
     {
-        $obj = new \DateTime();
+        $obj = static::comparisonNow() ?? new \DateTimeImmutable();
         return static::format($obj, $withFraction);
     }
 
@@ -182,11 +195,19 @@ class TimeUtil
     }
 
     public static function nowDateTime(): \DateTime{
+        $comparisonNow = static::comparisonNow();
+        if ($comparisonNow !== null) {
+            return \DateTime::createFromImmutable($comparisonNow);
+        }
         $now = time();
         return static::secondsToDateTime($now, false, true);
     }
 
     public static function nowDateTimeImmutable(): \DateTimeImmutable{
+        $comparisonNow = static::comparisonNow();
+        if ($comparisonNow !== null) {
+            return $comparisonNow;
+        }
         $now = time();
         return static::secondsToDateTime($now, true, true);
     }