feat: bridge existing retention directives to backend KV-cache adapters

Motivation

Current main already defines and emits provider-neutral retention intent. The remaining work is to negotiate and implement backend-specific adapters without claiming stronger guarantees than a backend actually supports.

Audited upstream baseline (2026-07-15)

config.RetentionDirective already includes:

• drop;
• ttl_turns;
• keep_current_model;
• prefer_prefix_retention.

The runtime consumes the first three for router-side retention behavior and emits the prefix-retention preference as downstream metadata. The missing piece is verified backend KV-cache retention/eviction behavior and acknowledgement.

The relevant vLLM work is still an open design RFC, not a stable API that this repository can assume: https://github.com/vllm-project/vllm/issues/37003

Scope

1. Document the existing directive semantics, precedence, and exact router-side guarantees.
2. Define a versioned capability-negotiation and acknowledgement contract for backends/gateways.
3. Implement adapters only for demonstrated, version-pinned backend capabilities.
4. For unsupported backends, emit an explicit no-op/unsupported result; never report retention as enforced.
5. Record requested directive, translated adapter action, backend acknowledgement, expiry/eviction observation, and reason in bounded telemetry/Router Replay.
6. Prototype vLLM integration behind an experimental/version gate until an upstream supported capability exists.
7. Test lifecycle, retries, model switch, prefix identity, cancellation, backend restart, and partial rollout.

Boundaries

• This is not a new semantic model-selection or capacity policy.
• A preference is not a guarantee without backend acknowledgement.
• Cache identifiers and prefix metadata must not expose prompt contents or cross tenant boundaries.
• Unsupported or ambiguous backend behavior must fail to a documented no-op or conservative policy.
• Do not vendor an unstable vLLM internal API as a permanent public contract.

Acceptance criteria

• Existing router-side directive behavior is covered by contract tests.
• Backend capability/version is negotiated and visible.
• Requested, translated, acknowledged, and observed states are distinguishable.
• No-op behavior is explicit for unsupported versions/providers.
• Tenant isolation, prefix identity, TTL, model switch, and eviction semantics are tested.
• Experimental adapters are version-pinned and removable.
• Maintained examples/docs do not promise upstream support that is still only an RFC.

Likely change surfaces

src/semantic-router/pkg/config/, src/semantic-router/pkg/extproc/, src/semantic-router/pkg/routerreplay/, Envoy/GIE/provider adapters, deployment manifests, docs, and E2E tests.

Related: #2018, #2332, #2349, #2546.