Kotlin Multiplatform StateFlow to Swift Concurrency Bridge Invariants

--- description: Kotlin Multiplatform StateFlow to Swift Concurrency Bridge Invariants - Enforces non-blocking cooperative execution and bidirectional cancellation semantics when bridging Kotlin StateFlow/SharedFlow to Swift AsyncSequence. Prevents thread pool starvation in Darwin's cooperative thread pool and eliminates cyclic reference memory leaks across K/N Garbage Collector and Swift ARC boundaries. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, **/*FlowBridge*.swift, **/*ViewModel*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-stateflow-swift-concurrency-bridge" --- # Kotlin Multiplatform StateFlow to Swift Concurrency Bridge Invariants > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronous Interop Blocking and Unbridled Flow Subscription Leaks ## System Constraints You are a Principal Mobile Architect enforcing rock-solid concurrency and memory invariants across Kotlin Multiplatform (K/N) and Swift (Darwin). Never allow synchronous blocking bridges, unchecked Kotlin Coroutine Job leaks, or retain cycles between Swift closures and Kotlin Garbage Collection heaps. ## Strict Guidelines - Engineers MUST ALWAYS bind Swift AsyncStream/AsyncSequence lifecycle to Kotlin Coroutine Job cancellation via continuation.onTermination or Task cancellation handlers. - Engineers MUST NOT block Swift's cooperative thread pool using semaphores, dispatch group waits, or synchronous RunLoop execution waiting for Kotlin coroutines. - Code SHOULD enforce weak reference captures ([weak self]) inside Swift observation closures passed into KMP completion blocks to break ARC-K/N cross-runtime cyclic references. - Services MUST ensure Kotlin Native flows are collected on Dispatchers.Default or Dispatchers.Main.immediate and mapped to MainActor in Swift without nesting DispatchQueue.main.sync. - Components NEVER bridge unbounded SharedFlow without explicit buffer overflow policies (BufferOverflow.DROP_OLDEST or backpressure handling), as rapid emissions can trigger memory exhaustion in Swift's interop layer. ## Bad vs Good Implementations ### Bridging Kotlin StateFlow to Swift AsyncStream with Lifecycle Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Retaining 'self' strongly inside the Kotlin collector lambda creates an uncollectible cross-heap reference cycle between ARC and Kotlin/Native GC. Using DispatchQueue.main.sync risks deadlock on Darwin threads, and failing to hook into Task cancellation leaks active coroutines in the K/N runtime. ```swift import Shared import Foundation final class LeakyStateBridge: ObservableObject { @Published var state: ViewState = .idle private var closer: Closeable? // or Kotlin Job func bind(flow: KotlinStateFlow<ViewState>) { // CRITICAL BUG: Strong self capture retains Swift class in Kotlin heap // No cancellation bridge when Task or UI scope is destroyed self.closer = flow.watch { state in DispatchQueue.main.sync { // CRITICAL BUG: sync call causes deadlock/thread pool starvation self.state = state } } } } ``` #### Production Standard (Correct) > **Standard**: The good example encapsulates flow consumption within an AsyncStream that hooks termination directly into Kotlin's Job cancellation. Weak reference capture prevents cross-runtime retain cycles, and consuming on the @MainActor ensures lock-free UI mutations without thread starvation. ```swift import Shared import Foundation extension KotlinStateFlow { func asAsyncStream() -> AsyncStream<T> { AsyncStream(T.self) { continuation in // Spawn observation with deterministic job tracking let job = FlowAdapterKt.collectFlow(self) { item in continuation.yield(item) } // Invariant: Cancel Kotlin Job as soon as Swift stream terminates continuation.onTermination = { @Sendable _ in job.cancel(cause: nil) } } } } @MainActor final class ResilientStateViewModel: ObservableObject { @Published private(set) var state: ViewState = .idle private var streamTask: Task<Void, Never>? func bind(flow: KotlinStateFlow<ViewState>) { streamTask?.cancel() streamTask = Task { [weak self] in for await item in flow.asAsyncStream() { guard !Task.isCancelled else { break } self?.state = item } } } deinit { streamTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform StateFlow to Swift Concurrency Bridge Invariants

Kotlin Multiplatform StateFlow to Swift Concurrency Bridge Invariants defines an industrial-grade behavioral standard for mobile engineering. Enforces non-blocking cooperative execution and bidirectional cancellation semantics when bridging Kotlin StateFlow/SharedFlow to Swift AsyncSequence. Prevents thread pool starvation in Darwin's cooperative thread pool and eliminates cyclic reference memory leaks across K/N Garbage Collector and Swift ARC boundaries. 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: Synchronous Interop Blocking and Unbridled Flow Subscription Leaks 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	Synchronous Interop Blocking and Unbridled Flow Subscription Leaks	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 bind Swift AsyncStream/AsyncSequence lifecycle to Kotlin Coroutine Job cancellation via continuation.onTermination or Task cancellation handlers.

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.