feat: enable guarded ranked matcher role

multiplayer-next.md

@@ -46,10 +46,11 @@ product policy are in [`docs/MATCHMAKING.md`](docs/MATCHMAKING.md).
   snapshot and removal with durable-source repair on partial/malformed cache
   state; proposal/result transactions and live Redis restart/failover gates
   remain. The matcher package now performs bounded candidate formation and
-  delegates the final proposal claim to the durable transaction boundary;
+  delegates the final proposal claim to the durable transaction boundary; the
-  queue tickets now also retain server-derived probe RTT metadata for
+  runnable matcher supports casual and explicitly enabled ranked six-player
-  authoritative matcher reads; ranked metadata/provider wiring and live
+  polling with durable Steam identity metadata lookup. Queue tickets now also
-  Redis repair remain. The authenticated probe API now records validated
+  retain server-derived probe RTT metadata for authoritative matcher reads;
+  ranked arena selection and live Redis repair remain. The authenticated probe API now records validated
   server-computed RTT values into the active player's durable queue ticket and
   fails closed when that write is unavailable; Steam/coordinator evidence
   acquisition and multi-region probe population remain.
@@ -71,8 +72,8 @@ product policy are in [`docs/MATCHMAKING.md`](docs/MATCHMAKING.md).
   a runnable casual `cmd/matcher` role now polls PostgreSQL and delegates
   proposal claims to the durable transaction; `cmd/maintenance` now runs
   bounded ranked-season rollover batches with signal-bound shutdown;
-  provider-backed allocation, ranked provider wiring, Redis worker wiring and
+  provider-backed allocation, allocator runtime wiring, Redis failover and live
-  live service checks remain.
+  service checks remain.
 - [ ] **IN PROGRESS:** Define assignment compatibility and opt-in `ServerConfig`
   flags whose defaults reproduce the community-server path. Allocation manifest
   validation now covers client build and future expiry; allocated servers now

multiplayer-todo.md

@@ -1194,7 +1194,7 @@ the local/CI/community transport, not a silent production fallback.
 |---|---|---|
 | 8.14 `[D:8.4,8.5,8.8]` | **IN PROGRESS.** Pure Go queue domain enforces one active ticket per verified player under concurrent mutation, 10 s heartbeat/30 s expiry, retry-safe create/heartbeat/cancel, owner-only recovery reads and deterministic candidate projection; store layer adds a rebuildable candidate-cache boundary and authenticated HTTP queue adapter with playlist/build/protocol compatibility metadata | `server/domain/queue.go`, `server/store/candidates.go`, `server/store/queue_sql.go`, `server/store/redis_candidates.go` and `server/api/service.go` cover ownership/expiry/idempotency, concurrent create fencing, candidate/player ownership binding, owner/revision-scoped SQL heartbeat/cancel/recovery, injectable PostgreSQL queue backend selected by the HTTP service, authoritative queue-to-cache rebuild, expired recovery as a terminal error, owner-scoped SQL recovery with authoritative expiry handling, server-owned candidate resolution, strict compatibility metadata, TTL-bound Redis upsert/remove/snapshot, API create/heartbeat/cancel projection hooks, optional control-plane Redis configuration and atomic durable-source repair on partial/malformed cache state; opt-in real PostgreSQL execution now covers create/replay/active-player fencing, owner recovery, revision-fenced heartbeat/cancel and expiry, while miniredis covers Redis behavior and repair-source failure; live Redis restart/failover and worker integration remain |
 | 8.15 `[D:7.8,8.3]` | **IN PROGRESS.** Pure Go probe validation treats Steam location as opaque, requires nonce/freshness/region and server-computed RTT, and implements discrepancy quarantine/release; authenticated HTTP now accepts only opaque location/nonce input through a server-owned probe provider and records validated RTT into the active player's durable queue ticket; durable queue projections have a server-derived RTT JSON field for matcher reads | `server/domain/probes.go`, `server/migrations/0003_queue_probe_metadata.sql`, adversarial fixtures and `server/api/service.go`/`store/queue_sql.go` cover stale/wrong/forged evidence, the 25 ms/30% threshold, three-sample quarantine, five-clean release, authenticated provider arguments, rejection of client RTT fields, player/ticket/expiry binding, persistence failure, playlist-scoped candidate reads and bounded metadata decoding; Steam coordinator, regional probe adapters and multi-region probe population remain |
