research: route on typed failure experience from Router Replay

Terminology and current baseline (audited 2026-07-15)

Router Memory (src/semantic-router/pkg/memory/) is prompt-visible user/conversation memory. It is not the routing failure-experience store and must not be repurposed as one.

Router Replay captures routing decisions and, depending on configuration, can retain request/response/tool content as well as signals, usage/cost, and later learning outcomes. pkg/routerruntime exposes the typed learning-outcome seam. Current main does not expose a normalized, versioned failure taxonomy that Router Learning can safely aggregate by model/domain/tool.

Scope

1. Define a versioned failure taxonomy, initially including only reliably observable classes such as provider/transport failure, timeout, invalid output contract, safety refusal, verified tool failure, and explicit evaluator outcome.
2. Preserve provenance and uncertainty; never infer a semantic failure from latency or a retry alone.
3. Build an asynchronous, idempotent materializer from Replay/outcome events into a separate content-minimized derived projection.
4. Produce decayed, minimum-sample, uncertainty-aware aggregates keyed only by reviewed dimensions.
5. Expose aggregates to offline evaluation first; allow Router Learning consumption only behind shadow/canary gates and protection.
6. Define correction semantics for delayed or revised outcomes.

Boundaries

• Failure evidence cannot override authorization, hard safety constraints, or the validated candidate set.
• No synchronous experience-store read/write is required on the hot path.
• The derived failure projection omits raw prompts, responses, and tool arguments by default. This does not redefine Router Replay retention; Replay content capture remains separately configured and governed.
• Provider failures, model-quality failures, policy refusals, and tool-execution failures remain distinguishable.

Acceptance criteria

• Failure schema and provenance rules are versioned and documented.
• Ambiguous observations remain unknown rather than being forced into a class.
• Materialization handles delayed/corrected outcomes and duplicate events.
• Sparse/cold-start data cannot cause confident routing changes.
• Replay evaluation and shadow metrics precede live use.
• Applied Router Learning effects have bounded reasons and rollback.
• Privacy, retention, multi-replica, and restart semantics are tested.

Relevant surfaces

src/semantic-router/pkg/routerreplay/, src/semantic-router/pkg/routerruntime/, src/semantic-router/pkg/extproc/, src/semantic-router/pkg/config/, observability, CLI diagnostics, docs, and tests.

Related: #2238, #2243, #2542, #2545.