KMP Coroutine Dispatcher Thread-Confinement Invariant Across Darwin and Android JNI Bridges

--- description: KMP Coroutine Dispatcher Thread-Confinement Invariant Across Darwin and Android JNI Bridges - Enforces strict dispatcher injection and platform thread-confinement invariants across Kotlin Multiplatform boundaries. Prevents Darwin main-thread freeze, JNI thread detachment deadlocks, and cross-isolate memory corruption by forbidding hardcoded standard dispatchers, unconfined bridge calls, and unmanaged GlobalScope instances across Kotlin/Native and Kotlin/JVM layers. globs: **/commonMain/**/*.kt, **/androidMain/**/*.kt, **/iosMain/**/*.kt, **/appleMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-coroutine-dispatcher-thread-confinement-invariant" --- # KMP Coroutine Dispatcher Thread-Confinement Invariant Across Darwin and Android JNI Bridges > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoded Dispatchers.IO/Main Leaking Across Darwin and Android FFI Boundaries Causing Deadlocks and Crashes ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform Coroutine Dispatcher Thread-Confinement Invariants. You must ensure all coroutine context switching across Kotlin/Native (Darwin Grand Central Dispatch) and Kotlin/JVM (Android Looper/JNI) respects platform thread confinement rules, guarantees clean cancellation, utilizes injected CoroutineDispatchers, and avoids blocking FFI boundary crossings. ## Strict Guidelines - Engineers MUST ALWAYS inject a dedicated CoroutineDispatchers interface (providing main, io, default, unconfined) rather than referencing Dispatchers.IO or Dispatchers.Main directly in commonMain. - Engineers MUST NOT execute blocking synchronous calls (e.g., runBlocking, Thread.sleep) on Darwin main queues or within JNI transition layers, which immediately triggers watchdogs and ANRs. - Code SHOULD use Dispatchers.Default or a bounded Darwin GCD queue for CPU-bound tasks in Apple targets, as Dispatchers.IO on Kotlin/Native can exhaust thread pools if saturated with blocking calls. - Services MUST ensure that all UI-bound mutations triggered from Swift/Objective-C interop or Android ViewModels resolve strictly on Dispatchers.Main.immediate to eliminate frame dropping and UI reentrancy hazards. - Components NEVER use GlobalScope or construct unmanaged CoroutineScope instances; every coroutine must be tied to a managed lifecycle (e.g., KmpViewModel, platform lifecycles, or Structured Concurrency primitives) with proactive cancellation. ## Bad vs Good Implementations ### Dispatchers Injection and Darwin-Safe Context Switching #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly references GlobalScope and hardcoded dispatchers. On Kotlin/Native (Darwin), uncontrolled concurrency via GlobalScope causes resource leaks, and lack of immediate main dispatch can trigger out-of-order UI frames or bridge deadlocks. ```kotlin // commonMain: Violates thread confinement and breaks unit testability class UserRepository { fun fetchUserAndDisplay(userId: String) { // Direct reference to Dispatchers.IO and GlobalScope GlobalScope.launch(Dispatchers.IO) { val user = networkCall(userId) // Blocks or suspends without injected context withContext(Dispatchers.Main) { // Risky on Darwin without immediate dispatch guarantee updateUi(user) } } } } ``` #### Production Standard (Correct) > **Standard**: Coroutines rely entirely on injected CoroutineDispatchers. Lifecycles are scoped and bounded, allowing platform-specific overrides (like TestDispatcher or Darwin Dispatchers.Main.immediate) and preventing thread leaks. ```kotlin // commonMain: Enforces strict structured concurrency and injected dispatchers interface AppCoroutineDispatchers { val main: CoroutineDispatcher val io: CoroutineDispatcher val default: CoroutineDispatcher } class UserRepository( private val dispatchers: AppCoroutineDispatchers, private val coroutineScope: CoroutineScope ) { suspend fun fetchUser(userId: String): Result<User> = withContext(dispatchers.io) { runCatching { networkCall(userId) } } fun observeUser(userId: String, onUserUpdated: (User) -> Unit) { coroutineScope.launch(dispatchers.main) { val result = fetchUser(userId) result.onSuccess { user -> // Safe main-thread emission across Swift/JNI onUserUpdated(user) } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Coroutine Dispatcher Thread-Confinement Invariant Across Darwin and Android JNI Bridges

KMP Coroutine Dispatcher Thread-Confinement Invariant Across Darwin and Android JNI Bridges defines an industrial-grade behavioral standard for mobile engineering. Enforces strict dispatcher injection and platform thread-confinement invariants across Kotlin Multiplatform boundaries. Prevents Darwin main-thread freeze, JNI thread detachment deadlocks, and cross-isolate memory corruption by forbidding hardcoded standard dispatchers, unconfined bridge calls, and unmanaged GlobalScope instances across Kotlin/Native and Kotlin/JVM layers. 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: Hardcoded Dispatchers.IO/Main Leaking Across Darwin and Android FFI Boundaries Causing Deadlocks and Crashes 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	Hardcoded Dispatchers.IO/Main Leaking Across Darwin and Android FFI Boundaries Causing Deadlocks and Crashes	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 inject a dedicated CoroutineDispatchers interface (providing main, io, default, unconfined) rather than referencing Dispatchers.IO or Dispatchers.Main directly in commonMain.

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.