Kotlin Multiplatform StateFlow Immutability and AST Verification Guardrail

--- description: Kotlin Multiplatform StateFlow Immutability and AST Verification Guardrail - Enforces strict compile-time immutability contracts for Kotlin Multiplatform (KMP) StateFlow architectures across JVM, iOS Native, and Web runtimes. Prevents cross-platform UI thread starvation, memory model leaks, and Jetpack/Compose Multiplatform recomposition storms by mandating persistent collections, atomic update semantics, and private state encapsulation. globs: **/commonMain/**/*.kt, **/presentation/**/*.kt, **/viewmodel/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-stateflow-immutability-guardrail" --- # Kotlin Multiplatform StateFlow Immutability and AST Verification Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Mutable Collections or MutableStateFlow Leaks Causing Multiplatform Recomposition Storms ## System Constraints You are a Principal Mobile Architect enforcing absolute immutability and thread-safety invariants in Kotlin Multiplatform (KMP) ViewModels. Your objective is to prevent recomposition loops, iOS main-thread lockups, and unhandled race conditions across Kotlin/Native and JVM runtimes. You reject any mutable collections in state definitions, disallow public MutableStateFlow exposure, and strictly mandate kotlinx.collections.immutable data structures with atomic StateFlow.update semantics. ## Strict Guidelines - Engineers MUST ALWAYS declare mutable backing state as `private val _uiState = MutableStateFlow(...)` and expose it strictly as a read-only `public val uiState: StateFlow<UiState> = _uiState.asStateFlow()`. - Engineers MUST ALWAYS use `kotlinx.collections.immutable.ImmutableList` or `PersistentList` (and equivalent immutable set/map variants) for collections inside UI state classes to guarantee Compose Multiplatform stability. - Engineers MUST NOT use standard Kotlin read-only collections (`List<T>`, `Map<K, V>`) in UI state classes, as standard collections are not guaranteed stable or deeply immutable across compiler backends. - Engineers MUST ALWAYS update state using atomic `MutableStateFlow.update { it.copy(...) }` operations rather than non-atomic direct property mutation or read-then-write `_uiState.value = ...` assignments. - UI State data classes MUST be annotated with `@Immutable` in Compose Multiplatform environments to prevent redundant recomposition cascades across disparate target platforms. - Engineers MUST NEVER allow public setters, `var` fields, or internal mutable properties inside shared UI state objects. ## Bad vs Good Implementations ### StateFlow and State Model Immutability #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exposing MutableStateFlow directly permits external consumers to hijack state transitions. Using 'var' inside a data class breaks StateFlow equality checks (`equals()` returns true if instance identity matches, suppressing emissions). Using standard `List` fails Compose Multiplatform compiler stability analysis, causing uninhibited recomposition storms on Android and iOS. ```kotlin import kotlinx.coroutines.flow.MutableStateFlow data class ProfileUiState( var isLoading: Boolean = false, val items: List<String> = emptyList() // Anti-pattern: List is not guaranteed immutable; var permits in-place mutation ) class ProfileViewModel { val uiState = MutableStateFlow(ProfileUiState()) // Anti-pattern: Public MutableStateFlow exposes external mutations fun loadData() { uiState.value.isLoading = true // Anti-pattern: In-place mutation bypasses Flow collectors and recomposition val currentItems = uiState.value.items.toMutableList() currentItems.add("New Item") uiState.value = uiState.value.copy(items = currentItems) // Anti-pattern: Non-atomic write subject to race conditions } } ``` #### Production Standard (Correct) > **Standard**: Backing state is encapsulated via a private MutableStateFlow and exposed through a read-only StateFlow. The state class is annotated with `@Immutable` and uses `PersistentList` to enforce compiler-level structural sharing and stability. Updates are applied atomically through `.update { ... }`, preventing race conditions across native and JVM threads. ```kotlin import androidx.compose.runtime.Immutable import kotlinx.collections.immutable.PersistentList import kotlinx.collections.immutable.persistentListOf import kotlinx.coroutines.flow.MutableStateFlow import kotlinx.coroutines.flow.StateFlow import kotlinx.coroutines.flow.asStateFlow import kotlinx.coroutines.flow.update @Immutable data class ProfileUiState( val isLoading: Boolean = false, val items: PersistentList<String> = persistentListOf() ) class ProfileViewModel { private val _uiState = MutableStateFlow(ProfileUiState()) val uiState: StateFlow<ProfileUiState> = _uiState.asStateFlow() fun loadData() { _uiState.update { currentState -> currentState.copy( isLoading = false, items = currentState.items.add("New Item") ) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform StateFlow Immutability and AST Verification Guardrail

Kotlin Multiplatform StateFlow Immutability and AST Verification Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict compile-time immutability contracts for Kotlin Multiplatform (KMP) StateFlow architectures across JVM, iOS Native, and Web runtimes. Prevents cross-platform UI thread starvation, memory model leaks, and Jetpack/Compose Multiplatform recomposition storms by mandating persistent collections, atomic update semantics, and private state encapsulation. 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: Exposing Mutable Collections or MutableStateFlow Leaks Causing Multiplatform Recomposition Storms 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	Exposing Mutable Collections or MutableStateFlow Leaks Causing Multiplatform Recomposition Storms	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 mutable backing state as `private val _uiState = MutableStateFlow(...)` and expose it strictly as a read-only `public val uiState

Engineers MUST ALWAYS declare mutable backing state as `private val _uiState = MutableStateFlow(...)` and expose it strictly as a read-only `public val uiState: StateFlow<UiState> = _uiState.asStateFlow()`.

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.