fix: wrap decoder exceptions as DecodeError at seam B

README.md

@@ -49,7 +49,7 @@ with Client(base_url="https://example.test") as client:
     print(response.json())
 ```
 
-Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`:
+Typed decoding via `response_model=` works in both worlds — requires `pip install httpware[pydantic]`. Decode failures (malformed body, schema mismatch) raise `httpware.DecodeError`, a `ClientError` subclass — so `except httpware.ClientError` covers them alongside transport and status errors.
 
 ```python
 from httpware import AsyncClient

docs/errors.md

@@ -26,7 +26,8 @@ ClientError                          (catch-all for anything httpware raises)
 │       ├── InternalServerError     (500)
 │       └── ServiceUnavailableError (503)
 ├── RetryBudgetExhaustedError       (a retry was needed but the budget refused)
-└── BulkheadFullError                (acquire_timeout elapsed before a slot opened)
+├── BulkheadFullError                (acquire_timeout elapsed before a slot opened)
+└── DecodeError                      (response_model= decoder failed; HTTP call itself succeeded)
 ```
 
 ## Status-to-exception mapping
@@ -128,6 +129,32 @@ except RetryBudgetExhaustedError as exc:
     )
 ```
 
+## `DecodeError`
+
+`DecodeError` is raised when `response_model=` is set on a request and the active `ResponseDecoder` failed to parse the response body. The HTTP call itself succeeded — status was 2xx/3xx and the transport delivered the body intact — but the body could not be coerced into the requested model. The exception is raised independently of which decoder is in use (`PydanticDecoder`, `MsgspecDecoder`, or a third-party adapter), so `except httpware.ClientError` is sufficient to cover the response-model decode path.
+
+Fields:
+
+- `response: httpx2.Response` — the response whose body failed to decode. Status, headers, and the originating `request` are all available via `exc.response.*`.
+- `model: type` — the type that was passed as `response_model=`.
+- `original: BaseException` — the underlying library exception (e.g., `pydantic.ValidationError`, `msgspec.ValidationError`, `msgspec.DecodeError`). Also available via `exc.__cause__`.
+
+```python
+from httpware import AsyncClient, DecodeError
+
+
+try:
+    user = await client.get("/users/1", response_model=User)
+except DecodeError as exc:
+    _LOGGER.error(
+        "decode failed for %s into %s: %s",
+        exc.response.request.url,
+        exc.model.__name__,
+        exc.original,
+    )
+    raise
+```
+
 ## See also
 
 - **[Resilience reference](resilience.md)** — `AsyncRetry`, `RetryBudget`, `AsyncBulkhead` parameter tables.

planning/engineering.md

@@ -36,10 +36,10 @@ The 0.1.0 seams numbered 1 (Middleware↔Transport) and 4 (Transport↔httpx2) h
 - **Contract:** the middleware chain is composed once at client construction and frozen for the client's lifetime. Both worlds follow the same contract; the only difference is the per-world type: `AsyncClient` composes `AsyncMiddleware` via `compose_async` (the continuation type is `AsyncNext`), and `Client` composes `Middleware` via `compose` (the continuation type is `Next`). Both `compose` and `compose_async` live in `src/httpware/middleware/chain.py`. The chain bottom (the "terminal") is internal: it calls `self._httpx2_client.send(request)`, maps `httpx2` errors to `httpware` errors, and raises a `StatusError` subclass on 4xx/5xx. Same lifecycle rules in both worlds.
 - **Rule:** mutating the chain after construction is not supported. Per-request behavior goes through `httpx2.Request.extensions` or through `extensions=` kwargs at call sites.
 
-### Seam B: `AsyncClient ↔ ResponseDecoder`
+### Seam B: `Client`/`AsyncClient` ↔ `ResponseDecoder`
 
 - **Where:** `src/httpware/client.py` ↔ `src/httpware/decoders/`.
-- **Contract:** the decoder is invoked when the caller passes `response_model=`. The protocol is `decode(content: bytes, model: type[T]) -> T`. Decoder errors (`pydantic.ValidationError`, `msgspec.ValidationError`) propagate unwrapped.
+- **Contract:** the decoder is invoked when the caller passes `response_model=`. The protocol is `decode(content: bytes, model: type[T]) -> T`. Any exception raised by `decode` is wrapped by `Client.send` / `AsyncClient.send` into `httpware.DecodeError` (a `ClientError` subclass carrying `response`, `model`, `original`). Decoder implementers do not need to raise `DecodeError` directly.
 - **Rule:** the decoder must operate on raw bytes in a single parse pass. Two-pass decoding (`json.loads` then `validate_python`) is rejected: a single bytes-in / typed-object-out pass avoids the redundant intermediate `dict` allocation and parses faster. The Pydantic adapter implements this as `TypeAdapter(model).validate_json(content)`, with the `TypeAdapter` itself memoized via `@functools.lru_cache(maxsize=1024)` on a module-level `_get_adapter(model)` factory (the adapter is the expensive part to build). The msgspec adapter implements it as `msgspec.json.decode(content, type=model)`.
 
 ### Seam C: `httpware ↔ optional extras`
@@ -65,6 +65,8 @@ The error-mapping table (what `httpx2` exception maps to which `httpware` except
 
 `TimeoutError` inherits from both `httpware.ClientError` and `builtins.TimeoutError` so `except builtins.TimeoutError` (the form `asyncio.wait_for` uses) also catches httpware-raised timeouts.
 
+`DecodeError` covers the case where `response_model=` is set, the HTTP call itself succeeded, but the active `ResponseDecoder` raised. The wrap happens at the seam in `Client.send` / `AsyncClient.send` — `except Exception` translates any decoder-side failure into `DecodeError(response=..., model=..., original=...)` with `raise ... from exc` chaining. The `original` attribute exposes the underlying library exception (e.g., `pydantic.ValidationError`, `msgspec.ValidationError`); `__cause__` carries the same reference.
+
 ## 5. Module layout
 
 Current tree: