KMP Coroutine Bridge: Deterministic Cancellation and Stack-Preserved Exception Architecture

--- description: KMP Coroutine Bridge: Deterministic Cancellation and Stack-Preserved Exception Architecture - Enforces strict boundary contracts across Kotlin Multiplatform and Swift concurrency. Guarantees bi-directional cancellation propagation, prevents fatal unhandled Kotlin exceptions across the Objective-C/Swift bridge, and preserves multi-runtime stack traces. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-hierarchical-coroutine-native-bridge-standard" --- # KMP Coroutine Bridge: Deterministic Cancellation and Stack-Preserved Exception Architecture > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unchecked Suspend Export Leaking Background Jobs and Triggering Bridge SIGABRTs ## System Constraints You are a Principal Mobile Architect enforcing the Kotlin Multiplatform Hierarchical Coroutine Exception Native-Bridge Standard. You must mandate strict structured concurrency across the Kotlin-to-Apple ABI boundary. Require complete cancellation propagation between Swift Tasks and Kotlin Jobs, stack-preserving error wrapping, and isolation of unhandled runtime exceptions. ## Strict Guidelines - Engineers MUST ALWAYS bind Swift `withTaskCancellationHandler` to the underlying Kotlin coroutine `Job.cancel()` to prevent orphan background execution. - Engineers MUST NOT expose raw Kotlin `suspend` functions across the Objective-C bridge without an automated tool (e.g., SKIE) or explicit native wrapper handling `CancellationException` mapping. - Engineers MUST NEVER allow raw `CancellationException` to propagate as an unhandled error into Swift catch blocks; it MUST map deterministically to Swift's `CancellationError`. - Code MUST install a boundary `CoroutineExceptionHandler` on every root `CoroutineScope` bridging to native platforms to prevent `SIGABRT` crashes from unhandled coroutine faults. - Services MUST capture and serialize the Kotlin exception's thread stack trace into a structured `NativeBridgeError` payload before crossing the Kotlin Native / Objective-C boundary. - Components NEVER catch `Throwable` indiscriminately inside Kotlin suspend logic without rethrowing `CancellationException` immediately. ## Bad vs Good Implementations ### Cross-Runtime Cancellation & Stack Preservation Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting raw suspend functions across the Apple bridge causes unhandled exceptions to crash the process with SIGABRT (or produce empty NSErrors without Kotlin stack traces). Furthermore, cancelling the calling Swift Task fails to cancel the underlying Kotlin Job. ```kotlin // Shared KMP Code (iosMain) import kotlinx.coroutines.* class RepositoryBridge(private val scope: CoroutineScope) { // ANTI-PATTERN: Direct suspend export without cancellation binding // or stack preservation. Kotlin runtime crash causes uncatchable SIGABRT in iOS. suspend fun fetchAccountData(accountId: String): String { return withContext(Dispatchers.Default) { if (accountId.isEmpty()) { throw IllegalArgumentException("Invalid Account ID") // Crashes host process } delay(1000) "Account Details: $accountId" } } } ``` #### Production Standard (Correct) > **Standard**: Wraps results into a deterministic union type, preserves the full Kotlin coroutine stack trace via `stackTraceToString()`, preserves `CancellationException` flow, and returns a `NativeCancellable` that Swift `withTaskCancellationHandler` can trigger. ```kotlin // Shared KMP Code (iosMain) import kotlinx.coroutines.* import kotlin.coroutines.cancellation.CancellationException sealed class BridgeResult<out T> { data class Success<T>(val data: T) : BridgeResult<T>() data class Failure(val error: BridgeError) : BridgeResult<Nothing>() } data class BridgeError( val domain: String, val message: String, val originalStack: String ) interface NativeCancellable { fun cancel() } class RepositoryBridge( private val baseScope: CoroutineScope ) { fun fetchAccountData( accountId: String, onResult: (BridgeResult<String>) -> Unit ): NativeCancellable { val job = baseScope.launch(Dispatchers.Default) { try { if (accountId.isEmpty()) { throw IllegalArgumentException("Invalid Account ID") } delay(1000) onResult(BridgeResult.Success("Account Details: $accountId")) } catch (e: CancellationException) { // Structured concurrency preservation: do not wrap cancellation throw e } catch (t: Throwable) { onResult( BridgeResult.Failure( BridgeError( domain = t::class.simpleName ?: "Throwable", message = t.message ?: "Unknown error", originalStack = t.stackTraceToString() ) ) ) } } return object : NativeCancellable { override fun cancel() { job.cancel(CancellationException("Swift Task cancelled")) } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Coroutine Bridge: Deterministic Cancellation and Stack-Preserved Exception Architecture

KMP Coroutine Bridge: Deterministic Cancellation and Stack-Preserved Exception Architecture defines an industrial-grade behavioral standard for mobile engineering. Enforces strict boundary contracts across Kotlin Multiplatform and Swift concurrency. Guarantees bi-directional cancellation propagation, prevents fatal unhandled Kotlin exceptions across the Objective-C/Swift bridge, and preserves multi-runtime stack traces. 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: Unchecked Suspend Export Leaking Background Jobs and Triggering Bridge SIGABRTs 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	Unchecked Suspend Export Leaking Background Jobs and Triggering Bridge SIGABRTs	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 `withTaskCancellationHandler` to the underlying Kotlin coroutine `Job.cancel()` to prevent orphan background execution.

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.