-| 8.16 `[D:8.14,8.15]` | **IN PROGRESS.** Pure Go candidate/team selection implements the <=100 ms ceiling, pairwise widening tolerance, anchor inclusion, deterministic set/region scoring and balanced team partitioning; queue-backed formation now consumes the server-owned projection, fences duplicate player identities and rejects playlist/build/protocol mixing; the matcher worker performs bounded formation and delegates the final claim to the durable proposal transaction | `server/domain/matcher.go`, `teams.go`, `server/matcher/worker.go` and adversarial fixtures cover no-common-region, tolerance boundaries, lexical ties, mean-rating balance, malformed candidates, duplicate identities, compatibility mismatches, incomplete batches, source failure, durable claim failure and queue-backed oldest-anchor formation; ranked provider and long-running worker integration remain |
+| 8.16 `[D:8.14,8.15]` | **IN PROGRESS.** Pure Go candidate/team selection implements the <=100 ms ceiling, pairwise widening tolerance, anchor inclusion, deterministic set/region scoring and balanced team partitioning; queue-backed formation now consumes the server-owned projection, fences duplicate player identities and rejects playlist/build/protocol mixing; the matcher worker performs bounded formation and delegates the final claim to the durable proposal transaction; the runnable matcher now supports explicitly enabled ranked six-player polling with durable verified-Steam identity lookup | `server/domain/matcher.go`, `teams.go`, `server/matcher/worker.go`, `server/store/queue_sql.go` and adversarial fixtures cover no-common-region, tolerance boundaries, lexical ties, mean-rating balance, malformed candidates, duplicate identities, compatibility mismatches, incomplete batches, source failure, durable claim failure, queue-backed oldest-anchor formation and incomplete ranked identity metadata; arena selection and long-running worker integration remain |
 | 8.17 `[D:8.14,8.16]` | **IN PROGRESS.** Pure Go proposal policy sends a 10-second response window to every selected human, requires unanimous acceptance, applies exact decline/timeout cooldowns and ranked escalation; authenticated API exposes revisioned accept/decline mutations; formed matches now pass through a playlist-aware proposal boundary | `server/domain/proposal.go`, `formation.go` and `server/api/service.go` plus adversarial fixtures cover partial/unanimous response, expiry, replay/conflict, stale API revision, casual lineup preparation and ranked metadata validation; queue precedence and allocation integration remain |
 | 8.18 `[D:8.5,8.14,8.17]` | **IN PROGRESS.** Go store layer defines PostgreSQL SERIALIZABLE whole-transaction retries and queue candidate/proposal claim SQL using `FOR UPDATE SKIP LOCKED` plus durable uniqueness/revision fences; proposal creation now inserts proposal/participants and promotes every ticket in one rollback-safe transaction with player- and playlist-bound claim predicates, queue creation has a durable idempotency/owner-read adapter, participant-scoped proposal recovery now expires OPEN proposals and pending participants transactionally at read time, and proposal accept/decline now uses participant/proposal locks, revision fencing and durable idempotency; response attempts also advance expired proposals and pending participants before returning closed; runnable casual matcher polling now supports an optional Redis candidate projection that repairs empty/lost cache state from authoritative PostgreSQL before the durable final claim | `server/store/serializable.go`, `queue_sql.go`, `proposal_sql.go`, `proposal_recovery_sql.go`, `redis_candidates.go`, `server/matcher/worker.go` and tests cover retry classification, claim-boundary invariants, player/ticket/playlist mapping, durable queue replay/conflict, owner-scoped queue/proposal recovery, expiry at read and mutation boundaries, response replay/conflict, stale revisions, zero-row claim aborts, atomic statement ordering, incomplete matcher batches, source failures and empty-index Redis repair; opt-in PostgreSQL execution now covers queue create/replay/fencing, assignment persistence, proposal claim/promotion, participant recovery, unanimous response and rollback of partial claims; ranked provider, worker-failure and concurrent two-matcher integration tests remain |
 | 8.19 `[D:8.18]` | **IN PROGRESS.** Pure Go casual lineup requires 2–6 humans with at least one per team, fills missing slots with explicit bots, permits kickoff-only bot-slot backfill and assigns no backfill penalty/rating update; proposal preparation now derives the lineup from formed teams | `server/domain/casual.go`, `formation.go` cover both-team minimum, bot shape, live-play rejection, zero-penalty backfill and casual proposal composition; queue candidate selection, opt-in 10 s backfill proposals, reconnect/leave penalties and live integration remain |
