Resolve the highest-ranked role from an array of user roles.
Used to determine display role (primaryRole) for AuthPrincipal.
Total order: primary = highest ROLE_HIERARCHY weight; ties are broken by
canonical declaration order (the role declared first in ROLE_HIERARCHY
wins), making the result independent of input array order. Unknown roles
weight 0 (below every known role) and their remaining ties are broken
lexicographically, so order-independence holds for the whole domain (#624).
Total over the empty set (#624): an array with no roles yields null
rather than throwing. Callers that require a concrete role guard at their
boundary (e.g. resolvePrimaryRole(roles) ?? "").
Resolve the highest-ranked role from an array of user roles. Used to determine display role (primaryRole) for AuthPrincipal.
Total order: primary = highest ROLE_HIERARCHY weight; ties are broken by canonical declaration order (the role declared first in ROLE_HIERARCHY wins), making the result independent of input array order. Unknown roles weight 0 (below every known role) and their remaining ties are broken lexicographically, so order-independence holds for the whole domain (#624).
Total over the empty set (#624): an array with no roles yields
nullrather than throwing. Callers that require a concrete role guard at their boundary (e.g.resolvePrimaryRole(roles) ?? "").