feature: abstract the API layer for multiple front-end protocols

Summary

Define a protocol-neutral routing engine so the routed data plane can support adapters beyond Envoy External Processing (ExtProc) without duplicating policy or weakening existing behavior.

Audited current-main baseline (2026-07-15)

• Routed chat/completions traffic is processed through the Envoy ExtProc gRPC service in src/semantic-router/pkg/extproc/.
• src/semantic-router/pkg/apiserver/ exposes direct HTTP management, classification, memory, vector-store, and Router Learning outcome APIs. It is not a drop-in direct HTTP proxy for the routed chat data plane.
• ExtProc already contains request-shape handling for OpenAI-compatible chat, the Responses API, and Anthropic translation. Those paths are protocol handling inside the ExtProc adapter, not independent front-end servers.
• The repository does not contain config/envoy.yaml. Envoy configuration is generated or maintained under deployment/operator and CLI surfaces.
• PII classification is part of the classification/config model surfaces; there is no current pkg/pii package.

Scope

1. Specify a typed, protocol-neutral request/response context for the routing stages that are genuinely shared.
2. Extract only stable policy seams from ExtProc; keep transport mutation, streaming, early responses, and Envoy-specific behavior in the ExtProc adapter.
3. Preserve ExtProc as a first-class, backward-compatible adapter.
4. Evaluate a direct OpenAI-compatible HTTP data-plane adapter as the first additional adapter.
5. Define cancellation, streaming, body limits, header trust, identity, error mapping, and observability consistently across adapters.
6. Reuse the same active config/runtime registry and model lifecycle instead of creating a second router instance or config source.

Non-goals

• Do not treat the existing management/classification API server as an already-complete routed HTTP proxy.
• Do not build a custom Nginx module in the first slice; Nginx can consume a documented HTTP adapter when one exists.
• Do not duplicate routing policy or allow adapter-specific security bypasses.
• Do not change the supported local serve flow defined by the repository harness.

Acceptance criteria

• Shared routing input/output contracts have no Envoy protobuf dependency.
• ExtProc behavior remains compatible and covered by existing E2E tests.
• One additional adapter demonstrates parity for routing decision, streaming/cancellation, identity, limits, errors, and diagnostics.
• Adapter-specific capabilities and unsupported behavior are explicit.
• No adapter creates a second mutable config/runtime source.
• Performance comparison reports adapter overhead without claiming zero cost.

Likely change surfaces

src/semantic-router/pkg/extproc/, a new narrowly scoped adapter package, src/semantic-router/pkg/apiserver/ only where management primitives are reused, src/semantic-router/pkg/routerruntime/, src/vllm-sr/cli/config_generator.py, deployment templates, docs, and E2E tests.

Validation entrypoint

Start with:

make agent-report ENV=cpu CHANGED_FILES="<space-separated changed files>"

Then run the reported gates and affected E2E profiles. Behavior-visible protocol/startup/API changes require E2E coverage.