[AUTH]: Make OAuth onboarding and role provisioning transactionally consistent

[barry01-hash]

Context

Supabase authentication, the local User record, role selection, and role-specific Grantee/PayoutProvider records are created through separate requests and hooks. Retries, simultaneous tabs, or callback failures can leave partial identities and conflicting onboarding state.

Scope

• Define an explicit onboarding state model independent of inferred missing rows.
• Make local identity upsert idempotent across email/password and OAuth callbacks.
• Provision the selected role and role-specific record atomically.
• Prevent unauthorized role changes and define the supported role-change workflow.
• Handle email changes, provider linking, duplicate verified emails, and disabled users deliberately.
• Replace duplicated client initialization checks with one server-authoritative bootstrap endpoint.

Acceptance criteria

• Replaying OAuth callbacks or opening multiple tabs creates exactly one local identity.
• Users cannot reach the dashboard with an impossible partial role state.
• Role provisioning commits fully or rolls back fully.
• Identity collisions return a safe recoverable path without account takeover risk.
• Integration tests cover callback retry, concurrent selection, disabled user, and provider linking.
• The onboarding state diagram and recovery procedure are documented.

Relevant areas

OAuth verification/register routes, role-selection provider/hooks, auth context/services, User, Grantee, and PayoutProvider models.