fix: always emit error payload retryable flag (§12) (#162)

ErrorPayload::toArray() always emits a retryable boolean, derived from the
canonical code's default when not set explicitly, so LEASE_EXPIRED and
BUDGET_EXHAUSTED travel as retryable:false and INTERNAL_ERROR as
retryable:true. Adds an effectiveRetryable() accessor.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nficano

src/Errors/ErrorPayload.php

@@ -50,6 +50,16 @@ public static function fromException(ARCPException $e): self
         );
     }
 
+    /**
+     * The effective retryability emitted on the wire: an explicit flag wins,
+     * otherwise the canonical code's default (§12), defaulting to false for
+     * namespaced/extension codes with no enum mapping.
+     */
+    public function effectiveRetryable(): bool
+    {
+        return $this->retryable ?? ($this->canonical()?->defaultRetryable() ?? false);
+    }
+
     /** Map the wire code to a canonical {@see ErrorCode}, when possible. */
     public function canonical(): ?ErrorCode
     {
@@ -71,21 +81,23 @@ public function isNamespaced(): bool
      * @return array{
      *     code: string,
      *     message: string,
-     *     retryable?: bool,
+     *     retryable: bool,
      *     details?: ErrorDetails,
      *     cause?: array<string, mixed>,
      *     trace_id?: string,
      * }
      */
     public function toArray(): array
     {
+        // §12: error payloads MUST carry a retryable boolean. Emit the
+        // effective value even when not set explicitly so LEASE_EXPIRED /
+        // BUDGET_EXHAUSTED always travel as retryable:false and
+        // INTERNAL_ERROR as retryable:true.
         $out = [
             'code' => $this->code,
             'message' => $this->message,
+            'retryable' => $this->effectiveRetryable(),
         ];
-        if ($this->retryable !== null) {
-            $out['retryable'] = $this->retryable;
-        }
         if ($this->details !== []) {
             $out['details'] = $this->details;
         }

tests/Unit/ErrorsTest.php

@@ -172,6 +172,25 @@ public function testErrorPayloadRoundTrip(): void
         self::assertSame($payload->details, $back->details);
     }
 
+    public function testRetryableAlwaysEmittedAndDerived(): void
+    {
+        // §12: every encoded error payload carries a retryable boolean even
+        // when not set explicitly.
+        $leaseExpired = new ErrorPayload('LEASE_EXPIRED', 'lease ended');
+        self::assertArrayHasKey('retryable', $leaseExpired->toArray());
+        self::assertFalse($leaseExpired->toArray()['retryable']);
+
+        $budget = new ErrorPayload('BUDGET_EXHAUSTED', 'no funds');
+        self::assertFalse($budget->toArray()['retryable']);
+
+        $internal = new ErrorPayload('INTERNAL', 'boom');
+        self::assertTrue($internal->toArray()['retryable']);
+
+        // An explicit flag still wins over the derived default.
+        $forced = new ErrorPayload('INTERNAL', 'boom', retryable: false);
+        self::assertFalse($forced->toArray()['retryable']);
+    }
+
     public function testErrorPayloadFromException(): void
     {
         $e = new PermissionDeniedException('p', 'r');

tests/Unit/MessageCatalogRoundTripTest.php

@@ -108,7 +108,7 @@ public function testCatalogRegistersEverything(): void
     public static function specimens(): iterable
     {
         $now = new \DateTimeImmutable('2026-05-09T12:00:00Z');
-        $err = new ErrorPayload('INTERNAL', 'something went wrong');
+        $err = new ErrorPayload('INTERNAL', 'something went wrong', true);
 
         yield 'session.open' => [new SessionOpen(
             Auth::bearer('t'),