docs(adr): propose ADR-0030 — AI gateway Responses API support

[ndreno]

Summary

Proposes ADR-0030, extending the AI gateway (ADR-0024) with:

• OpenAI Responses API support alongside Chat Completions. The ai-proxy dispatcher becomes protocol-aware and serves both surfaces against the same target pool. Motivated by clients like codex-cli that use the Responses API, not Chat Completions.
• Caller-owned model principle — the model identifier is part of the client's contract, not the gateway's. The gateway routes, validates, and gates; it does not decide the model.
• Dynamic model routing via a new routes table with glob patterns (claude-* → anthropic, gpt-* → openai), optional allow / deny lists for static catalog policy, and the existing cel middleware for dynamic consumer policy.
• /v1/models served by the ai-proxy dispatcher itself when bound to the route — no native data plane carve-out, stays inside Barbacane's spec-driven routing model. Shipped via an importable OpenAPI fragment so operators don't duplicate config across three operations.
• Pragmatic store UX — accept store: true (most clients send it as an unexamined default), emit Warning: 299 header + store_downgrade_total metric, reject only the genuinely stateful features (previous_response_id).

Breaking change

The model field is removed from targets.<name> and from the flat top-level config. Migration for existing ADR-0024 deployments: delete the field from each target. Justified by the pre-1.0 status and the codebase convention of avoiding backward-compat shims at this stage.

Out of scope (deferred)

• Stateful Responses API (previous_response_id, GET /v1/responses/{id}, cancel) — requires a session-scoped storage capability in the WASM runtime; separate ADR.
• True SSE translation against Anthropic — inherits the deferral from ADR-0024.
• Ollama Responses API support — Ollama's OpenAI-compat surface is Chat Completions only as of 2026-04.

Context

This ADR originated from a conversation with @marmeladema, who built a stateful OpenAI Responses ↔ Anthropic translation proxy for running codex-cli against Claude — a harder problem than what Barbacane's ai-proxy does today, precisely because it preserves conversation state across turns (previous_response_id, tool-use chains, etc.). That discussion surfaced two gaps on Barbacane's side:

1. Clients-send-OpenAI-Chat-Completions is a narrower assumption than "OpenAI-compatible" — the Responses API is a distinct protocol with a cleaner mapping to Anthropic Messages (item-based vs. message-based).
2. Pinning model identifiers in gateway config is operational friction and conflates routing intent with catalog policy.

This ADR addresses the stateless slice of what @marmeladema's proxy does — which covers the 80% use case (clients that send store: true as an unexamined default but never actually chain responses) without requiring a new session-scoped storage primitive in the WASM runtime. The fully stateful slice (previous_response_id continuation, response retrieval/cancel) is deferred to a phase 2 ADR that will introduce that primitive; @marmeladema's existing work is likely directly reusable there.

Test plan

• Review the decisions in section 0 (principle) and section 2 (Responses translation, store UX) for alignment with @marmeladema's implementation, especially the stateless boundary
• Confirm the spec fragment / import mechanism proposed in section 4 is compatible with the compiler's current capabilities (or scope the addition)
• Once accepted: implementation PRs per section (1 → 2 → 3 → 4), contract tests added per provider × protocol matrix