#352: order signal timeout races by history

Author: durable-workflow-ops

src/V2/Support/WorkflowExecutor.php

@@ -663,14 +663,28 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                     ? $this->signalTimeoutFiredEvent($run, $sequence, $current->name)
                     : null;
                 $signalWaitId = $this->signalWaitId($run, $sequence, $current) ?? (string) Str::ulid();
+                $signalCommand = $this->pendingSignalCommand($run, $current);
 
-                if (
+                $timeoutHasWon = (
                     $current->timeoutSeconds !== null
                     && (
                         $timeoutFiredEvent !== null
                         || ($timeoutScheduledEvent === null && $timeoutTimer?->status === TimerStatus::Fired)
                     )
-                ) {
+                );
+
+                if ($timeoutHasWon && $signalCommand !== null && $timeoutFiredEvent !== null) {
+                    $signalReceivedEvent = $this->signalReceivedEventForCommand($run, $signalCommand);
+
+                    if (
+                        $signalReceivedEvent !== null
+                        && $signalReceivedEvent->sequence < $timeoutFiredEvent->sequence
+                    ) {
+                        $timeoutHasWon = false;
+                    }
+                }
+
+                if ($timeoutHasWon) {
                     $this->recordSignalWait($run, $task, $sequence, $current, $signalWaitId);
 
                     try {
@@ -689,8 +703,6 @@ public function run(WorkflowRun $run, WorkflowTask $task): ?WorkflowTask
                     continue;
                 }
 
-                $signalCommand = $this->pendingSignalCommand($run, $current);
-
                 if ($signalCommand !== null) {
                     $signalWaitId = $this->signalWaitIdForCommand($run, $signalCommand, $current->name);
 
@@ -1855,6 +1867,17 @@ private function pendingSignalCommand(WorkflowRun $run, SignalCall $signalCall):
         return $command;
     }
 
+    private function signalReceivedEventForCommand(WorkflowRun $run, WorkflowCommand $command): ?WorkflowHistoryEvent
+    {
+        /** @var WorkflowHistoryEvent|null $event */
+        $event = $run->historyEvents->first(
+            static fn (WorkflowHistoryEvent $event): bool => $event->event_type === HistoryEventType::SignalReceived
+                && $event->workflow_command_id === $command->id
+        );
+
+        return $event;
+    }
+
     private function applySignal(
         WorkflowRun $run,
         WorkflowTask $task,
@@ -1923,11 +1946,7 @@ private function recordSignalWait(
 
     private function signalWaitIdForCommand(WorkflowRun $run, WorkflowCommand $command, string $signalName): string
     {
-        /** @var WorkflowHistoryEvent|null $receivedEvent */
-        $receivedEvent = $run->historyEvents->first(
-            static fn (WorkflowHistoryEvent $event): bool => $event->event_type === HistoryEventType::SignalReceived
-                && $event->workflow_command_id === $command->id
-        );
+        $receivedEvent = $this->signalReceivedEventForCommand($run, $command);
 
         $signalWaitId = $receivedEvent === null
             ? null

tests/Feature/V2/V2AwaitWorkflowTest.php

@@ -1435,6 +1435,101 @@ public function testAwaitStringSignalTimeoutReturnsNullAndReplaysForQueries(): v
         }
     }
 
+    public function testAwaitStringSignalReceivedBeforeTimeoutFiredWinsByHistoryOrder(): void
+    {
+        Queue::fake();
+
+        try {
+            Carbon::setTestNow(Carbon::parse('2026-04-16 12:00:00'));
+
+            $workflow = WorkflowStub::make(TestAwaitSignalTimeoutWorkflow::class, 'await-signal-before-timeout-race');
+            $workflow->start('approved-by', 5);
+
+            $this->runReadyWorkflowTask($workflow->runId());
+
+            $signal = $workflow->attemptSignal('approved-by', 'Jordan');
+
+            $this->assertTrue($signal->accepted());
+
+            Carbon::setTestNow(now()->addSeconds(5));
+
+            $this->runReadyTimerTask($workflow->runId());
+            $this->runReadyWorkflowTask($workflow->runId());
+
+            $this->assertTrue($workflow->refresh()->completed());
+            $this->assertSame([
+                'payload' => 'Jordan',
+                'timed_out' => false,
+                'stage' => 'received',
+                'workflow_id' => 'await-signal-before-timeout-race',
+                'run_id' => $workflow->runId(),
+            ], $workflow->output());
+
+            $eventTypes = WorkflowHistoryEvent::query()
+                ->where('workflow_run_id', $workflow->runId())
+                ->orderBy('sequence')
+                ->pluck('event_type')
+                ->map(static fn ($eventType) => $eventType->value)
+                ->all();
+
+            $this->assertLessThan(
+                array_search('TimerFired', $eventTypes, true),
+                array_search('SignalReceived', $eventTypes, true),
+            );
+            $this->assertContains('SignalApplied', $eventTypes);
+        } finally {
+            Carbon::setTestNow();
+        }
+    }
+
+    public function testAwaitStringSignalTimeoutFiredBeforeSignalReceivedWinsByHistoryOrder(): void
+    {
+        Queue::fake();
+
+        try {
+            Carbon::setTestNow(Carbon::parse('2026-04-16 12:00:00'));
+
+            $workflow = WorkflowStub::make(TestAwaitSignalTimeoutWorkflow::class, 'await-timeout-before-signal-race');
+            $workflow->start('approved-by', 5);
+
+            $this->runReadyWorkflowTask($workflow->runId());
+
+            Carbon::setTestNow(now()->addSeconds(5));
+
+            $this->runReadyTimerTask($workflow->runId());
+
+            $signal = $workflow->attemptSignal('approved-by', 'Jordan');
+
+            $this->assertTrue($signal->accepted());
+
+            $this->runReadyWorkflowTask($workflow->runId());
+
+            $this->assertTrue($workflow->refresh()->completed());
+            $this->assertSame([
+                'payload' => null,
+                'timed_out' => true,
+                'stage' => 'timed-out',
+                'workflow_id' => 'await-timeout-before-signal-race',
+                'run_id' => $workflow->runId(),
+            ], $workflow->output());
+
+            $eventTypes = WorkflowHistoryEvent::query()
+                ->where('workflow_run_id', $workflow->runId())
+                ->orderBy('sequence')
+                ->pluck('event_type')
+                ->map(static fn ($eventType) => $eventType->value)
+                ->all();
+
+            $this->assertLessThan(
+                array_search('SignalReceived', $eventTypes, true),
+                array_search('TimerFired', $eventTypes, true),
+            );
+            $this->assertNotContains('SignalApplied', $eventTypes);
+        } finally {
+            Carbon::setTestNow();
+        }
+    }
+
     public function testAwaitStringSignalPreservesEmptyAndMultipleArgumentPayloadRules(): void
     {
         Queue::fake();