[ISSUE #8256] Add opt-in evaluation sample export and feedback correlation - #8412

Fixes #8256.

Problem

An operator who wants to evaluate an LLM workload routed through the gateway has no sanctioned way to obtain evaluation data: the body-free observation contracts carry the facts, but nothing turns them into versioned samples an offline runner can consume, and nothing lets a judge's score rejoin the request it belongs to without trusting a client-supplied request id. Anything naive here is dangerous — collecting request content implicitly, extending a response's lifetime, or keeping unbounded join state — so this first delivery of #8256 is deliberately narrow: metadata-only samples, two independent opt-in layers, a bounded asynchronous exporter that cannot touch the request path, and feedback joins authorized through gateway-minted opaque references.

Approach

Both layers must opt in: the gateway-wide shenyu.plugins.ai.evaluation.enabled property and a per-selector evaluation block on the route handle (enabled, sampleRate, includeIdentity). With either layer off, the gateway holds no evaluation state and behaves byte-identically to today; the manager and exporter beans only exist when the feature is on. Sampling uses a deterministic 100-slot probability gate scoped to this pipeline — the logging family's count-sampler mechanism, not a second telemetry transport.

The exported sample (eval-sample-v1) is body-free metadata by construction: opaque gateway-minted sampleId, request/selector/rule ids, the configuration generation, terminal outcome, status, duration, attempt count and the provider-reported usage figures with their quality status — unknown figures are exported as null, never as zero or an invented value, and there are no prompt/model/policy version slots yet because no gateway source for them exists (they land with the #8051 integration). Trusted identity fields enter a sample only when the route allow-listed includeIdentity; the recorded tenant always stays inside the bounded join registry for authorization but is exported only when allow-listed.

Export is O(1) on the request path — a cached route lookup, a sampler check and a bounded-queue offer whose overflow drops and counts instead of blocking — and a dedicated daemon thread drains batches into a sink. The default sink writes one structured line per record for an operator-owned offline runner; an application-owned sink replaces it via @ConditionalOnMissingBean, and the exporter survives a failing sink by dropping the batch rather than dying. No exchange or request object is ever retained, no additional upstream or model call is made, and all retained state is bounded by the queue capacity.

Feedback joins (eval-feedback-v1) authorize through the opaque sample reference plus the tenant the gateway recorded — a request id is never an authority. Unknown, forged or expired references are rejected as UNKNOWN_SAMPLE without creating state; a tenant mismatch as TENANT_MISMATCH; malformed label sets as REJECTED_INVALID. A repeated judgeId updates its labels idempotently, distinct judges append up to the bounded per-sample budget, and accepted joins are exported through the same pipeline. The join registry is capacity-bounded and its entries expire with the configured retention, so "expired" versus "forged" versus "unauthorized" stays a distinct, documented outcome.

Testing

All tests are deterministic and sleep-free; the exporter is driven through its package-private single-batch drain so nothing waits on the worker thread. They cover the double opt-in chain (gateway off, route off, zero rate), the metadata-only contract with identity allow-listing, unknown usage staying unknown, the full join vocabulary (accepted with feedback export, idempotent judge update, per-sample bound, forged reference, tenant mismatch, malformed labels, expiry), a broken sampler configuration never throwing out of the observation, bounded admission with drop counting, batched draining, a failing sink not breaking the drain, and close-flush. The starter's optional-bean wiring keeps its existing tests green.

shenyu-common 663 tests, shenyu-plugin-ai-common 40, shenyu-plugin-ai-proxy 477 (16 new), shenyu-spring-boot-starter-plugin-ai-proxy 18 — all green; Checkstyle clean on all four modules. The contract tables, authorization semantics and follow-ups (content capture behind an independent allow-list, ES/Kafka sinks, #8051/#8052 version references) are documented in shenyu-plugin-ai/AI_EVALUATION_SAMPLES.md.