docs(release): draft 0.8.1 notes (DecodeError)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lesnik512

planning/releases/0.8.1.md

@@ -0,0 +1,64 @@
+# httpware 0.8.1 — `DecodeError` closes the decoder-exception gap
+
+**Patch release with one behavior change.** Code that catches `httpware.ClientError` (the advertised catch-all) now actually catches every failure mode of `response_model=` decoding. Code that catches `pydantic.ValidationError` or `msgspec.*` *directly* downstream of `client.send(..., response_model=...)` will no longer match — those exceptions are now wrapped.
+
+## The gap
+
+Before 0.8.1, when `response_model=` was set, `Client.send` and `AsyncClient.send` invoked the active `ResponseDecoder` without a translation step. Whatever the decoder raised — `pydantic.ValidationError` (schema mismatch or malformed JSON via `TypeAdapter.validate_json`), `msgspec.ValidationError`, `msgspec.DecodeError`, or anything else — escaped untranslated. `except httpware.ClientError` did not catch it. Consumers either had to import the decoder library at the call site or skip the decoder entirely and decode the raw `httpx2.Response` by hand.
+
+## The fix
+
+New `httpware.DecodeError(ClientError)` — direct child of `ClientError`, sibling of `StatusError` / `TransportError` / `RetryBudgetExhaustedError` / `BulkheadFullError`. Both `Client.send` and `AsyncClient.send` now wrap the decoder call:
+
+```python
+try:
+    return self._decoder.decode(response.content, response_model)
+except Exception as exc:
+    raise DecodeError(response=response, model=response_model, original=exc) from exc
+```
+
+The middleware/`_dispatch` call stays outside the try — transport and status errors are unaffected. Decoder implementers do not need to import or raise `DecodeError`; the seam translates whatever they raise.
+
+Fields on `DecodeError`:
+
+- `response: httpx2.Response` — the response whose body failed to decode (status, headers, request URL all available).
+- `model: type` — the type that was passed as `response_model=`.
+- `original: BaseException` — the underlying library exception. Also available via `__cause__`.
+
+```python
+from httpware import AsyncClient, ClientError, 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
+except ClientError:
+    raise
+```
+
+## Migration
+
+If you catch `pydantic.ValidationError` or `msgspec.*` directly downstream of `client.send(..., response_model=...)`, switch to `except httpware.DecodeError` (or the broader `except httpware.ClientError`). The previously-leaking exceptions weren't a documented contract, so there's no deprecation pass. The fix is the fix.
+
+If you already catch `httpware.ClientError`, nothing changes — your handler now also covers the decode-failure path it should have covered all along.
+
+## Touched surface
+
+- `httpware.DecodeError` — new public class, re-exported from the top level.
+- `Client.send` / `AsyncClient.send` — both wrap the decoder call (one `try/except` each).
+- `ResponseDecoder.decode` — protocol signature unchanged; docstring grows one sentence documenting the seam wrap.
+- `PydanticDecoder` and `MsgspecDecoder` — unchanged.
+- Docs: `docs/errors.md` (hierarchy + new section), `planning/engineering.md` (Seam B contract + §4 paragraph), `README.md` (one-line note on the `response_model=` paragraph).
+
+## See also
+
+- [`planning/specs/2026-06-07-decoder-error-design.md`](../specs/2026-06-07-decoder-error-design.md) — design rationale.
+- [`planning/plans/2026-06-07-decoder-error-plan.md`](../plans/2026-06-07-decoder-error-plan.md) — implementation plan.
+- PR [#32](https://github.com/modern-python/httpware/pull/32).