@@ -1228,7 +1228,7 @@ the local/CI/community transport, not a silent production fallback.
 | # | Task | Acceptance |
 |---|---|---|
 | 8.39 `[D:8.3,8.14,8.17]` | **IN PROGRESS.** `MatchmakingState` now projects queue → proposal → allocation/process-ready/assignment-ready/connect/live plus terminal failure states; autoload `ControlPlaneClient` provides authenticated queue create/recovery/heartbeat/cancel and proposal response requests with idempotency/revision headers; `matchmaking.tscn`/`matchmaking.gd` expose the state and authoritative actions from the main menu; authenticated proposal recovery now reconciles missed proposal events and expires them at read time; the Go API publishes targeted authenticated revisioned queue/proposal/assignment events and the Godot client consumes state/proposal/assignment events, fetching the authoritative assignment after assignment readiness; the API can now use the durable participant-scoped proposal provider for both recovery and accept/decline mutations | `test_matchmaking_state.gd`, `test_control_plane_client.gd`, `test_matchmaking_ui.gd`, `TestProposalRecoveryIsParticipantScopedAndExpiresAtReadBoundary`, `TestAuthenticatedWebSocketDeliversOnlyTargetedRevisionedEvents`, `TestStateChangingAPIActionsPublishTargetedEvents`, `TestProposalRecoveryUsesDurableBackendAndRemainsParticipantScoped` and store proposal SQL tests reject stale/gapped/conflicting updates, validate endpoint/token/payload normalization, preserve idempotent duplicates, and guarantee visible phase/terminal copy; wiring durable allocation events into the outbox, wait/latency explanations and Godot runtime verification remain |
