docs(http): resolve OQ-40 reqwest client config — ClientWithMiddleware + retry/retry-after middleware stack

OQ-40 resolved: alknet-http owns a shared reqwest_middleware::ClientWithMiddleware
(not a bare reqwest::Client) with a two-layer middleware stack —
RetryTransientMiddleware (reqwest-retry, exponential backoff on transient
failures) + inlined RetryAfterMiddleware (from melotic/reqwest-retry-after, MIT,
~50 lines, inlined to bound the upstream's unbounded HashMap storage). The two
are complementary: reqwest-retry's default strategy does not honor Retry-After.

Hot-reload is rebuild-and-swap via ArcSwap (same pattern as
ConfigIdentityProvider, ADR-035); a rebuild drops the connection pool, which
is acceptable since a config change wanting a fresh pool is the trigger. The
three one-way constraints stand unchanged: alknet-http owns its client (no
env-var config, no shared global), credentials inject per-request from
OperationContext.capabilities, outbound TLS uses the system trust store.

Records the downstream layering boundary: the agent crate's provider SSE
normalization (the solid part of aisdk's pattern — Vercel-UI-message
normalization) sits on top of this client, consuming the reqwest::Response
stream; it does not replace the client. The aisdk core/client.rs reference for
client construction is dropped (env-var config + hand-rolled retry are the
anti-patterns discarded); the from_openapi.ts SSE normalization reference in
the forwarding-handler section is kept (separate, solid pattern).

No ADR — the decision is internal to alknet-http: the client type does not
cross crate boundaries (alknet-call never sees reqwest), the library choice is
reversible, and it does not touch the system's structure, constraints, or
cross-crate API surface.

Updates: http-adapters.md (HTTP client section rewritten, references updated,
constraints/OQ bullets updated), http-mcp.md (OQ-40 status flip), open-
questions.md (OQ-40 resolved with full config-shape table), README.md (OQ-40
folded into the existing two-way-doors bucket), and three secondary docs
(crates/http/README.md, overview.md, http-server.md) that carried stale 'open'
OQ-40 references.

docs/architecture/crates/http/http-adapters.md

@@ -1,6 +1,6 @@
 ---
 status: draft
-last_updated: 2026-06-29
+last_updated: 2026-06-30
 ---
 
 # HTTP Adapters — from_openapi and to_openapi
@@ -130,7 +130,7 @@ The forwarding handler is the `Arc<dyn Handler>` stored in the
    - Headers: `Content-Type: application/json` + the auth header built
      from `context.capabilities` (see No-Env-Vars below).
    - Body: the `body` field of the input (for `Mutation`/`Subscription`).
-3. Sends the request via the shared `reqwest::Client` (see HTTP Client
+3. Sends the request via the shared HTTP client (see HTTP Client
    below).
 4. For a `Query`/`Mutation`: parses the response body (JSON, text, or
    binary — same content-type branching as the TS `createHTTPOperation`),
@@ -146,22 +146,69 @@ the registry dispatches. `alknet-call` never sees `reqwest`.
 
 ### HTTP client (reqwest)
 
-`alknet-http` maintains a shared `reqwest::Client` (constructed once,
-reused across all `from_openapi`/`from_mcp` forwarding handlers). The
-client handles connection pooling, keep-alive, and TLS. The aisdk
-`core/client.rs` reference shows the pattern worth referencing: a shared
-client with `OnceLock<reqwest::Client>`, retry logic (exponential
-backoff, `Retry-After` header), and separate streaming vs non-streaming
-clients. `alknet-http` owns its HTTP client; it does not inherit aisdk's.
+`alknet-http` maintains a shared HTTP client, constructed once and reused
+across all `from_openapi`/`from_mcp` forwarding handlers. The client owns
+connection pooling, keep-alive, TLS, and a retry stack. The shared type is
+`reqwest_middleware::ClientWithMiddleware`, not a bare `reqwest::Client` —
+both retry and Retry-After are middleware on the stack, and middleware
+requires the `ClientWithMiddleware` wrapper.
 
-The retry/pooling config comes from `StaticConfig` or `DynamicConfig`
-(hot-reloadable). The credential injection happens per-request (from
-`OperationContext.capabilities`), not at client construction — the
-client is shared across all operations, the credentials are per-call.
+The middleware stack has two layers:
 
-The exact pooling/retry config is a two-way-door implementation detail
-(OQ-40); the one-way constraint is that `alknet-http` owns its `reqwest`
-client (no env-var-based client config, no shared global client).
+1. **`RetryTransientMiddleware`** (from `reqwest-retry`) — exponential
+   backoff on transient failures (connection errors, 5xx). The "retry N
+   times with increasing intervals" part. Configured via an
+   `ExponentialBackoff` policy at client construction.
+2. **Inlined `RetryAfterMiddleware`** — parses the `Retry-After` header
+   on 429/503 and sleeps before the next request to that URL. The
+   "respect what the server told you" part. Inlined (MIT, ~50 lines of
+   real logic) from `melotic/reqwest-retry-after`, not pulled as a
+   dependency: the crate is complementary to `reqwest-retry` (whose
+   default strategy does not honor `Retry-After`), and inlining lets
+   the upstream's unbounded `HashMap<Url, SystemTime>` storage be
+   bounded for a long-running process.
+
+Pooling, keep-alive, and TLS come from `reqwest::ClientBuilder` defaults;
+outbound TLS uses the system trust store (standard HTTPS to external APIs
+like OpenAI, Anthropic). Custom CA bundle + client certs are an optional
+config for self-hosted API gateways (two-way-door implementation detail;
+the credential comes from `Capabilities`, the TLS trust comes from the
+system).
+
+Credential injection happens per-request (from
+`OperationContext.capabilities`), not at client construction — the client
+is shared across all operations, the credentials are per-call.
+
+Hot-reload of the pooling/retry config is **rebuild-and-swap**: a config
+change rebuilds the `ClientWithMiddleware` and swaps it via `ArcSwap`
+(the same pattern `ConfigIdentityProvider` uses, ADR-035). A rebuild
+drops the connection pool / keep-alive state, which is acceptable — a
+config change wanting a fresh pool is the case that triggers it. The
+retry policy is baked into the middleware at `ClientBuilder::build()`
+time; live policy mutation is not supported by `reqwest-retry`, so cheap
+per-policy updates are not part of the model.
+
+The exact pooling/retry config (pool size, retry count, timeout
+defaults, hot-reloadability via `DynamicConfig`) is a two-way-door
+implementation detail (OQ-40, now resolved); the one-way constraint is
+that `alknet-http` owns its HTTP client (no env-var-based client config,
+no shared global client).
+
+**Downstream layering boundary.** The agent crate's provider SSE
+normalization (replicating the solid part of aisdk's pattern — the
+Vercel-UI-message normalization that maps different providers' SSE to a
+common shape) sits on top of this `ClientWithMiddleware`: it consumes the
+`reqwest::Response` stream the forwarding handler produces and emits
+`call.responded` events. It does not replace the client or own
+transport/pooling/retry. `alknet-http` owns transport; the agent crate
+owns provider-specific SSE → Vercel-UI-message mapping. The aisdk
+`core/client.rs` reference for HTTP client construction is *not* carried
+forward — its env-var config and hand-rolled retry are the anti-patterns
+discarded in favor of the middleware stack above. The
+`@alkdev/operations/src/from_openapi.ts` SSE *normalization* pattern is
+separate and stays referenced in the Forwarding Handler section above
+(the `parseSSEFrames`, `createHTTPOperation`, content-type branching
+patterns).
 
 ### No-Env-Vars credential injection
 
@@ -332,9 +379,12 @@ once published, the 5-endpoint gateway shape is one-way.
   generated spec's versioning (tied to the registry's `External`
   operation set version) must be emitted so consumers can detect mapping
   changes (ADR-017 Consequences, OQ-39).
-- **`alknet-http` owns its `reqwest::Client`.** Shared across all
-  forwarding handlers, constructed once. No env-var-based client config.
-  Pooling/retry config is a two-way door (OQ-40).
+- **`alknet-http` owns its HTTP client.** Shared across all forwarding
+  handlers, constructed once. The shared type is
+  `reqwest_middleware::ClientWithMiddleware` (middleware stack:
+  `RetryTransientMiddleware` + inlined `RetryAfterMiddleware`). No
+  env-var-based client config. Pooling/retry config is a two-way door,
+  resolved in OQ-40.
 - **TLS for outbound calls uses the system trust store by default.**
   Standard HTTPS to external APIs (OpenAI, Anthropic). Custom CA bundle
   + client certs are an optional config for self-hosted API gateways.
@@ -363,9 +413,10 @@ See [open-questions.md](../../open-questions.md) for full details.
   versioning strategy for generated OpenAPI specs (tied to the
   registry's `External` operation set version). One-way after first
   publication.
-- **OQ-40** (open): reqwest client config and connection pooling —
-  two-way-door: the exact pooling/retry config shape, hot-reloadable
-  via `DynamicConfig`.
+- **OQ-40** (resolved): reqwest client config and connection pooling —
+  `ClientWithMiddleware` + `RetryTransientMiddleware` + inlined
+  `RetryAfterMiddleware`; rebuild-and-swap hot-reload; per-request
+  credential injection. Two-way-door config shape, now resolved.
 
 ## References
 
@@ -379,6 +430,11 @@ See [open-questions.md](../../open-questions.md) for full details.
   `OperationAdapter` trait, `AdapterError` variants (OQ-26), no-env-vars
   invariant
 - `/workspace/@alkdev/operations/src/from_openapi.ts` — TypeScript prior
-  art (parsing, SSE, auth headers, `createHTTPOperation`)
-- `/workspace/aisdk/src/core/client.rs` — HTTP client reference (pooling,
-  retry, streaming vs non-streaming)
+  art (parsing, SSE, auth headers, `createHTTPOperation`,
+  `parseSSEFrames` — the SSE normalization patterns, not the client
+  construction)
+- `reqwest-retry` crate (https://docs.rs/reqwest-retry/) —
+  `RetryTransientMiddleware` / `ExponentialBackoff` retry policy
+- `melotic/reqwest-retry-after`
+  (https://github.com/melotic/reqwest-retry-after) — `RetryAfterMiddleware`
+  source (MIT, inlined, not a dependency)