feat: add runnable casual matcher role

server/store/queue_sql.go

@@ -37,6 +37,41 @@ WHERE ticket_id = $1 AND player_id = $2 AND revision = $3
 RETURNING ticket_id, player_id, playlist, state, client_build, protocol_version, enqueued_at, expires_at, revision`
 )
 
+const QueueCandidateProjectionSQL = `SELECT ticket_id, player_id, playlist, client_build,
+    protocol_version, enqueued_at
+FROM queue_tickets
+WHERE state = 'QUEUED' AND expires_at > $1
+ORDER BY enqueued_at, ticket_id
+LIMIT $2`
+
+// 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.
+func ListQueuedCandidates(ctx context.Context, db *sql.DB, now time.Time, limit int) ([]domain.Candidate, error) {
+	if db == nil || now.IsZero() || limit < 1 || limit > 1000 {
+		return nil, fmt.Errorf("invalid queued candidate arguments")
+	}
+	rows, err := db.QueryContext(ctx, QueueCandidateProjectionSQL, now, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var candidates []domain.Candidate
+	for rows.Next() {
+		var candidate domain.Candidate
+		var playlist string
+		if err := rows.Scan(&candidate.TicketID, &candidate.PlayerID, &playlist, &candidate.ClientBuild, &candidate.ProtocolVersion, &candidate.EnqueuedAt); err != nil {
+			return nil, err
+		}
+		candidate.Playlist = domain.Playlist(playlist)
+		candidates = append(candidates, candidate)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return candidates, nil
+}
+
 func CreateQueueTicket(ctx context.Context, db *sql.DB, ticketID, playerID, idempotencyKey string, spec domain.QueueSpec, now time.Time) (domain.QueueTicket, error) {
 	if db == nil || ticketID == "" || playerID == "" || len(idempotencyKey) < 16 || len(idempotencyKey) > 128 || (spec.Playlist != domain.Casual && spec.Playlist != domain.Ranked) || spec.ClientBuild == "" || len(spec.ClientBuild) > 128 || spec.ProtocolVersion < 1 || now.IsZero() {
 		return domain.QueueTicket{}, fmt.Errorf("invalid queue transaction arguments")