gpg always returns the primary user id first. (see gnupg/g10.keylist.org:reorder_keyblock). gpgme keeps this order and thus the first user +id in the linked list is the primary user id. If the primary user id flag is not set the first is the same what gpg considers the primary user id. I can add this to the documentation.

Well, it is already there:

@item gpgme_user_id_t uids

This is a linked list with the user IDs of the key.  The first user ID
in the list is the main (or primary) user ID.

But there can be several user IDs that are marked primary, right? I know that gpg tries to not let that happen, but there are other OpenPGP toolkits out there, and composite/hybridized keys, etc where this could happen.

Even if gpg reports all the primary user IDs first, there doesn't appear to be a way to tell when the listing switches from primary to non-primary user IDs.

Right, but gpg has a strategy to figure out what it considers the primary (ie. the user id commonly printed). If we would merely convey the primary key flag to gpgme, gpgme or the gpgme calling application still needs to figure out what it considers the primary key - that might be different from what gpg shows.

I guess it depends on whether you want gpgme to be an interface to OpenPGP certificates more generally (in which case, exposing the primary flag would be useful), or just a gpg frontend (in which case, the current behavior might be ok)

gpgme shall provide an interface for commonly required tasks but it shall not expose everything from gpg.