chore(release): draft 0.4.0 release notes

Slice 1 of Epic 3: Retry middleware, Finagle-style RetryBudget,
RetryBudgetExhaustedError, and the NetworkError(TransportError)
refinement. Purely additive — no breaking changes from 0.3.0.

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

Author: lesnik512

planning/releases/0.4.0.md

@@ -0,0 +1,97 @@
+# httpware 0.4.0 — Retry middleware + RetryBudget
+
+**0.4.0 is additive. No breaking changes.** Code written against 0.3.0 continues to work unchanged.
+
+This release ships the first slice of Epic 3 (Resilience): a `Retry` middleware with sensible defaults, a Finagle-style `RetryBudget` token bucket that prevents retry storms, and a refinement to the exception tree (`NetworkError`) that lets callers tell transient network failures apart from non-retryable transport failures.
+
+## New features
+
+- **`httpware.Retry`** — middleware that automatically retries transient failures on idempotent methods. Defaults:
+  - `max_attempts=3`, `base_delay=0.1s`, `max_delay=5.0s`, full-jitter exponential backoff (AWS formulation)
+  - Retries on `408`, `429`, `502`, `503`, `504` for `GET / HEAD / OPTIONS / PUT / DELETE` (non-idempotent methods like `POST` and `PATCH` are not retried by default — pass `retry_methods=` to opt in per client)
+  - Retries on `httpware.NetworkError` and `httpware.TimeoutError` for the same method set
+  - Honors `Retry-After` (seconds + HTTP-date forms, capped at `max_delay`); `respect_retry_after=False` disables
+  - Optional `attempt_timeout=` wall-clock cap per attempt via `asyncio.timeout()`
+  - On exhaustion, re-raises the original `StatusError` subclass unwrapped with a PEP 678 `__notes__` entry (`"httpware: gave up after N attempts"`)
+- **`httpware.RetryBudget`** — Finagle-style token bucket bounding retry rate to prevent retry storms when downstream services degrade. Defaults: `ttl=10s`, `min_retries_per_sec=10`, `percent_can_retry=0.2` (match Finagle / AWS SDK / Envoy). Per `Retry`-instance by default; pass an explicit `RetryBudget` to share across multiple `Retry` middlewares (e.g., several `AsyncClient`s hitting the same downstream).
+- **`httpware.RetryBudgetExhaustedError`** — distinct `ClientError` raised when the budget refuses a retry. Carries `last_response: httpx2.Response | None`, `last_exception: BaseException | None`, and `attempts: int`. Picklable across process boundaries.
+- **`httpware.NetworkError(TransportError)`** — refines the `AsyncClient` terminal mapping so transient `httpx2.NetworkError`-family exceptions (`ConnectError`, `ReadError`, `WriteError`, `CloseError`) raise `httpware.NetworkError`. `InvalidURL` and `CookieConflict` continue to raise bare `TransportError`. Pool-acquisition timeouts (`httpx2.PoolTimeout`) continue to raise `httpware.TimeoutError`.
+
+## Backwards compatibility
+
+Subclassing keeps existing catch-blocks working unchanged:
+
+- `except TransportError` still catches all transient + permanent transport-layer failures (`NetworkError` is a subclass).
+- `except ClientError` still catches everything in the httpware exception tree, including the new `RetryBudgetExhaustedError`.
+
+The terminal mapping change only narrows what callers see when they check the *exact* type. Catch-by-isinstance behaves the same.
+
+## Usage
+
+```python
+from httpware import AsyncClient, Retry, RetryBudget
+
+async with AsyncClient(
+    base_url="https://api.example.com",
+    middleware=[Retry()],  # default: 3 attempts, full-jitter backoff, fresh RetryBudget
+) as client:
+    user = await client.get("/users/1", response_model=User)
+```
+
+Share a budget across several clients hitting the same downstream:
+
+```python
+from httpware import AsyncClient, Retry, RetryBudget
+
+shared_budget = RetryBudget()  # one bucket, shared
+
+async with AsyncClient(
+    base_url="https://upstream-a.example.com",
+    middleware=[Retry(budget=shared_budget)],
+) as client_a, AsyncClient(
+    base_url="https://upstream-b.example.com",
+    middleware=[Retry(budget=shared_budget)],
+) as client_b:
+    ...
+```
+
+Catch budget exhaustion specifically:
+
+```python
+from httpware import RetryBudgetExhaustedError
+
+try:
+    response = await client.get("/users/1")
+except RetryBudgetExhaustedError as exc:
+    # Budget refused a retry; the prior failure is preserved.
+    logger.warning(
+        "retry budget exhausted after %d attempts; last status %s",
+        exc.attempts,
+        exc.last_response.status_code if exc.last_response else "n/a",
+    )
+```
+
+Tune for tighter SLAs:
+
+```python
+Retry(
+    max_attempts=5,
+    base_delay=0.05,
+    max_delay=1.0,
+    attempt_timeout=0.5,           # cap each attempt at 500ms wall-clock
+    retry_methods=frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE", "POST"}),
+    budget=RetryBudget(percent_can_retry=0.1),  # tighter cap
+)
+```
+
+## What's still ahead
+
+The rest of Epic 3 — `Bulkhead` (concurrency limiter) and extension-slot documentation — ships in subsequent releases. Epic 5 (observability hooks + OTel middleware) is also unstarted; logging of retry decisions will plumb through then.
+
+Out of scope for this release (per the spec, may revisit on real-user pain): per-call retry override via `extensions`, a `Backoff` protocol abstraction, `retry_on_exception=` configuration, and retrying streamed request bodies (the latter waits for `AsyncClient.stream` in Epic 4).
+
+## References
+
+- Spec: [`planning/specs/2026-06-05-retry-and-retry-budget-design.md`](../specs/2026-06-05-retry-and-retry-budget-design.md)
+- Plan: [`planning/plans/2026-06-05-retry-and-retry-budget-plan.md`](../plans/2026-06-05-retry-and-retry-budget-plan.md)
+- Roadmap: [`planning/engineering.md`](../engineering.md) §8