KMP Shared StateFlow Cross-Platform Coroutine Exception Boundary Standard

--- description: KMP Shared StateFlow Cross-Platform Coroutine Exception Boundary Standard - Enforces deterministic coroutine exception containment within Kotlin Multiplatform (KMP) shared state machines driving StateFlow observables. Prevents unhandled asynchronous exceptions from bypassing native boundary boundaries, which triggers uncaught fatal signals (SIGABRT/Crashlytics fatals) on iOS runtimes and unhandled ThreadDeath/Crash on Android UI main loops. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-shared-stateflow-coroutine-exception-boundary-standard" --- # KMP Shared StateFlow Cross-Platform Coroutine Exception Boundary Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Uncontained coroutine scope launches propagating uncaught exceptions across Swift/Kotlin boundaries causing instant iOS SIGABRT termination ## System Constraints You are a Principal Mobile Architect enforcing strict exception boundary encapsulation for Kotlin Multiplatform (KMP) coroutines exposing StateFlow to platform consumers (Swift/Obj-C and Android Jetpack Compose). You must reject any shared coroutine launch that lacks explicit CoroutineExceptionHandler isolation or exposes bare Flow streams without catch blocks, as uncaught exceptions crossing Darwin interop boundaries terminate the iOS host process via SIGABRT without Swift do-catch interceptability. ## Strict Guidelines - Engineers MUST ALWAYS attach a top-level `CoroutineExceptionHandler` to the shared `CoroutineScope` context or explicitly encapsulate execution within `runCatching` inside `launch` blocks. - Engineers MUST NEVER allow unhandled exceptions to escape into platform-exposed `StateFlow` or `SharedFlow` operators; errors must be transformed into discrete domain state models (e.g., `UiState.Error`). - Engineers MUST ALWAYS configure downstream flow pipelines with `.catch { e -> emit(UiState.Error(e)) }` prior to calling `.stateIn()` to avoid uncaught upstream flow termination. - Shared ViewModels and state machines MUST use `SupervisorJob` combined with an isolated `CoroutineExceptionHandler` rather than standard `Job` to prevent child failures from cancelling entire host state machines. - Components consuming shared flows on iOS NEVER receive raw Kotlin throwing exceptions; APIs must wrap execution in Swift-safe result wrappers or delegate to sanitized StateFlow instances. - Coroutines launched in `commonMain` intended for consumption by Swift MUST NOT rely on Swift `try/catch` bridges, as asynchronous Kotlin coroutine exceptions bypass Swift Objective-C exception interop. ## Bad vs Good Implementations ### Exception Boundary Containment in KMP Shared ViewModel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Launching without a SupervisorJob and CoroutineExceptionHandler inside a shared KMP class means any network failure or JSON deserialization error thrown asynchronously will hit the Darwin host unhandled, immediately aborting the iOS app with SIGABRT. ```kotlin class UserProfileViewModel(private val repository: UserRepository) { // ANTI-PATTERN: Default Job cancels scope on any child exception. // Missing CoroutineExceptionHandler causes uncaught Kotlin exceptions to terminate iOS process. val viewModelScope = CoroutineScope(Dispatchers.Main) private val _uiState = MutableStateFlow<UiState>(UiState.Idle) val uiState: StateFlow<UiState> = _uiState.asStateFlow() fun fetchUserProfile(userId: String) { viewModelScope.launch { // Uncaught exception directly crashes iOS host with SIGABRT val profile = repository.fetchRemoteUser(userId) _uiState.value = UiState.Success(profile) } } } ``` #### Production Standard (Correct) > **Standard**: Combines SupervisorJob and a CoroutineExceptionHandler with defensive runCatching. Async failures are strictly encapsulated into the UiState.Error model without leaking raw exceptions across KMP interop bridges. ```kotlin class UserProfileViewModel( private val repository: UserRepository, mainDispatcher: CoroutineDispatcher = Dispatchers.Main ) { // PRODUCTION FIX: SupervisorJob prevents scope teardown; ExceptionHandler halts unhandled propagation. private val exceptionHandler = CoroutineExceptionHandler { _, throwable -> _uiState.value = UiState.Error(throwable.message ?: "Unknown error occurred") } val viewModelScope = CoroutineScope(SupervisorJob() + mainDispatcher + exceptionHandler) private val _uiState = MutableStateFlow<UiState>(UiState.Idle) val uiState: StateFlow<UiState> = _uiState.asStateFlow() fun fetchUserProfile(userId: String) { viewModelScope.launch { runCatching { _uiState.value = UiState.Loading repository.fetchRemoteUser(userId) }.onSuccess { _uiState.value = UiState.Success(it) }.onFailure { // Contained domain failure mapped safely into UI state _uiState.value = UiState.Error(it.message ?: "Failed to load profile") } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Shared StateFlow Cross-Platform Coroutine Exception Boundary Standard

KMP Shared StateFlow Cross-Platform Coroutine Exception Boundary Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic coroutine exception containment within Kotlin Multiplatform (KMP) shared state machines driving StateFlow observables. Prevents unhandled asynchronous exceptions from bypassing native boundary boundaries, which triggers uncaught fatal signals (SIGABRT/Crashlytics fatals) on iOS runtimes and unhandled ThreadDeath/Crash on Android UI main loops. 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: Uncontained coroutine scope launches propagating uncaught exceptions across Swift/Kotlin boundaries causing instant iOS SIGABRT termination 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	Uncontained coroutine scope launches propagating uncaught exceptions across Swift/Kotlin boundaries causing instant iOS SIGABRT termination	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 attach a top-level `CoroutineExceptionHandler` to the shared `CoroutineScope` context or explicitly encapsulate execution within `runCatching` inside `launch` blocks.

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.