Conformance blocker: PHP worker query-task polling must satisfy server contract (#606)

Author: durable-workflow-ops

docs/api-stability.md

@@ -186,6 +186,10 @@ These classes are covered by the same semver rules as the server-facing
 `Support\*` list above. They intentionally wrap only the worker-plane
 HTTP routes and cold-replay stepping primitives; application workers still
 own registration maps, process lifecycle, logging, and command-line UX.
+Standalone PHP workflow-worker registrations advertise the `query_tasks`
+capability by default whenever they register workflow types; pass an explicit
+empty capabilities list only for custom workers that deliberately cannot
+answer server-routed workflow queries.
 Cold PHP Fiber runners must be constructed with the bridge `history_events`
 payload so workflow start time plus recorded activity, timer, child-workflow,
 side-effect, version marker, and search-attribute outcomes can be replayed

docs/architecture/query-and-live-debug.md

@@ -187,6 +187,10 @@ and returns `poll_status = 'leased'`; an empty long-poll returns
 `poll_status = 'empty'` with no task. Query task long-poll timeout
 semantics are the same clamped `WorkerProtocolVersion::longPollSemantics()`
 used by workflow and activity task polling.
+`WorkerProtocolClient::registerWorker()` advertises `query_tasks` by
+default for standalone PHP workers that register workflow types, and
+`pollQueryTasks()` sends a stable `poll_request_id` for every query
+poll attempt.
 
 Each leased query task carries `query_task_id`,
 `query_task_attempt`, `lease_owner`, `workflow_id`, `run_id`,

src/V2/Worker/WorkerProtocolClient.php

@@ -126,11 +126,9 @@ public function registerWorker(
             $body['workflow_definition_fingerprints'] = $workflowDefinitionFingerprints;
         }
 
-        if ($capabilities !== null) {
-            $body['capabilities'] = array_values(array_filter(
-                $capabilities,
-                static fn (mixed $capability): bool => is_string($capability) && $capability !== '',
-            ));
+        $advertisedCapabilities = $this->workerCapabilities($supportedWorkflowTypes, $capabilities);
+        if ($advertisedCapabilities !== null) {
+            $body['capabilities'] = $advertisedCapabilities;
         }
 
         if ($buildId !== null) {
@@ -369,7 +367,9 @@ public function pollQueryTasks(
             return [];
         }
 
-        $pollRequestId = $this->stringValue($pollRequestId) ?? 'query-poll-'.bin2hex(random_bytes(16));
+        $pollRequestId = is_string($pollRequestId) && trim($pollRequestId) !== ''
+            ? trim($pollRequestId)
+            : 'query-poll-'.bin2hex(random_bytes(16));
         $body = [
             'worker_id' => $this->resolveStandaloneWorkerId($workerId),
             'task_queue' => $this->resolveStandaloneTaskQueue($queue),
@@ -918,6 +918,39 @@ private function longPollRequestTimeoutSeconds(int $timeoutSeconds): int
         return max($pollTimeoutSeconds, WorkerProtocolVersion::DEFAULT_LONG_POLL_TIMEOUT) + 5;
     }
 
+    /**
+     * @param list<string> $supportedWorkflowTypes
+     * @param list<string>|null $capabilities
+     * @return list<string>|null
+     */
+    private function workerCapabilities(array $supportedWorkflowTypes, ?array $capabilities): ?array
+    {
+        if ($capabilities === null) {
+            return $this->hasSupportedWorkflowTypes($supportedWorkflowTypes)
+                ? [WorkerProtocolVersion::CAPABILITY_QUERY_TASKS]
+                : null;
+        }
+
+        return array_values(array_filter(
+            $capabilities,
+            static fn (mixed $capability): bool => is_string($capability) && $capability !== '',
+        ));
+    }
+
+    /**
+     * @param list<string> $supportedWorkflowTypes
+     */
+    private function hasSupportedWorkflowTypes(array $supportedWorkflowTypes): bool
+    {
+        foreach ($supportedWorkflowTypes as $workflowType) {
+            if (is_string($workflowType) && trim($workflowType) !== '') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private function resolveStandaloneWorkerId(?string $workerId): string
     {
         $resolved = $workerId ?? $this->registeredWorkerId;

tests/Unit/V2/WorkerProtocolClientTest.php

@@ -70,6 +70,70 @@ public function testRegisterWorkerSendsWorkerProtocolHeadersAndBody(): void
         ], $requestBody);
     }
 
+    public function testStandaloneWorkflowWorkerRegistrationAdvertisesQueryTaskCapabilityByDefault(): void
+    {
+        $http = new HttpFactory();
+        $requestBody = null;
+
+        $http->fake(function (Request $request) use ($http, &$requestBody) {
+            $requestBody = $request->data();
+
+            return $http->response(['registered' => true], 201);
+        });
+
+        $client = new WorkerProtocolClient($http, 'http://server:8080', 'test-token', 'default');
+        $client->registerWorker(
+            workerId: 'php-worker',
+            taskQueue: 'polyglot',
+            supportedWorkflowTypes: ['polyglot.php.signal-query'],
+        );
+
+        $this->assertSame(['query_tasks'], $requestBody['capabilities'] ?? null);
+    }
+
+    public function testActivityOnlyWorkerRegistrationDoesNotAdvertiseQueryTasksByDefault(): void
+    {
+        $http = new HttpFactory();
+        $requestBody = null;
+
+        $http->fake(function (Request $request) use ($http, &$requestBody) {
+            $requestBody = $request->data();
+
+            return $http->response(['registered' => true], 201);
+        });
+
+        $client = new WorkerProtocolClient($http, 'http://server:8080', 'test-token', 'default');
+        $client->registerWorker(
+            workerId: 'php-activity-worker',
+            taskQueue: 'polyglot',
+            supportedActivityTypes: ['polyglot.php.activity'],
+        );
+
+        $this->assertArrayNotHasKey('capabilities', $requestBody);
+    }
+
+    public function testExplicitWorkerCapabilitiesOverrideQueryTaskDefault(): void
+    {
+        $http = new HttpFactory();
+        $requestBody = null;
+
+        $http->fake(function (Request $request) use ($http, &$requestBody) {
+            $requestBody = $request->data();
+
+            return $http->response(['registered' => true], 201);
+        });
+
+        $client = new WorkerProtocolClient($http, 'http://server:8080', 'test-token', 'default');
+        $client->registerWorker(
+            workerId: 'php-worker',
+            taskQueue: 'polyglot',
+            supportedWorkflowTypes: ['polyglot.php.signal-query'],
+            capabilities: [],
+        );
+
+        $this->assertSame([], $requestBody['capabilities'] ?? null);
+    }
+
     public function testStandaloneQueryPollAndCompleteUseCachedLease(): void
     {
         $http = new HttpFactory();