parity(auth): add dispose() method + AuthRefreshDiscardedError for lockless coordination [from supabase-js]

[grdsdev]

SDK Parity: Kotlin implementation needed

Reference Implementation (supabase-js)

• Commit: 54ec2b6
• PR: #2392
• Module: auth
• Type: new-feature + deprecation

What Changed

1. New dispose() method on auth client — explicitly stops auto-refresh and cleans up state. Prevents coroutine leaks when the client is no longer needed.

2. New AuthRefreshDiscardedError — returned when a token refresh succeeded server-side but tokens were discarded because the local session changed mid-flight (e.g., concurrent signOut).

3. lock option deprecated — navigator.locks-based mutex removed.

Code Reference

async dispose(): Promise<void>  // stops auto-refresh, clears state

class AuthRefreshDiscardedError extends AuthError {
  name = 'AuthRefreshDiscardedError'
  // session changed mid-flight during refresh
}

Implementation Guidance (Kotlin)

// New method on GoTrueClient
fun dispose() {
    // Cancel auto-refresh coroutine/Job
    // Clear in-memory session state
}

// New exception
class AuthRefreshDiscardedException(message: String = "Session refresh was discarded") 
  : RestException(message, ...)

Key Behaviors

• dispose() cancels background refresh jobs (idempotent)
• AuthRefreshDiscardedException used when refresh succeeded but session changed mid-flight
• Deprecate lock option if present

Acceptance Criteria

• dispose() method added, cancels background refresh
• AuthRefreshDiscardedException added
• Tests cover cleanup on dispose

Context

• supabase-js version: v2.107.0
• Migration guide: lockless-coordination.md
• Related Linear issues: SDK-1026 (dart), SDK-1027 (py), SDK-1028 (swift)

---

Generated with Claude Code /sync-sdk-parity