-| 8.40 `[D:8.3,8.14]` | **IN PROGRESS.** Pure Go revisioned replica reducer rejects gaps for REST resync, makes duplicate/out-of-order events idempotent, and resumes from the authoritative snapshot revision; authenticated queue-ticket recovery now has an owner-checked REST read; Godot client projection persists non-secret ticket/proposal state, forces authoritative recovery after restart, and can replay a lost queue-create response with the original ticket/idempotency key; the Go API now exposes an authenticated `/v1/events` WebSocket with bounded per-player queues, strict upgrade/vocabulary validation and REST-resync-safe slow-client failure; Godot `ControlPlaneClient` can connect to the stream using Godot 4.7's handshake-header API, consume validated events, automatically reconnect with bounded backoff, and trigger REST recovery on projection gaps and stream return; `OutboxDispatcher` now provides ordered at-least-once delivery after durable commit; assignment recovery events carry the durable assignment revision without leaking it into REST JSON; prediction startup now distinguishes the sequence-0 warm-up acknowledgement from genuine missing/evicted history, preventing a false hard-snap during a live match | `server/domain/sync.go`, `server/api/events.go`, `server/api/service.go`, `server/store/outbox.go`, `service_test.go`, `outbox_test.go`, `matchmaking_state.gd`, `control_plane_client.gd`, `local_prediction_history.gd`, `net_ship_predictor.gd` and tests cover gap, snapshot, replay, same-revision conflict, owner-only ticket recovery, expired-ticket terminal handling, malformed restart snapshots, API-level duplicate-create replay/conflict, authenticated handshake/key rejection, targeted event delivery, exactly-once slow-subscriber closure, invalid-event rejection, delivery-before-ack failure ordering, assignment event/response revision separation and prediction warm-up/hard-resync separation; Godot 4.7.1 headless project parse and 143-test unit harness pass with compatibility rendering, and a two-process ENet authoritative match smoke passes spawn, movement, prediction, 0% snapshot loss and 0 hard snaps; `cmd/control-plane` now provides a signal-bound API role and `cmd/matcher` provides a signal-bound casual matcher role, both applying migrations and using durable PostgreSQL boundaries; allocator/maintenance roles, Redis fan-out and live multi-process control-plane/game verification remain |
+| 8.40 `[D:8.3,8.14]` | **IN PROGRESS.** Pure Go revisioned replica reducer rejects gaps for REST resync, makes duplicate/out-of-order events idempotent, and resumes from the authoritative snapshot revision; authenticated queue-ticket recovery now has an owner-checked REST read; Godot client projection persists non-secret ticket/proposal state, forces authoritative recovery after restart, and can replay a lost queue-create response with the original ticket/idempotency key; the Go API now exposes an authenticated `/v1/events` WebSocket with bounded per-player queues, strict upgrade/vocabulary validation and REST-resync-safe slow-client failure; Godot `ControlPlaneClient` can connect to the stream using Godot 4.7's handshake-header API, consume validated events, automatically reconnect with bounded backoff, and trigger REST recovery on projection gaps and stream return; `OutboxDispatcher` now provides ordered at-least-once delivery after durable commit; assignment recovery events carry the durable assignment revision without leaking it into REST JSON; prediction startup now distinguishes the sequence-0 warm-up acknowledgement from genuine missing/evicted history, preventing a false hard-snap during a live match | `server/domain/sync.go`, `server/api/events.go`, `server/api/service.go`, `server/store/outbox.go`, `service_test.go`, `outbox_test.go`, `matchmaking_state.gd`, `control_plane_client.gd`, `local_prediction_history.gd`, `net_ship_predictor.gd` and tests cover gap, snapshot, replay, same-revision conflict, owner-only ticket recovery, expired-ticket terminal handling, malformed restart snapshots, API-level duplicate-create replay/conflict, authenticated handshake/key rejection, targeted event delivery, exactly-once slow-subscriber closure, invalid-event rejection, delivery-before-ack failure ordering, assignment event/response revision separation and prediction warm-up/hard-resync separation; Godot 4.7.1 headless project parse and 143-test unit harness pass with compatibility rendering, and a two-process ENet authoritative match smoke passes spawn, movement, prediction, 0% snapshot loss and 0 hard snaps; `cmd/control-plane` provides a signal-bound API role, `cmd/matcher` now supports casual and explicitly enabled ranked roles with durable identity lookup, and `cmd/maintenance` provides bounded season maintenance; allocator, Redis fan-out and live multi-process control-plane/game verification remain |
 | 8.41 `[D:7.8,8.9,8.31,8.40]` | **IN PROGRESS.** Authenticated `GET /v1/assignments/{matchId}` now exposes only a validated, player-scoped assignment view including the hosted endpoint; Godot `AssignmentState`/`ControlPlaneClient.fetch_assignment()` bind the response to the authenticated player, recheck expiry, validate and retain the endpoint, and `connect_to_assignment()` now starts only the validated ENet/Steam transport after assignment readiness; the opaque join authorisation is carried in the MatchNet hello payload rather than the endpoint URL; allocated Godot servers now fail closed unless an operator-mounted JSON roster of control-plane signed envelopes and an HMAC-SHA256 key are present, and MatchNet verifies the canonical Go claim bytes, checks exact token membership plus match/server/protocol/slot/expiry claims before admitting a peer, rejects concurrent reuse of an active token, tracks server-owned reconnect generations across the 60-second reclaim window, fences expired reclaims and invalidates old peers; migration 0002 and the Go store adapter now persist/recover the complete player-scoped assignment projection with conflict-safe identical replay; `AssignmentProviderFromStore` wires that durable projection into the API injection point; `SaveAssignments` publishes a complete signed roster atomically instead of allowing partial player visibility; `SaveVerifiedAssignmentRoster` rechecks signed claims before deriving player rows | `server/api/service.go`, `store_adapters.go`, `service_test.go`, `assignment_state.gd`, `control_plane_client.gd`, `match_net.gd`, `server_boot.gd`, `server_config.gd`, `test_assignment_state.gd`, `test_control_plane_client.gd`, `test_match_net.gd`, `server/contracts/v1/openapi.json`, `server/migrations/0002_assignments.sql` and `server/store/assignment_sql.go` cover participant/identity/expiry/shape/transport/endpoint boundaries, player-scoped schema keys, expiry-filtered reads, assignment upsert conflict handling, atomic batch validation, signed-claim binding, strict endpoint splitting, allowlisted claim rejection, canonical HMAC interoperability, forged-signature rejection, duplicate active-token rejection, reclaim generation/expiry behavior and 146-test Godot compatibility coverage; the three-process disconnect/reclaim smoke passes ship retention, replacement drive and old-peer invalidation; SDR relay-ticket installation, live allocated-token process integration and live Godot/PostgreSQL verification remain |
 | 8.42 `[D:8.22,8.23,8.24,8.40]` | **IN PROGRESS.** `RankedProfileState` and `ControlPlaneClient.fetch_ranked_profile()` expose the backend-authoritative rating/RD/volatility/games/tier/provisional/season view; matchmaking UI displays provisional/tier status without client-side rating math | `test_control_plane_client.gd` validates profile shape, numeric safety and provisional display; ranked profile fetch/display, committed revision after reconnect, abandon status and season countdown remain dependent on live auth/backend events and Godot runtime verification |
 | 8.43 `[D:8.39,8.40,8.41]` | **IN PROGRESS.** Matchmaking client now distinguishes expired queue recovery, session expiry, missing records and retryable control-plane outages; a 401 clears the in-memory token, emits `session_expired` and disables retry until a new session is configured; terminal messages remain visible and active searches are not falsely failed on transient errors | `MatchmakingState` and `ControlPlaneClient` tests cover explicit expiry and the existing terminal/retry-safe state paths; decline, version mismatch, regional outage retry UI, failed reconnect, duplicate-action recovery and live Godot verification remain |

