TD-076: Command normalizer accepts non-string result payloads (#591)

Author: durable-workflow-ops

src/V2/Support/WorkflowCommandNormalizer.php

@@ -565,7 +565,7 @@ private static function resolveCommandArgumentsWithCodec(array $command, int $in
     /**
      * @param  array<string, mixed>  $command
      * @param  array<string, list<string>>  $errors
-     * @return array{payload: mixed, codec: string|null}
+     * @return array{payload: string|null, codec: string|null}
      */
     private static function resolveCommandPayloadWithCodec(
         array $command,
@@ -589,10 +589,31 @@ private static function resolveCommandPayloadWithCodec(
 
         if (is_array($command[$field])) {
             try {
-                return PayloadEnvelopeResolver::resolveCommandPayloadWithCodec(
+                $resolved = PayloadEnvelopeResolver::resolveCommandPayloadWithCodec(
                     $command[$field],
                     "commands.{$index}.{$field}",
                 );
+
+                $payload = $resolved['payload'];
+
+                if ($payload === null || is_string($payload)) {
+                    return [
+                        'payload' => $payload,
+                        'codec' => $resolved['codec'],
+                    ];
+                }
+
+                $errors["commands.{$index}.{$field}"] = [
+                    sprintf(
+                        'Workflow task command field [%s] must be a string or a payload envelope when provided.',
+                        $field,
+                    ),
+                ];
+
+                return [
+                    'payload' => null,
+                    'codec' => null,
+                ];
             } catch (ValidationException $e) {
                 foreach ($e->errors() as $errorField => $messages) {
                     $errors[$errorField] = $messages;
@@ -605,15 +626,22 @@ private static function resolveCommandPayloadWithCodec(
             }
         }
 
+        $errors["commands.{$index}.{$field}"] = [
+            sprintf(
+                'Workflow task command field [%s] must be a string or a payload envelope when provided.',
+                $field,
+            ),
+        ];
+
         return [
-            'payload' => $command[$field],
+            'payload' => null,
             'codec' => null,
         ];
     }
 
     /**
      * @param  array<string, mixed>  $command
-     * @param  array{payload: mixed, codec: string|null}  $resolved
+     * @param  array{payload: string|null, codec: string|null}  $resolved
      * @param  array<string, list<string>>  $errors
      */
     private static function payloadCodecForResolvedPayload(

tests/Unit/V2/WorkflowCommandNormalizerTest.php

@@ -43,6 +43,22 @@ public function testCompleteWorkflowAcceptsRawStringResult(): void
         ]], $out);
     }
 
+    public function testCompleteWorkflowRejectsNonStringResultPayload(): void
+    {
+        $errors = $this->normalizeAndCaptureErrors([
+            [
+                'type' => 'complete_workflow',
+                'result' => ['ok' => true],
+            ],
+        ]);
+
+        $this->assertArrayHasKey('commands.0.result', $errors);
+        $this->assertStringContainsString(
+            'must be a string or a payload envelope',
+            $errors['commands.0.result'][0],
+        );
+    }
+
     public function testCompleteWorkflowUnwrapsEnvelope(): void
     {
         $out = WorkflowCommandNormalizer::normalize([
@@ -452,6 +468,23 @@ public function testCompleteUpdateRequiresUpdateId(): void
         ]);
     }
 
+    public function testCompleteUpdateRejectsNonStringResultPayload(): void
+    {
+        $errors = $this->normalizeAndCaptureErrors([
+            [
+                'type' => 'complete_update',
+                'update_id' => '01UPDATE000000000000000001',
+                'result' => 42,
+            ],
+        ]);
+
+        $this->assertArrayHasKey('commands.0.result', $errors);
+        $this->assertStringContainsString(
+            'must be a string or a payload envelope',
+            $errors['commands.0.result'][0],
+        );
+    }
+
     public function testFailUpdatePreservesOptionalFields(): void
     {
         $out = WorkflowCommandNormalizer::normalize([