Kotlin Multiplatform 2.1 StateFlow Thread Confinement and Dispatcher Synchronization

--- description: Kotlin Multiplatform 2.1 StateFlow Thread Confinement and Dispatcher Synchronization - Enforces strict thread confinement and atomic mutation boundaries for Coroutine StateFlow across Darwin Grand Central Dispatch and Android UI dispatchers in Kotlin Multiplatform 2.1. Eliminates memory tearing, re-entrancy deadlocks, and Swift/Kotlin memory model race conditions when bridge layers evaluate shared reactive state. globs: **/commonMain/**/*.kt, **/androidMain/**/*.kt, **/iosMain/**/*.kt, **/darwinMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-21-stateflow-thread-confinement-standard" --- # Kotlin Multiplatform 2.1 StateFlow Thread Confinement and Dispatcher Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Thread MutableStateFlow Mutation and Unconfined Dispatcher Bridges Across Darwin GCD and Android Main ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform 2.1 Coroutine StateFlow Thread Confinement. Mandate invariants that eliminate thread safety violations, lock inversions, and memory tearing between Darwin GCD queues and Android Dispatchers.Main. Never permit direct exposed MutableStateFlow mutations across platform boundaries; enforce strict single-thread update loops via atomic updates and confined CoroutineScope lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS expose read-only StateFlow<T> interfaces across common boundaries, encapsulating MutableStateFlow<T> strictly within domain viewmodels or state containers. - Engineers MUST ALWAYS mutate StateFlow values using atomic operators like MutableStateFlow.update { ... } or MutableStateFlow.compareAndSet to prevent check-then-act memory tearing across concurrent threads. - Engineers MUST NOT collect or mutate shared StateFlow instances on unconfined dispatchers (such as Dispatchers.Unconfined or custom Darwin background GCD queues without serial confinement). - Code SHOULD explicitly route UI-bound Darwin observation through a dedicated main-thread bridge or Darwin-safe wrapper (e.g., SKIE or explicit flow collectors confined to Dispatchers.Main.immediate). - Services MUST ensure that state updates initiated from background I/O operations (Dispatchers.IO) switch execution context before mutating any StateFlow consumed synchronously by platform UI frameworks. - Components NEVER execute blocking operations inside StateFlow subscription blocks, preventing lock inversions between Grand Central Dispatch main queues and Kotlin Coroutine dispatchers. ## Bad vs Good Implementations ### StateFlow Atomic Mutation and Platform Dispatcher Confinement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Public MutableStateFlow permits concurrent Darwin and Android callers to read and write without isolation. Direct property assignment (uiState.value = ...) introduces race conditions and memory tearing. Launching on Dispatchers.IO and writing to a flow directly consumed by Darwin GCD bridges triggers lock inversions and unpredictable cross-thread scheduling overhead. ```kotlin class ProfileViewModel : CoroutineScope { override val coroutineContext = Dispatchers.Default // ANTI-PATTERN: Public MutableStateFlow allows external platforms to mutate from any thread val uiState = MutableStateFlow(ProfileState.Initial) fun updateUsername(newName: String) { // ANTI-PATTERN: Direct property setter causes check-then-act memory tearing under concurrent calls val current = uiState.value if (current is ProfileState.Loaded) { uiState.value = current.copy(username = newName) } } fun loadData() { // ANTI-PATTERN: Mutating state directly from unconfined/IO threads without synchronization GlobalScope.launch(Dispatchers.IO) { val profile = repository.fetch() uiState.value = ProfileState.Loaded(profile.name) } } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates MutableStateFlow, ensures all updates use atomic CAS semantics via update { }, and bounds UI state emissions to Dispatchers.Main.immediate with lifecycle-managed cancellation. Darwin bridges receive safe, sequenced emissions without memory tearing or lock inversion across GCD runloops. ```kotlin class ProfileViewModel( private val repository: ProfileRepository, private val mainDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate ) { private val scope = CoroutineScope(SupervisorJob() + mainDispatcher) // PROD INVARIANT: Mutable state is encapsulated; public consumer sees strictly immutable StateFlow private val _uiState = MutableStateFlow<ProfileState>(ProfileState.Initial) val uiState: StateFlow<ProfileState> = _uiState.asStateFlow() fun updateUsername(newName: String) { // PROD INVARIANT: update { } provides lock-free atomic compare-and-set _uiState.update { current -> when (current) { is ProfileState.Loaded -> current.copy(username = newName) else -> current } } } fun loadData() { scope.launch { // Background IO is isolated; state update guarantees main-thread confinement val profile = withContext(Dispatchers.IO) { repository.fetch() } _uiState.update { ProfileState.Loaded(profile.name) } } } fun clear() { scope.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 StateFlow Thread Confinement and Dispatcher Synchronization

Kotlin Multiplatform 2.1 StateFlow Thread Confinement and Dispatcher Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread confinement and atomic mutation boundaries for Coroutine StateFlow across Darwin Grand Central Dispatch and Android UI dispatchers in Kotlin Multiplatform 2.1. Eliminates memory tearing, re-entrancy deadlocks, and Swift/Kotlin memory model race conditions when bridge layers evaluate shared reactive state. 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-Thread MutableStateFlow Mutation and Unconfined Dispatcher Bridges Across Darwin GCD and Android Main 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-Thread MutableStateFlow Mutation and Unconfined Dispatcher Bridges Across Darwin GCD and Android Main	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 expose read-only StateFlow<T> interfaces across common boundaries, encapsulating MutableStateFlow<T> strictly within domain viewmodels or state containers.

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.