server/cmd/matcher/main.go

@@ -22,9 +22,10 @@ import (
 func main() {
 	dsn := flag.String("dsn", os.Getenv("COSMIC_CLASH_POSTGRES_DSN"), "PostgreSQL connection string")
 	migrationDir := flag.String("migrations", "migrations", "directory containing numbered SQL migrations")
-	playlist := flag.String("playlist", string(domain.Casual), "playlist to match; ranked requires a provider-enabled role")
+	playlist := flag.String("playlist", string(domain.Casual), "playlist to match")
 	size := flag.Int("size", 4, "players per match")
 	interval := flag.Duration("interval", time.Second, "poll interval")
+	rankedRandomArena := flag.Bool("ranked-random-arena", false, "enable ranked matching only when the selected arena is random and non-elevated")
 	redisAddr := flag.String("redis-addr", os.Getenv("COSMIC_CLASH_REDIS_ADDR"), "optional Redis candidate projection address")
 	redisPrefix := flag.String("redis-prefix", envOrDefault("COSMIC_CLASH_REDIS_PREFIX", "cosmic-clash"), "Redis key prefix")
 	redisTTL := flag.Duration("redis-ttl", 60*time.Second, "TTL for transient candidate projection entries")
@@ -32,8 +33,15 @@ func main() {
 	if *dsn == "" {
 		fatalf("--dsn or COSMIC_CLASH_POSTGRES_DSN is required")
 	}
-	if *playlist != string(domain.Casual) {
+	if *playlist != string(domain.Casual) && *playlist != string(domain.Ranked) {
-		fatalf("unsupported playlist %q; only casual is currently enabled", *playlist)
+		fatalf("unsupported playlist %q", *playlist)
+	}
+	selectedPlaylist := domain.Playlist(*playlist)
+	if selectedPlaylist == domain.Ranked && *size != 6 {
+		fatalf("ranked matching requires --size=6")
+	}
+	if selectedPlaylist == domain.Casual && *size < 2 || selectedPlaylist == domain.Casual && *size > 6 {
+		fatalf("casual matching requires --size between 2 and 6")
 	}
 	if *redisTTL <= 0 {
 		fatalf("--redis-ttl must be positive")
@@ -60,7 +68,7 @@ func main() {
 		candidateProjection := store.CandidateProjection{
 			Index: store.RedisCandidateIndex{Client: redisClient, Prefix: *redisPrefix, TTL: *redisTTL},
 			Source: func(ctx context.Context, at time.Time) ([]domain.Candidate, error) {
-				return store.ListQueuedCandidates(ctx, db, domain.Casual, at, 1000)
+				return store.ListQueuedCandidates(ctx, db, selectedPlaylist, at, 1000)
 			},
 		}
 		projection = &candidateProjection
@@ -88,9 +96,20 @@ func main() {
 		Creator: matcher.ProposalCreatorFunc(func(ctx context.Context, proposal domain.Proposal, ticketIDs map[string]string, at time.Time) error {
 			return store.CreateProposal(ctx, db, proposal, ticketIDs, at)
 		}),
-		Playlist: domain.Casual, Size: *size, Now: now,
+		Playlist: selectedPlaylist, Size: *size, Now: now,
 		NextID: func() string { return fmt.Sprintf("proposal-%d", time.Now().UnixNano()) },
 		Prepare: func(id string, playlist domain.Playlist, formation domain.MatchFormation, at time.Time) (domain.PreparedProposal, error) {
+			if playlist == domain.Ranked {
+				playerIDs := make([]string, 0, len(formation.Selection.Players))
+				for _, player := range formation.Selection.Players {
+					playerIDs = append(playerIDs, player.PlayerID)
+				}
+				participants, err := store.LoadRankedParticipants(context.Background(), db, playerIDs)
+				if err != nil {
+					return domain.PreparedProposal{}, err
+				}
+				return domain.PrepareProposal(id, playlist, formation, participants, domain.RankedArena{RandomEnabled: *rankedRandomArena}, at)
+			}
 			return domain.PrepareProposal(id, playlist, formation, nil, domain.RankedArena{}, at)
 		},
 	}

server/store/queue_sql.go

@@ -44,6 +44,40 @@ WHERE state = 'QUEUED' AND playlist = $1 AND expires_at > $2
 ORDER BY enqueued_at, ticket_id
 LIMIT $3`
 
+const RankedParticipantSQL = `SELECT player_id, steam_id
+FROM identities
+WHERE player_id = ANY($1)
+ORDER BY player_id`
+
+// LoadRankedParticipants resolves the verified identity metadata required by
+// ranked admission. The caller must compare the returned set with the formed
+// candidate set; a partial lookup is not a valid ranked roster.
+func LoadRankedParticipants(ctx context.Context, db *sql.DB, playerIDs []string) ([]domain.RankedParticipant, error) {
+	if db == nil || len(playerIDs) != 6 {
+		return nil, fmt.Errorf("ranked admission requires six players")
+	}
+	rows, err := db.QueryContext(ctx, RankedParticipantSQL, playerIDs)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	participants := make([]domain.RankedParticipant, 0, len(playerIDs))
+	for rows.Next() {
+		var participant domain.RankedParticipant
+		if err := rows.Scan(&participant.PlayerID, &participant.SteamID); err != nil {
+			return nil, err
+		}
+		participants = append(participants, participant)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	if len(participants) != len(playerIDs) {
+		return nil, fmt.Errorf("ranked identity metadata is incomplete")
+	}
+	return participants, nil
+}
+
 // ListQueuedCandidates is an authoritative, expiry-filtered source for the
 // matcher projection. It deliberately does not claim rows; CreateProposal is
 // the transaction that performs the competing claim with SKIP LOCKED fences.

server/store/queue_sql_test.go

@@ -8,13 +8,14 @@ import (
 
 func TestQueueSQLUsesDurableIdempotencyAndOwnerScopedRecovery(t *testing.T) {
 	for query, fragments := range map[string][]string{
-		QueueIdempotencyInsertSQL: {"idempotency_keys", "ON CONFLICT (scope, idempotency_key) DO NOTHING", "payload_digest"},
+		QueueIdempotencyInsertSQL:   {"idempotency_keys", "ON CONFLICT (scope, idempotency_key) DO NOTHING", "payload_digest"},
-		QueueIdempotencySelectSQL: {"scope = $1", "idempotency_key = $2", "FOR UPDATE"},
+		QueueIdempotencySelectSQL:   {"scope = $1", "idempotency_key = $2", "FOR UPDATE"},
-		QueueTicketSelectSQL:      {"ticket_id = $1", "player_id = $2"},
+		QueueTicketSelectSQL:        {"ticket_id = $1", "player_id = $2"},
-		QueueTicketInsertSQL:      {"player_id", "playlist", "client_build", "protocol_version"},
+		QueueTicketInsertSQL:        {"player_id", "playlist", "client_build", "protocol_version"},
-		QueueTicketHeartbeatSQL:   {"player_id = $2", "revision = $3", "expires_at > $4", "RETURNING"},
+		QueueTicketHeartbeatSQL:     {"player_id = $2", "revision = $3", "expires_at > $4", "RETURNING"},
-		QueueTicketCancelSQL:      {"player_id = $2", "revision = $3", "state NOT IN", "RETURNING"},
+		QueueTicketCancelSQL:        {"player_id = $2", "revision = $3", "state NOT IN", "RETURNING"},
 		QueueCandidateProjectionSQL: {"playlist = $1", "predicted_rtt", "expires_at > $2", "LIMIT $3"},
+		RankedParticipantSQL:        {"steam_id", "player_id = ANY($1)", "ORDER BY player_id"},
 	} {
 		for _, fragment := range fragments {
 			if !contains(query, fragment) {
@@ -24,6 +25,12 @@ func TestQueueSQLUsesDurableIdempotencyAndOwnerScopedRecovery(t *testing.T) {
 	}
 }
 
+func TestLoadRankedParticipantsRejectsNonSixPlayerLookupsWithoutDatabase(t *testing.T) {
+	if _, err := LoadRankedParticipants(nil, nil, []string{"player-1"}); err == nil {
+		t.Fatal("partial ranked identity lookup was accepted")
+	}
+}
+
 func TestListQueuedCandidatesRejectsUnscopedOrUnboundedReads(t *testing.T) {
 	now := time.Unix(1000, 0)
 	for _, playlist := range []domain.Playlist{"", "invalid"} {