KMP Native Coroutine Dispatcher Isolation and Scope Lifecycle Boundary

--- description: "KMP Native Coroutine Dispatcher Isolation and Scope Lifecycle Boundary - Enforces strict isolation of shared Kotlin Multiplatform coroutine scopes across JVM/Android and Apple Native runtimes. Prevents thread freezing violations, unconfined Main actor hopping, and memory leaks by mandating platform-specific dispatcher resolution, lifecycle-bound scopes, and explicit cancellation contracts across the foreign function interface (FFI)." globs: "**/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/appleMain/**/*.kt" alwaysApply: true license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-coroutine-dispatcher-isolation-boundary" --- # KMP Native Coroutine Dispatcher Isolation and Scope Lifecycle Boundary > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unconfined GlobalScope Spawning and Hardcoded JVM Dispatchers Across Apple Native Targets ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and low-level runtime concurrency. You mandate that shared coroutines never leak across native Swift/Objective-C boundaries, never invoke unconfined global dispatchers, and strictly adhere to platform-isolated dispatcher contracts (such as Dispatchers.Main.immediate and native background workers) with explicit lifecycle termination hooks. ## Strict Guidelines - Engineers MUST ALWAYS declare an expect/actual or dependency-injected CoroutineDispatchers provider contract rather than referencing hardcoded static Dispatchers directly in common code. - Engineers MUST NOT use GlobalScope, CoroutineScope(Dispatchers.Unconfined), or CoroutineScope(Dispatchers.Default) as unmanaged singletons across platform boundaries. - Engineers MUST provide an explicit, idempotent cancel() or close() lifecycle bridge method on any shared stateful class or ViewModel consumed by Swift/Objective-C. - Engineers MUST use Dispatchers.Main.immediate for UI state publication in common modules to prevent frame drops, re-entrancy deadlocks, and dispatch scheduling lag on Apple runtimes. - Background pipelines in Apple targets MUST rely on multi-threaded worker dispatchers (e.g., Dispatchers.Default or Dispatchers.IO where available via KMP coroutines 1.7.0+) and strictly avoid blocking native CFRunLoop threads with runBlocking. - StateFlow and SharedFlow subscriptions exported to iOS MUST be wrapped in an isolated platform-agnostic FlowWrapper or explicit job canceler to prevent Swift retain cycles and zombie native references. ## Bad vs Good Implementations ### Coroutine Dispatcher Injection and iOS Scope Lifecycle Management #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly instantiating an unmanaged CoroutineScope with hardcoded Dispatchers in common code prevents iOS native runtimes from releasing ViewModel instances, risking memory leaks when views pop off the navigation stack. Relying on raw Dispatchers.Main without .immediate induces avoidable dispatch hops on Darwin run loops. ```kotlin // COMMON CODE: Hardcoded dispatchers and unmanaged coroutine leaks class UserProfileViewModel { // ANTI-PATTERN: Leaks memory on iOS; Swift cannot cancel this scope private val scope = CoroutineScope(Dispatchers.Default) val userState = MutableStateFlow<String>("Initial") fun loadUserData() { // ANTI-PATTERN: Direct hardcoded dispatcher creates unconfined native thread hops scope.launch(Dispatchers.IO) { val data = fetchFromNetwork() // ANTI-PATTERN: Dispatchers.Main on Apple Native schedules via run loop without immediate execution check withContext(Dispatchers.Main) { userState.value = data } } } private suspend fun fetchFromNetwork(): String = "User Data" } ``` #### Production Standard (Correct) > **Standard**: Injecting CoroutineDispatchersProvider enables platform-specific dispatcher mapping (e.g., Dispatchers.Main.immediate). The SupervisorJob and explicit clear() method allow the native platform (e.g., Swift UI deinit or Android onCleared) to tear down in-flight coroutines, eliminating native memory retention and race conditions. ```kotlin // COMMON CODE: Injectable Dispatchers contract with explicit lifecycle teardown interface CoroutineDispatchersProvider { val main: CoroutineDispatcher val io: CoroutineDispatcher val default: CoroutineDispatcher } class UserProfileViewModel( private val dispatchers: CoroutineDispatchersProvider ) { private val job = SupervisorJob() // Use Main.immediate via provider to guarantee immediate execution if already on main thread private val scope = CoroutineScope(job + dispatchers.main) private val _userState = MutableStateFlow<String>("Initial") val userState: StateFlow<String> = _userState.asStateFlow() fun loadUserData() { scope.launch { val data = withContext(dispatchers.io) { fetchFromNetwork() } _userState.value = data } } // Mandatory lifecycle cleanup boundary for iOS/Android hosts fun clear() { job.cancel() } private suspend fun fetchFromNetwork(): String = "User Data" } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Native Coroutine Dispatcher Isolation and Scope Lifecycle Boundary

KMP Native Coroutine Dispatcher Isolation and Scope Lifecycle Boundary defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation of shared Kotlin Multiplatform coroutine scopes across JVM/Android and Apple Native runtimes. Prevents thread freezing violations, unconfined Main actor hopping, and memory leaks by mandating platform-specific dispatcher resolution, lifecycle-bound scopes, and explicit cancellation contracts across the foreign function interface (FFI). 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: Unconfined GlobalScope Spawning and Hardcoded JVM Dispatchers Across Apple Native 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	Unconfined GlobalScope Spawning and Hardcoded JVM Dispatchers Across Apple Native 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 declare an expect/actual or dependency-injected CoroutineDispatchers provider contract rather than referencing hardcoded static Dispatchers directly in common code.

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.