v2: relax control-plane payload envelope to accept any registered codec

`PayloadEnvelopeResolver::resolveToArray()` is the shared input decoder for
signal, query, and update surfaces. It used to hard-reject anything other
than the "json" codec, which blocks the Avro (#330) default codec from
reaching those surfaces and made the error message surprise clients that
already carry Avro/PHP-closure payloads everywhere else.

Change it to decode with `Serializer::unserializeWithCodec($codec, $blob)`
and validate that the result is an array. That accepts json, avro, and
the two legacy PHP closure codecs, and surfaces codec-specific decode
errors as a friendly validation message instead of a bare exception.

Add a PayloadEnvelopeResolverTest covering:
- null / empty short-circuit
- positional-array passthrough
- json + legacy-Y round trips
- avro round trip (skipped when apache/avro is unavailable)
- unknown codec rejection
- non-array and malformed blob rejection

Partial progress on #331 (signal / query / update — items 1–3 of the
surface list). The remaining items (child workflow propagation,
continue-as-new, schedule input, history event payloads, Waterline and
CLI rendering, and history export) are still open.

Author: durable-workflow-ops

src/V2/Support/PayloadEnvelopeResolver.php

@@ -35,9 +35,10 @@ final class PayloadEnvelopeResolver
      * Used for control-plane surfaces (signal, query, update) where the
      * package API expects a PHP array, not a codec-tagged blob. Accepts
      * either a plain array of positional arguments or a {codec, blob}
-     * envelope — when an envelope is received, the blob is decoded using
-     * the declared codec. Only the "json" codec is supported for array
-     * surfaces; other codecs cannot be losslessly represented as PHP arrays.
+     * envelope. When an envelope is received, the blob is decoded using
+     * the declared codec — any codec in the {@see CodecRegistry} that can
+     * round-trip an array is accepted (json, avro, and the legacy PHP
+     * closure codecs). The decoded value must be an array.
      *
      * @param  mixed  $input  the `input` field from a validated request
      * @return array<int|string, mixed>  arguments (positional or named)
@@ -60,18 +61,19 @@ public static function resolveToArray($input, string $field = 'input'): array
 
         $envelope = self::resolveExplicitEnvelope($input, $field);
 
-        if ($envelope['codec'] !== 'json') {
+        try {
+            $decoded = Serializer::unserializeWithCodec($envelope['codec'], $envelope['blob']);
+        } catch (\Throwable $e) {
             throw ValidationException::withMessages([
-                $field . '.codec' => [sprintf(
-                    'Only the "json" codec is supported for %s on this surface. Got "%s".',
+                $field . '.blob' => [sprintf(
+                    'The %s envelope blob could not be decoded with codec "%s": %s',
                     $field,
                     $envelope['codec'],
+                    $e->getMessage(),
                 )],
             ]);
         }
 
-        $decoded = json_decode($envelope['blob'], true);
-
         if (! is_array($decoded)) {
             throw ValidationException::withMessages([
                 $field . '.blob' => [sprintf('The %s envelope blob must decode to an array.', $field)],

tests/Unit/V2/PayloadEnvelopeResolverTest.php

@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\V2;
+
+use Illuminate\Validation\ValidationException;
+use Tests\TestCase;
+use Workflow\Serializers\Serializer;
+use Workflow\V2\Support\PayloadEnvelopeResolver;
+
+final class PayloadEnvelopeResolverTest extends TestCase
+{
+    public function testResolveToArrayReturnsEmptyForNullOrEmpty(): void
+    {
+        $this->assertSame([], PayloadEnvelopeResolver::resolveToArray(null));
+        $this->assertSame([], PayloadEnvelopeResolver::resolveToArray([]));
+    }
+
+    public function testResolveToArrayReturnsPositionalArrayUnchanged(): void
+    {
+        $this->assertSame(
+            ['alpha', 'beta'],
+            PayloadEnvelopeResolver::resolveToArray(['alpha', 'beta']),
+        );
+    }
+
+    public function testResolveToArrayDecodesJsonEnvelope(): void
+    {
+        $envelope = [
+            'codec' => 'json',
+            'blob' => Serializer::serializeWithCodec('json', ['a', 'b', 42]),
+        ];
+
+        $this->assertSame(
+            ['a', 'b', 42],
+            PayloadEnvelopeResolver::resolveToArray($envelope),
+        );
+    }
+
+    public function testResolveToArrayDecodesLegacyYEnvelope(): void
+    {
+        $envelope = [
+            'codec' => 'workflow-serializer-y',
+            'blob' => Serializer::serializeWithCodec('workflow-serializer-y', ['a', 'b']),
+        ];
+
+        $this->assertSame(
+            ['a', 'b'],
+            PayloadEnvelopeResolver::resolveToArray($envelope),
+        );
+    }
+
+    public function testResolveToArrayDecodesAvroEnvelopeWhenInstalled(): void
+    {
+        if (! class_exists(\Apache\Avro\Schema\AvroSchema::class)) {
+            $this->markTestSkipped('apache/avro package is not installed in this environment.');
+        }
+
+        $envelope = [
+            'codec' => 'avro',
+            'blob' => Serializer::serializeWithCodec('avro', ['hello', 123]),
+        ];
+
+        $this->assertSame(
+            ['hello', 123],
+            PayloadEnvelopeResolver::resolveToArray($envelope),
+        );
+    }
+
+    public function testResolveToArrayRejectsUnknownCodec(): void
+    {
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('Unknown payload codec');
+
+        PayloadEnvelopeResolver::resolveToArray([
+            'codec' => 'does-not-exist',
+            'blob' => 'xxx',
+        ]);
+    }
+
+    public function testResolveToArrayRejectsNonArrayBlobPayload(): void
+    {
+        $envelope = [
+            'codec' => 'json',
+            'blob' => '"just a string"',
+        ];
+
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('must decode to an array');
+
+        PayloadEnvelopeResolver::resolveToArray($envelope);
+    }
+
+    public function testResolveToArrayRejectsCorruptBlob(): void
+    {
+        $envelope = [
+            'codec' => 'json',
+            'blob' => '{not-valid-json',
+        ];
+
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('could not be decoded with codec "json"');
+
+        PayloadEnvelopeResolver::resolveToArray($envelope);
+    }
+}