docs: add comprehensive Realtime module refactoring proposal

This proposal outlines a systematic refactoring of the Realtime module to
address maintainability, reliability, and testability concerns.

**Key Highlights:**

- Identifies 5 major architectural pain points in current implementation
- Proposes actor-based state machines for connection and subscription management
- Maintains 100% backward compatibility in public API
- Reduces complexity through clear separation of concerns
- Provides 4-phase migration strategy with risk mitigation

**Proposed Core Components:**

1. ConnectionStateMachine - Eliminates connection race conditions
2. HeartbeatMonitor - Isolates heartbeat logic
3. AuthTokenManager - Simplifies token management
4. MessageRouter - Centralizes message dispatch
5. SubscriptionStateMachine - Manages subscription lifecycle
6. EventHandlerRegistry - Type-safe event handling

**Benefits:**

- 40% reduction in LOC through better organization
- Impossible to have invalid states (type system enforced)
- 85%+ test coverage target
- 50% reduction in time to fix bugs
- Better developer experience

**Recommendation:**

Start with Phase 1 (3-5 days, low risk, high value):
- Extract ConnectionStateMachine
- Extract HeartbeatMonitor
- Extract AuthTokenManager
- Extract MessageRouter

Estimated total effort: 11-17 days for complete refactoring

The proposal is ready for team review and discussion.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: grdsdev