[rigazilla]

Summary

Step 11a of error handling (error surfacing), per the split agreed in docs/ERROR_HANDLING_DESIGN.md (D1). Step 11b (user-decided retry) is deferred to a follow-up PR.

• Replace bare std::runtime_error at the operation throw sites with a pure-data HotRodClientException carrying FailurePhase (BeforeSend / AfterSend / ServerError), serverStatus, triedNodes, and ownersExhausted. It still derives from std::runtime_error, so existing catches keep working.
• Parse the server ERROR response (opcode 0x50): its length-prefixed message is drained in the read loop before the pending-request lookup, so an orphan ERROR can no longer desync the connection stream.
• Add missing status constants (0x84 REQUEST_PARSING_ERROR, 0x87 NODE_SUSPECTED, 0x88 ILLEGAL_LIFECYCLE_STATE) to HeaderCodec.h.

Classification: two orthogonal axes (no stored retriable flag)

• isTransient() — futility ("is a retry worth it?", the library's call).
• outcomeUncertain() — ambiguity ("might the op have applied?", the user's call).

COMMAND_TIMEOUT (0x86) is treated as transient and outcome-uncertain. This intentionally diverges from the Java client (which does not retry it) — safe here because ambiguity is carried separately by outcomeUncertain(), so the user still decides. Rationale in docs/DECISIONS.md (2026-09-25).

Testing

• 11 new unit tests + 3 new integration tests.
• ConnectionUsableAfterServerError proves the stream stays in sync: trigger an ERROR on a missing cache, then PUT/GET round-trip on a real cache over the same connection.
• Full suite green: 187 unit, 78 integration across 15 suites.

Out of scope (Step 11b, follow-up)

Defaulted RetryContext on ops, exclusion-aware selectServerForKey, proxyToNonOwner (default true), thread-safe pool/topology, triedNodes accumulation.

🤖 Generated with Claude Code