Ranked

Ranked strategies make a routing decision a first-class ordered slate instead of a single winner. A slate carries the selected candidate and the ranked alternates behind it, plus anyone eliminated, pending, or failed — so downstream retries and fallbacks consume the next entry rather than re-running selection.

Ranked selection is supported through the RankedStrategy capability and its SelectRanked method. The durable RouteSlate is recorded on the decision, and the ranked_slate_fallback recipe provides ordered alternates.

Ranked routing slate

Output: ranked-slate · Modes: single, ranked, multi_winner, broadcast

A durable, ordered list of outcomes for one routable: selected, ranked alternates, eliminated, pending, and failed entries. It powers ordered fallback, top-k marketplaces, waterfall posting, and quorum — anywhere a decision is naturally a ranking rather than a pick.

Why it matters. A single slate expresses many routing shapes at once. In single mode it degrades to one winner; in ranked mode it's an ordered fallback list; in multi_winner mode several entries are marked selected; in broadcast mode every viable entry is a recipient. Capacity retries and waterfall posting consume the slate top-down instead of re-selecting.

How it's shaped. A strategy produces a RankedSlate through the RankedStrategy.SelectRanked capability (advertised as ranked_select, plus multi_winner when several entries are selected). ValidateRankedSlate (pkg/strategy/ranked_slate.go) enforces positive, ascending, unique ranks, that every entry references a request candidate, and that SelectedCount matches the selected entries. The durable form recorded on the decision is RouteSlate (domain/routing/route_slate.go) — a Mode, ordered RouteSlateEntry list, each with a Rank and an Outcome (selected / alternate / eliminated / pending / failed).

Where it fits. The Select stage returns a slate in SelectResponse.Slate while Selected stays populated for single-winner compatibility; the finalizer persists it as Decision.Slate.

Top-K adapter

Output: ranked-slate

Wraps any explainable single-winner strategy into a ranked slate. If a scorer emits complete, deterministic explain scores for every candidate, TopKFromExplanation (pkg/strategy/ranked_slate.go) turns that scoring into a top-k ordered slate — so existing scoring strategies produce trustworthy ordered alternates without being rewritten. The companion SingleSelectionSlate degrades a plain single winner into a one-entry slate.

Why it matters. You've already tuned multi_objective_score or yield_optimized; you shouldn't have to reimplement them to get ranked fallbacks. The adapter reuses their explain output as the ranking, so ordering is exactly consistent with the scores that chose the winner.

How it works. It requires the wrapped strategy to advertise explain and emit a complete, deterministic per-candidate breakdown; it then sorts by score into a validated RankedSlate. It fails if explain scores are unavailable or a candidate is missing a score, because a partial ordering wouldn't be trustworthy.

Where it fits. A wrapper in the Select stage that upgrades a single-winner scorer to ranked_select. The ranked_slate_fallback recipe packages this pattern for authoring.

Related