# Ranked (/docs/strategies/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.

| Strategy                                      | Output       | Status    |
| --------------------------------------------- | ------------ | --------- |
| [Ranked routing slate](#ranked-routing-slate) | ranked-slate | Available |
| [Top-K adapter](#top-k-adapter)               | ranked-slate | Available |

<Callout title="Why a slate beats a single winner" type="info">
  When a chosen recipient rejects, times out, or hits a capacity wall, a
  single-winner strategy has to run selection again from scratch. A ranked slate
  already knows the ordered alternates, so a capacity retry just advances to the
  next entry — cheaper, deterministic, and replayable.
</Callout>

## Ranked routing slate [#ranked-routing-slate]

**Output:** ranked-slate · &#x2A;*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 [#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](/docs/strategies/scoring)
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 [#related]

<Cards>
  <Card title="Scoring strategies" href="/docs/strategies/scoring">
    The explainable scorers the Top-K adapter wraps into slates.
  </Card>

  <Card title="Markets" href="/docs/strategies/markets">
    Multi-winner clearing emits ranked slates of buyers.
  </Card>

  <Card title="Allocation" href="/docs/strategies/allocation">
    Batch plans that rank assignments across many items at once.
  </Card>
</Cards>