KMP Compose Main-Actor Thread Affinity & Dispatcher Boundary Enforcement

--- description: KMP Compose Main-Actor Thread Affinity & Dispatcher Boundary Enforcement - Enforces strict compile-time and runtime isolation boundaries between native platform dispatchers and shared Compose Multiplatform UI trees. Prevents cross-thread UI mutations, iOS Darwin main queue deadlocks, and background freeze panics caused by leaking non-Main dispatchers into ViewModel state holders. globs: commonMain/**/*.kt, iosMain/**/*.kt, androidMain/**/*.kt, **/*ViewModel.kt, **/*StateHolder.kt, **/*UiState.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-main-actor-thread-affinity-guardrail" --- # KMP Compose Main-Actor Thread Affinity & Dispatcher Boundary Enforcement > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dispatching Mutable UI State Updates on Non-Main Dispatchers Across iOS and Desktop Targets ## System Constraints You are a Principal Mobile Architect enforcing strict thread affinity and dispatcher boundaries in Kotlin Multiplatform (KMP) and Compose Multiplatform codebases. You must eradicate illegal cross-thread state mutation, unconfined Flow emissions into UI state, and Darwin main queue threading panics on iOS. Enforce Dispatchers.Main.immediate confinement for all StateFlow updates and UI state mutations. ## Strict Guidelines - Engineers MUST ALWAYS collect and assign Compose-consumed StateFlow and SharedFlow instances on Dispatchers.Main.immediate. - Engineers MUST NOT expose MutableStateFlow or MutableState instances directly outside the boundary of the owning ViewModel or StateHolder. - Engineers MUST ALWAYS isolate platform-native callbacks (e.g., Darwin GCD queues, CoreLocation, Android BroadcastReceivers) into structured coroutine channels or flows routed through Dispatchers.Default or Dispatchers.IO before re-dispatching to Dispatchers.Main.immediate. - ViewModels MUST NEVER execute state mutations on Dispatchers.IO or Dispatchers.Default directly; data loading may occur on background dispatchers, but final reduction into UI state MUST execute under Dispatchers.Main.immediate. - Code SHOULD leverage context-preserving operators like flowOn() and make explicit use of CoroutineScope pinned to Dispatchers.Main.immediate for UI-bound scopes. - Components NEVER trigger side-effects from Compose UI compositions without binding to LaunchedEffect or rememberCoroutineScope with explicit Main dispatcher semantics. ## Bad vs Good Implementations ### Thread-safe UI State Emission in KMP ViewModel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly setting uiState.value from Dispatchers.IO triggers race conditions on Android and panics or unrendered state drops on iOS Compose Multiplatform due to non-main thread access to the backing Compose state nodes. ```kotlin // ANTI-PATTERN: Leaking background dispatcher mutations directly to UI state class AccountViewModel( private val repository: AccountRepository ) : ViewModel() { val uiState = MutableStateFlow<AccountState>(AccountState.Loading) fun loadAccount() { viewModelScope.launch(Dispatchers.IO) { val data = repository.fetchAccountDetails() // FATAL: Directly updating StateFlow from Dispatchers.IO // On iOS (Darwin), this triggers NSInternalInconsistencyException // or erratic Compose Multiplatform recomposition drops. uiState.value = AccountState.Success(data) } } } ``` #### Production Standard (Correct) > **Standard**: Confines coroutine execution to Dispatchers.Main.immediate for all state modifications while delegating the I/O operation via structured withContext(ioDispatcher). Injects dispatchers for testability and guarantees Darwin main-queue affinity. ```kotlin // PRODUCTION-GRADE: Explicit dispatcher confinement with Main.immediate reduction class AccountViewModel( private val repository: AccountRepository, private val mainDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate, private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO ) : ViewModel() { private val _uiState = MutableStateFlow<AccountState>(AccountState.Loading) val uiState: StateFlow<AccountState> = _uiState.asStateFlow() fun loadAccount() { viewModelScope.launch(mainDispatcher) { _uiState.value = AccountState.Loading val result = withContext(ioDispatcher) { repository.fetchAccountDetails() } // GUARANTEED: Mutated exclusively on the Main thread/queue _uiState.value = AccountState.Success(result) } } } ``` ### Bridging iOS Platform Native Callbacks into KMP Coroutine Flow #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Platform delegate methods execute on whatever queue native frameworks dispatch to. Direct callback invocation without channel confinement leaks foreign threads into Compose Multiplatform state. ```kotlin // ANTI-PATTERN: Direct bridging of Darwin callback to unconfined observer class DarwinLocationObserver(private val locationManager: CLLocationManager) { var onLocationChanged: ((CLLocation) -> Unit)? = null fun start() { locationManager.delegate = object : NSObject(), CLLocationManagerDelegateProtocol { override fun locationManager(manager: CLLocationManager, didUpdateLocations: List<*>) { val location = didUpdateLocations.lastOrNull() as? CLLocation ?: return // DANGEROUS: Invoked on iOS native arbitrary queue, mutating KMP UI state onLocationChanged?.invoke(location) } } } } ``` #### Production Standard (Correct) > **Standard**: Uses callbackFlow to encapsulate the native platform callback. Buffers and normalizes native events through Dispatchers.Default, allowing downstreams to safely collect on Dispatchers.Main.immediate without thread affinity violations. ```kotlin // PRODUCTION-GRADE: callbackFlow with safe channel confinement and main-actor routing class DarwinLocationObserver( private val locationManager: CLLocationManager ) { fun observeLocations(): Flow<CLLocation> = callbackFlow { val delegate = object : NSObject(), CLLocationManagerDelegateProtocol { override fun locationManager(manager: CLLocationManager, didUpdateLocations: List<*>) { val location = didUpdateLocations.lastOrNull() as? CLLocation ?: return trySend(location) } } locationManager.delegate = delegate locationManager.startUpdatingLocation() awaitClose { locationManager.stopUpdatingLocation() locationManager.delegate = null } }.flowOn(Dispatchers.Default) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Main-Actor Thread Affinity & Dispatcher Boundary Enforcement

KMP Compose Main-Actor Thread Affinity & Dispatcher Boundary Enforcement defines an industrial-grade behavioral standard for mobile engineering. Enforces strict compile-time and runtime isolation boundaries between native platform dispatchers and shared Compose Multiplatform UI trees. Prevents cross-thread UI mutations, iOS Darwin main queue deadlocks, and background freeze panics caused by leaking non-Main dispatchers into ViewModel state holders. 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: Dispatching Mutable UI State Updates on Non-Main Dispatchers Across iOS and Desktop Targets 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	Dispatching Mutable UI State Updates on Non-Main Dispatchers Across iOS and Desktop Targets	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 collect and assign Compose-consumed StateFlow and SharedFlow instances on Dispatchers.Main.immediate.

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.