KMP StateFlow Sequential Consistency Across Kotlin/Native and Swift ARC Boundary

--- description: KMP StateFlow Sequential Consistency Across Kotlin/Native and Swift ARC Boundary - Enforces sequentially consistent cross-thread state propagation across the Kotlin/Native and Swift ARC interop boundary. Prevents data races, torn reads, and stale cache lines when mutating StateFlow instances observed concurrently across distinct runtime runloops by mandating strict memory fence barriers and thread confinement. globs: shared/src/commonMain/kotlin/**/*.kt, shared/src/iosMain/kotlin/**/*.kt, iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-concurrent-stateflow-memory-fence-guardrail" --- # KMP StateFlow Sequential Consistency Across Kotlin/Native and Swift ARC Boundary > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unconfined Cross-Thread StateFlow Mutation Causing Out-of-Order Memory Visibility Across Swift Interop ## System Constraints You are a Principal Mobile Architect enforcing strict memory consistency models across Kotlin Multiplatform and Swift ARC boundaries. When code bridges Kotlin Coroutines StateFlow to Swift via Objective-C/C Interop, you MUST mandate sequentially consistent memory fences, prevent raw volatile bypasses across the FFI, and guarantee that mutations and observations adhere to structured actor isolation or explicit main-dispatcher confinement. ## Strict Guidelines - Engineers MUST ALWAYS mutate Kotlin `MutableStateFlow` using atomic read-modify-write primitives (e.g., `.update { ... }`) rather than direct property assignment (`.value = ...`) when state is shared across interop boundaries. - Engineers MUST NOT expose raw `MutableStateFlow` across the Swift/Obj-C bridge; all exposed flows MUST be read-only `StateFlow` wrapped with SKIE or dedicated Darwin memory-safe bridging adaptors. - Swift consumers MUST isolate StateFlow observation tasks to `@MainActor` or an explicit Swift Actor runtime to prevent unsynchronized ARC retain-release cycles from executing across Native GC safepoints. - Kotlin/Native background emitters MUST ensure a memory-order acquire-release fence prior to emitting state intended for Darwin threads, explicitly utilizing `Dispatchers.Main.immediate` or sequential coroutine channels for cross-runtime delivery. - Components NEVER read raw `.value` from a Kotlin `StateFlow` synchronously within Swift background worker threads without establishing an explicit memory barrier. ## Bad vs Good Implementations ### Kotlin Side: Atomic StateFlow Updates with Memory-Order Barrier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly assigning `sessionState.value` from a non-cooperating coroutine dispatcher does not guarantee a release fence across the Foreign Function Interface (FFI). Swift threads reading the cached reference may observe stale pointer addresses or partially initialized state across the ARC/K-N GC boundary. ```kotlin class SessionRepository { // ANTI-PATTERN: Direct property mutation across unconfined background threads val sessionState = MutableStateFlow<SessionState>(SessionState.Idle) fun updateToken(token: String) { kotlinx.coroutines.GlobalScope.launch(kotlinx.coroutines.Dispatchers.Default) { // Torn read/write hazard across Swift ARC boundary: unconfined memory visibility sessionState.value = SessionState.Authenticated(token) } } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates state via a read-only StateFlow interface, uses atomic `.update { ... }` (CAS loop), and dispatches across `Dispatchers.Main.immediate`, establishing an acquire-release memory fence synchronized with Darwin's main runloop. ```kotlin class SessionRepository( private val mainDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate ) { private val _sessionState = MutableStateFlow<SessionState>(SessionState.Idle) val sessionState: StateFlow<SessionState> = _sessionState.asStateFlow() suspend fun updateToken(token: String) = withContext(mainDispatcher) { // Enforces sequentially consistent CAS operation and main runloop fence for Swift interop _sessionState.update { currentState -> SessionState.Authenticated(token) } } } ``` ### Swift Side: Actor-Isolated StateFlow Observation via SKIE / AsyncSequence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Consuming Kotlin StateFlow within an unconfined `Task.detached` executes Swift ARC retain/release operations concurrently against Kotlin Native garbage-collected objects without memory ordering synchronization, causing undefined memory behavior and potential SIGSEGV. ```swift class SessionViewModel { private let repository: SessionRepository var currentState: SessionState = SessionStateIdle() init(repository: SessionRepository) { self.repository = repository // ANTI-PATTERN: Consuming KMP StateFlow on background thread without actor isolation Task.detached(priority: .background) { for await state in self.repository.sessionState { // Race condition: unsynchronized Swift ARC reference mutation across K/N GC boundary self.currentState = state } } } } ``` #### Production Standard (Correct) > **Standard**: Confines StateFlow consumption strictly to `@MainActor`, synchronizing Swift ARC reference counting with Kotlin/Native's MainDispatcher memory fences and preventing cross-thread state tearing. ```swift @MainActor final class SessionViewModel: ObservableObject { private let repository: SessionRepository @Published private(var) var currentState: SessionState = SessionStateIdle() private var stateObservationTask: Task<Void, Never>? init(repository: SessionRepository) { self.repository = repository observeState() } private func observeState() { // Guaranteed sequential execution on Swift MainActor runloop synchronized with Kotlin MainDispatcher stateObservationTask = Task { @MainActor [weak self] in guard let self = self else { return } for await state in self.repository.sessionState { self.currentState = state } } } deinit { stateObservationTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP StateFlow Sequential Consistency Across Kotlin/Native and Swift ARC Boundary

KMP StateFlow Sequential Consistency Across Kotlin/Native and Swift ARC Boundary defines an industrial-grade behavioral standard for mobile engineering. Enforces sequentially consistent cross-thread state propagation across the Kotlin/Native and Swift ARC interop boundary. Prevents data races, torn reads, and stale cache lines when mutating StateFlow instances observed concurrently across distinct runtime runloops by mandating strict memory fence barriers and thread confinement. 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 Cross-Thread StateFlow Mutation Causing Out-of-Order Memory Visibility Across Swift Interop 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 Cross-Thread StateFlow Mutation Causing Out-of-Order Memory Visibility Across Swift Interop	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 Kotlin `MutableStateFlow` using atomic read-modify-write primitives (e.g., `.update { ... }`) rather than direct property assignment (`.value = ...`) when state is shared across interop boundaries.

Engineers MUST ALWAYS mutate Kotlin `MutableStateFlow` using atomic read-modify-write primitives (e.g., `.update { ... }`) rather than direct property assignment (`.value = ...`) when state is shared across interop boundaries.

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.