Merge pull request #697 from durable-workflow/fix/898-datetime-visibility

Preserve UTC instants and microseconds in visibility queries

Author: rmcdaniel

app/Support/WorkflowVisibilityQuery.php

@@ -6,6 +6,7 @@
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Support\Carbon;
 use Illuminate\Validation\ValidationException;
+use Workflow\V2\Support\UtcScheduleTimestamp;
 
 class WorkflowVisibilityQuery
 {
@@ -744,15 +745,15 @@ private function coerceBool(mixed $literal, string $field): bool
         throw $this->invalidValue($field, 'a boolean literal');
     }
 
-    private function coerceDatetime(mixed $literal, string $field): Carbon
+    private function coerceDatetime(mixed $literal, string $field): string
     {
         if ($literal instanceof \DateTimeInterface) {
-            return Carbon::instance($literal);
+            return UtcScheduleTimestamp::databaseValue($literal);
         }
 
         if (is_string($literal) || is_int($literal) || is_float($literal)) {
             try {
-                return Carbon::parse($literal);
+                return UtcScheduleTimestamp::databaseValue(Carbon::parse($literal));
             } catch (\Throwable) {
                 throw $this->invalidValue($field, 'a datetime literal');
             }

tests/Feature/WorkflowSearchAttributeVisibilityQueryTest.php

@@ -6,6 +6,7 @@
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Queue;
+use PHPUnit\Framework\Attributes\DataProvider;
 use Tests\Feature\Concerns\ServerTestHelpers;
 use Tests\Fixtures\AwaitApprovalWorkflow;
 use Tests\TestCase;
@@ -209,6 +210,58 @@ public function test_workflow_list_query_rejects_undefined_search_attribute(): v
             );
     }
 
+    #[DataProvider('datetimeInstants')]
+    public function test_datetime_visibility_preserves_offset_instants_and_microseconds(string $literal): void
+    {
+        foreach (['default', 'other'] as $namespace) {
+            SearchAttributeDefinition::query()->create([
+                'namespace' => $namespace,
+                'name' => 'occurred_at',
+                'type' => 'datetime',
+            ]);
+        }
+
+        $this->startWorkflow('default', 'wf-date-match', [
+            'occurred_at' => '2026-10-08T10:34:56.123456Z',
+        ]);
+        $this->startWorkflow('default', 'wf-date-neighbor', [
+            'occurred_at' => '2026-10-08T10:34:56.123457Z',
+        ]);
+        $this->startWorkflow('other', 'wf-date-other', [
+            'occurred_at' => '2026-10-08T10:34:56.123456Z',
+        ]);
+
+        $this->assertSame(['wf-date-match'], $this->workflowIdsForQuery('occurred_at = "'.$literal.'"'));
+        $this->assertSame(['wf-date-neighbor'], $this->workflowIdsForQuery('occurred_at != "'.$literal.'"'));
+        $this->assertSame(['wf-date-match'], $this->workflowIdsForQuery('occurred_at IN ("'.$literal.'")'));
+        $this->assertSame(['wf-date-neighbor'], $this->workflowIdsForQuery('NOT occurred_at IN ("'.$literal.'")'));
+        $this->assertSame(['wf-date-match'], $this->workflowIdsForQuery(
+            'occurred_at >= "'.$literal.'" AND occurred_at < "2026-10-08T10:34:56.123457Z"',
+        ));
+        $this->assertSame(['wf-date-other'], $this->workflowIdsForQuery('occurred_at = "'.$literal.'"', 'other'));
+
+        DB::table('workflow_run_summaries')->where('workflow_instance_id', 'wf-date-match')->update([
+            'started_at' => '2026-10-08 10:34:56.123456',
+        ]);
+        DB::table('workflow_run_summaries')->where('workflow_instance_id', 'wf-date-neighbor')->update([
+            'started_at' => '2026-10-08 10:34:56.123457',
+        ]);
+        $this->assertSame(['wf-date-match'], $this->workflowIdsForQuery('StartTime = "'.$literal.'"'));
+        $this->assertSame(['wf-date-match'], $this->workflowIdsForQuery('StartTime IN ("'.$literal.'")'));
+    }
+
+    /**
+     * @return iterable<string, array{string}>
+     */
+    public static function datetimeInstants(): iterable
+    {
+        yield 'positive offset' => ['2026-10-08T12:34:56.123456+02:00'];
+        yield 'negative offset' => ['2026-10-08T06:34:56.123456-04:00'];
+        yield 'next local day' => ['2026-10-09T00:34:56.123456+14:00'];
+        yield 'previous local day' => ['2026-10-07T22:34:56.123456-12:00'];
+        yield 'utc' => ['2026-10-08T10:34:56.123456Z'];
+    }
+
     /**
      * @param  array<string, scalar|list<string>|null>  $searchAttributes
      */