Enforce Target-Native Main Dispatcher Boundaries for Compose Multiplatform State Mutations

--- description: Enforce Target-Native Main Dispatcher Boundaries for Compose Multiplatform State Mutations - Ensures all shared Kotlin Multiplatform (KMP) StateFlow, SharedFlow, and Compose runtime state mutations execute strictly on Dispatchers.Main.immediate. Cross-thread state updates originating from background dispatchers bypass UIKit and Android Choreographer synchronizations, inducing UI race conditions, deadlocks, and missed recomposition frames. globs: **/commonMain/**/viewmodel/**/*.kt, **/commonMain/**/presentation/**/*.kt, **/commonMain/**/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-state-mutation-boundary" --- # Enforce Target-Native Main Dispatcher Boundaries for Compose Multiplatform State Mutations > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating Shared ViewState on Unconfined or Worker Dispatchers Triggering Multiplatform UI Desynchronization ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform Compose State Lifecycle Mutation Boundaries. Mandate that all state container mutations, Flow collections for presentation, and Compose snapshot transitions are strictly confined to Dispatchers.Main.immediate. Reject any ViewModel implementation that directly executes UI state updates inside non-main coroutine contexts or relies on unconfined platform dispatchers. ## Strict Guidelines - Engineers MUST ALWAYS trigger MutableStateFlow mutations and snapshot state writes on Dispatchers.Main.immediate to guarantee lock-free synchronization with platform render cycles. - Engineers MUST NOT switch ViewModel root scopes to Dispatchers.IO or Dispatchers.Default; offload computational or I/O workloads using granular `withContext(Dispatchers.IO)` calls within main-scoped coroutines. - Code SHOULD configure `SharingStarted.WhileSubscribed(stopTimeoutMillis = 5_000)` on all `stateIn` operators to prevent background state emissions during UI lifecycle detachment. - Services MUST return pure immutable domain models or raw data flows, leaving state reduction and dispatcher confinement exclusively to presentation layer view models. - Components NEVER collect state flows inside multiplatform composables using unconfined dispatchers; collection MUST bind to the composition lifecycle via `collectAsStateWithLifecycle()`. ## Bad vs Good Implementations ### Shared ViewModel State Mutation Boundary Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating _uiState within Dispatchers.IO violates Compose Multiplatform thread-affinity rules. On iOS, updating state off the main thread risks race conditions in the Skiko/UIKit render pipeline; on Android, it leads to dropped frames and snapshot state collision exceptions. ```kotlin class UserProfileViewModel( private val userRepository: UserRepository ) : ViewModel() { private val _uiState = MutableStateFlow<ProfileUiState>(ProfileUiState.Loading) val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow() fun loadProfile(userId: String) { // VIOLATION: Launching on Dispatchers.IO causes state mutations off the main thread, // causing snapshot conflicts and race conditions on iOS and Android Compose runtimes. viewModelScope.launch(Dispatchers.IO) { val user = userRepository.fetchUser(userId) _uiState.update { ProfileUiState.Success(user) } } } } ``` #### Production Standard (Correct) > **Standard**: The coroutine starts and finishes state updates on Dispatchers.Main.immediate. The blocking I/O operation is isolated within a `withContext(ioDispatcher)` block, safely suspending and resuming back to the target-native UI dispatcher before mutating state. ```kotlin class UserProfileViewModel( private val userRepository: UserRepository, private val mainImmediateDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate, private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO ) : ViewModel() { private val _uiState = MutableStateFlow<ProfileUiState>(ProfileUiState.Loading) val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow() fun loadProfile(userId: String) { // COMPLIANT: Root coroutine retains Dispatchers.Main.immediate affinity. viewModelScope.launch(mainImmediateDispatcher) { _uiState.update { ProfileUiState.Loading } // Boundary: I/O execution is scoped down, then resumed on Main.immediate. val result = runCatching { withContext(ioDispatcher) { userRepository.fetchUser(userId) } } _uiState.update { result.fold( onSuccess = { ProfileUiState.Success(it) }, onFailure = { ProfileUiState.Error(it.message ?: "Unknown error") } ) } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce Target-Native Main Dispatcher Boundaries for Compose Multiplatform State Mutations

Enforce Target-Native Main Dispatcher Boundaries for Compose Multiplatform State Mutations defines an industrial-grade behavioral standard for mobile engineering. Ensures all shared Kotlin Multiplatform (KMP) StateFlow, SharedFlow, and Compose runtime state mutations execute strictly on Dispatchers.Main.immediate. Cross-thread state updates originating from background dispatchers bypass UIKit and Android Choreographer synchronizations, inducing UI race conditions, deadlocks, and missed recomposition frames. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Mutating Shared ViewState on Unconfined or Worker Dispatchers Triggering Multiplatform UI Desynchronization Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Mutating Shared ViewState on Unconfined or Worker Dispatchers Triggering Multiplatform UI Desynchronization	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS trigger MutableStateFlow mutations and snapshot state writes on Dispatchers.Main.immediate to guarantee lock-free synchronization with platform render cycles.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.