I noticed that the references() method does not support fields on embedded objects, as the argument to the preceding field() method will be passed into getFieldMapping() and trigger an exception. I suppose a solution would require multiple calls to getFieldMapping() in order to dive into the embedded object's class metadata.

To demonstrate, below is an example of a UserRepository class. The User document contains an embeddedObject that itself references another User:

class UserRepository extends DocumentRepository
{ 
    public function findByEmbeddedObjectReference(User $user)
    {
        return $this->createQueryBuilder()
            ->field('embeddedObject.user.$id')->equals($user->getId())
//          ->field('embeddedObject.user')->references($user)
            ->getQuery()
            ->execute();
    }
}

Using field()/equals() works fine as an alternative to references(), so there is no urgent need for this feature.