fix(client): bound the socket-level wait itself, not just the loop

Third finding on the same seam, and the root of all three: the deadline
arithmetic in receive() means nothing while the blocking primitive
answers only to the constructor-time steady-state timeout. A peer that
accepts and then goes silent — a proxy fronting an unreachable backend,
the exact case connect() is being bounded for — parks the first recv()
for the full steady-state window before any deadline is rechecked.

Every socket wait now takes the remaining budget of the loop it serves:
per-call on the coroutine client, via a per-wait refresh of the client
timeout option on the synchronous one. Where a synchronous build applies
options only at connect(), the behaviour degrades to exactly what shipped
before — the loop-level deadline still bounds the total — and where
honoured, the wait matches the budget.

The contract tests observe the socket layer directly: every handshake
wait stays within the remaining connect budget, steady-state waits return
to the full receive timeout, and the synchronous transport sees its
option refreshed per wait.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: abnegate

src/Client.php

@@ -546,6 +546,31 @@ private function receiveTimeout(): float
         return \max(0.001, $this->handshakeDeadline - \microtime(true));
     }
 
+    /**
+     * One socket-level wait, bounded by the caller's remaining budget.
+     *
+     * The deadline arithmetic in receive() means nothing if the blocking
+     * primitive itself waits on the constructor-time steady-state timeout: a
+     * peer that accepts and then goes silent parks the first recv() for that
+     * full window before any deadline is rechecked — which is exactly how a
+     * proxy fronting an unreachable backend behaves during connect().
+     */
+    private function recvWithin(float $seconds): string|false
+    {
+        if ($this->client instanceof CoroutineClient) {
+            return @$this->client->recv($seconds);
+        }
+
+        // The synchronous client reads its per-operation timeout from the
+        // client options. Where a build applies options only at connect(),
+        // this degrades to the pre-existing behaviour — the socket waits the
+        // steady-state timeout — and the deadline check above still bounds
+        // the loop; where honoured, the socket-level wait matches the budget.
+        @$this->client->set(['timeout' => $seconds]);
+
+        return @$this->client->recv();
+    }
+
     /**
      * Receive a message from connection.
      *
@@ -569,12 +594,13 @@ private function receive(): stdClass|array|int
         $deadline = \microtime(true) + $this->receiveTimeout();
 
         do {
-            if (\microtime(true) >= $deadline) {
+            $remaining = $deadline - \microtime(true);
+            if ($remaining <= 0) {
                 $this->invalidate();
                 throw new Exception('Receive timeout: no data received within reasonable time', 11601);
             }
 
-            $chunk = @$this->client->recv();
+            $chunk = $this->recvWithin(\min($remaining, $this->timeout));
             $errCode = $this->client->errCode ?? 0;
 
             // false => socket-level wait already elapsed with no payload.

tests/ClientTest.php

@@ -33,9 +33,13 @@ private function connectTransport(string $host, int $port, float $timeout, int $
         return $result;
     }
 
-    private function receiveTransport(): string|false
+    /** @var list<float> */
+    public array $receiveTimeouts = [];
+
+    private function receiveTransport(float $timeout = 0.0): string|false
     {
         $this->events[] = ['receive'];
+        $this->receiveTimeouts[] = $timeout;
         $receive = array_shift($this->receives) ?? ['result' => '', 'error' => 0];
         $this->errCode = $receive['error'];
 
@@ -59,10 +63,22 @@ final class SyncTransportDouble extends SwooleClient
 
     public array $closes = [];
 
+    /** @var list<float> */
+    public array $timeoutOptions = [];
+
     public function __construct()
     {
     }
 
+    public function set(array $settings): bool
+    {
+        if (isset($settings['timeout'])) {
+            $this->timeoutOptions[] = (float) $settings['timeout'];
+        }
+
+        return true;
+    }
+
     public function close(bool $force = false): bool
     {
         $this->events[] = ['close', $force];
@@ -124,7 +140,7 @@ public function isConnected(): bool
 
     public function recv(float $timeout = 0): string|false
     {
-        return $this->receiveTransport();
+        return $this->receiveTransport($timeout);
     }
 
     public function send(string $data, float $timeout = 0): int|false
@@ -303,6 +319,68 @@ public function testFailedHandshakeInvalidatesTheDialedSocket(): void
         );
     }
 
+    public function testSocketWaitsNeverExceedTheRemainingConnectBudget(): void
+    {
+        // The deadline arithmetic means nothing if the blocking primitive
+        // itself waits on the steady-state timeout: a peer that accepts and
+        // then goes silent parks the first recv() for that full window before
+        // any deadline is rechecked (greptile P1 x3 on #46 — the root).
+        $transport = new CoroutineTransportDouble();
+        $transport->open = false;
+        $transport->receives = [
+            ['result' => $this->frame(['ok' => 1.0]), 'error' => 0],
+            ['result' => $this->frame(['ok' => 1.0]), 'error' => 0],
+        ];
+        $client = $this->client($transport, timeout: 5.0, connectTimeout: 0.2);
+        $this->set($client, 'auth', new AuthenticationDouble());
+
+        $client->connect();
+
+        $this->assertNotSame([], $transport->receiveTimeouts);
+        foreach ($transport->receiveTimeouts as $wait) {
+            $this->assertGreaterThan(0.0, $wait);
+            $this->assertLessThanOrEqual(
+                0.2,
+                $wait,
+                'A handshake socket wait must be bounded by the remaining connect budget, '
+                . 'never the steady-state receive timeout',
+            );
+        }
+
+        $transport->receives = [['result' => $this->frame(['ok' => 1.0]), 'error' => 0]];
+        $transport->receiveTimeouts = [];
+        $client->query(['ping' => 1]);
+
+        $this->assertNotSame([], $transport->receiveTimeouts);
+        $this->assertEqualsWithDelta(
+            5.0,
+            $transport->receiveTimeouts[0],
+            0.05,
+            'Steady-state socket waits must use the full receive timeout again',
+        );
+    }
+
+    public function testSyncSocketWaitsRefreshTheClientTimeoutOption(): void
+    {
+        // The synchronous client cannot take a per-call timeout; the budget
+        // travels through the client options instead, refreshed per wait.
+        $transport = new SyncTransportDouble();
+        $transport->open = false;
+        $transport->receives = [
+            ['result' => $this->frame(['ok' => 1.0]), 'error' => 0],
+            ['result' => $this->frame(['ok' => 1.0]), 'error' => 0],
+        ];
+        $client = $this->client($transport, timeout: 5.0, connectTimeout: 0.2);
+        $this->set($client, 'auth', new AuthenticationDouble());
+
+        $client->connect();
+
+        $this->assertNotSame([], $transport->timeoutOptions);
+        foreach ($transport->timeoutOptions as $wait) {
+            $this->assertLessThanOrEqual(0.2, $wait);
+        }
+    }
+
     public function testSyncReceiveFailureHardClosesAndClearsState(): void
     {
         $transport = new SyncTransportDouble();