KMP Compose Mutex-Safe Main Dispatcher Pinning & Swift Affinity Contract

--- description: KMP Compose Mutex-Safe Main Dispatcher Pinning & Swift Affinity Contract - Enforces strict thread-affinity contracts between Compose Multiplatform runtime snapshots and iOS Swift Concurrency dispatchers. Prevents hard UI freezes, CADisplayLink starvation, and Darwin runloop deadlocks caused by unconfined coroutine hopping and unpinned Mutex acquisitions during state reconciliation. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/presentation/**/*.kt, **/viewmodel/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-mutex-safe-main-dispatcher-pinning" --- # KMP Compose Mutex-Safe Main Dispatcher Pinning & Swift Affinity Contract > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Dispatcher Mutex Contention and Unpinned Snapshot State Mutation on iOS Darwin Main Runloop ## System Constraints You are a Principal Software Architect enforcing zero-deadlock concurrency invariants between Kotlin Multiplatform (KMP) Compose runtime and Apple Darwin/Swift runloops. You strictly forbid unpinned Mutex acquisitions across dispatcher hops, synchronous blocking bridging (runBlocking) on UI threads, and mutating Compose snapshot state outside Dispatchers.Main.immediate. ## Strict Guidelines - Engineers MUST ALWAYS mutate Compose runtime state and publish UI-bound StateFlow emissions using Dispatchers.Main.immediate to guarantee lock-free synchronous dispatch on the Darwin runloop. - Engineers MUST NEVER hold a kotlinx.coroutines.sync.Mutex lock across an unconfined or background dispatcher transition (e.g., withContext(Dispatchers.Default) inside a withLock block). - Engineers MUST NEVER invoke runBlocking on Darwin's main thread (iOS MainActor) to bridge suspend functions to Swift; all boundary crossings MUST use asynchronous wrappers (such as SKIE or Task-based callbacks). - Code MUST isolate computational Mutex synchronization to non-main worker dispatchers and transfer immutable payloads to the UI thread via non-blocking channels or state flows. - Engineers MUST NOT synchronously await Swift MainActor tasks from inside Kotlin Compose snapshot applying observers, as this introduces bidirectional inversion of control deadlocks with CADisplayLink. - Shared mutable repositories MUST enforce single-direction lock acquisition order: Domain Lock -> Dispatcher Hop -> Snapshot Mutation, NEVER acquiring a Mutex from within a Compose composable context. ## Bad vs Good Implementations ### Preventing Mutex Hop Deadlock & Enforcing Dispatchers.Main.immediate Pinning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Acquiring a Mutex and then suspending across `Dispatchers.Default` leads to cooperative thread pool starvation. When updating Compose `mutableStateOf` without `Dispatchers.Main.immediate`, the iOS rendering pass (`CADisplayLink`) attempts to acquire the snapshot lock while Darwin's main thread is blocked awaiting coroutine continuation, causing an unrecoverable UI deadlock. ```kotlin class BadProfileViewModel : ViewModel() { private val mutex = Mutex() var uiState by mutableStateOf(ProfileUiState()) private set // CRITICAL BUG: Acquires Mutex, hops to Default, mutations occur without Main pinning // On iOS, this causes runloop deadlocks when Compose snapshot commit collides with Swift MainActor. fun updateProfile(name: String) { viewModelScope.launch { mutex.withLock { val processed = withContext(Dispatchers.Default) { computeNormalizedProfile(name) } // Violated: Snapshot mutated on arbitrary thread after suspension uiState = uiState.copy(name = processed) } } } private fun computeNormalizedProfile(name: String) = name.trim().lowercase() } ``` #### Production Standard (Correct) > **Standard**: Computation is offloaded prior to lock acquisition, eliminating held locks across dispatcher transitions. State mutation is explicitly routed through `Dispatchers.Main.immediate` and backed by `StateFlow.update`, preventing priority inversion between the Compose snapshot system and the Darwin main queue. ```kotlin class SafeProfileViewModel( private val defaultDispatcher: CoroutineDispatcher = Dispatchers.Default ) : ViewModel() { private val mutex = Mutex() private val _uiState = MutableStateFlow(ProfileUiState()) val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow() fun updateProfile(name: String) { viewModelScope.launch(Dispatchers.Main.immediate) { // 1. Offload heavy computation outside the main thread and without holding lock val processed = withContext(defaultDispatcher) { computeNormalizedProfile(name) } // 2. Critical section is atomic, localized, and pinned to Dispatchers.Main.immediate mutex.withLock { _uiState.update { currentState -> currentState.copy(name = processed) } } } } private fun computeNormalizedProfile(name: String) = name.trim().lowercase() } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Mutex-Safe Main Dispatcher Pinning & Swift Affinity Contract

KMP Compose Mutex-Safe Main Dispatcher Pinning & Swift Affinity Contract defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread-affinity contracts between Compose Multiplatform runtime snapshots and iOS Swift Concurrency dispatchers. Prevents hard UI freezes, CADisplayLink starvation, and Darwin runloop deadlocks caused by unconfined coroutine hopping and unpinned Mutex acquisitions during state reconciliation. 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: Cross-Dispatcher Mutex Contention and Unpinned Snapshot State Mutation on iOS Darwin Main Runloop 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	Cross-Dispatcher Mutex Contention and Unpinned Snapshot State Mutation on iOS Darwin Main Runloop	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 mutate Compose runtime state and publish UI-bound StateFlow emissions using Dispatchers.Main.immediate to guarantee lock-free synchronous dispatch on the Darwin runloop.

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.