KMP Structured Coroutine Cancellation Propagation on iOS Main RunLoop

--- description: KMP Structured Coroutine Cancellation Propagation on iOS Main RunLoop - Standardizes Swift-Kotlin task cancellation bridging across the Kotlin/Native boundary to prevent unhandled CancellationException termination on the iOS Main RunLoop. Enforces explicit Task.withTaskCancellationHandler lifecycle coupling and translates Kotlin CancellationException into Swift's native CancellationError during high-frequency UI navigation transitions. globs: iosApp/**/*.swift, shared/src/commonMain/**/*.kt, shared/src/iosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-ios-coroutine-cancellation-propagation" --- # KMP Structured Coroutine Cancellation Propagation on iOS Main RunLoop > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Orphaned Kotlin Coroutines and Crashing iOS Runtimes via Unhandled CancellationException Across Swift Concurrency Bridges ## System Constraints You are a Principal Engineer enforcing strict KMP Structured Coroutine Cancellation Propagation on the iOS Main RunLoop. You mandate that any bridge between Swift Concurrency (Task/async-await) and Kotlin Coroutines explicitly binds the Swift Task cancellation lifecycle to the Kotlin Job via Task.withTaskCancellationHandler or SKIE wrapper abstractions. You forbid swallowing cancellation errors as generic failures, forbid unhandled CancellationException rethrowing into Objective-C interop layers, and require that all state-modifying cancellation sweeps cleanly release resources on Dispatchers.Main.immediate without blocking native UI navigation transitions. ## Strict Guidelines - Engineers MUST ALWAYS bridge Swift Task cancellation to Kotlin Job cancellation using Task.withTaskCancellationHandler or an established compiler-plugin abstraction (e.g., SKIE). - Engineers MUST ALWAYS intercept Kotlin CancellationException at the Swift interop boundary and rethrow Swift's native CancellationError() rather than treating it as an application-level NSError or letting it crash the iOS runtime. - Engineers MUST NOT invoke Kotlin suspend functions from Swift without managing the underlying Disposable/Cancellable handle when not utilizing automatic Swift Concurrency bridges. - Code SHOULD enforce that UI-bound coroutine scopes in shared code target Dispatchers.Main.immediate to guarantee synchronous cancellation dispatch during iOS navigation teardowns. - Services MUST ensure shared Flow collectors cleanly complete or close their underlying channels when the consuming Swift AsyncSequence or Combine publisher is cancelled during view pop/dismissal. - Components NEVER allow unhandled Kotlin exceptions originating from cancelled deferred tasks to escape into the iOS fatal error handler. ## Bad vs Good Implementations ### Bridging Swift Task Cancellation to Kotlin Coroutine Job with CancellationError Mapping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to register a cancellation handler with Swift Concurrency. When a user pops the view controller during a network fetch, the Swift Task cancels but the Kotlin coroutine keeps executing on the shared pool. When the Kotlin coroutine finally observes cancellation, it throws CancellationException across the ObjC boundary as a generic NSError, failing to trigger Swift's native cancellation flow and polluting UI telemetry. ```swift // BAD: Direct async bridge execution without task cancellation binding or error translation func loadUserProfile(userId: String) async throws -> UserProfile { do { // If the Swift Task is cancelled during navigation pop, the Kotlin coroutine continues running. // If Kotlin finishes with CancellationException, it surfaces as an unhandled KotlinException NSError, // causing spurious error alerts or fatal runtime unwrapping. let profile = try await userViewModel.fetchProfile(id: userId) return profile } catch { // Swallows cancellation or misidentifies it as an active network/domain error throw error } } ``` #### Production Standard (Correct) > **Standard**: Attaches a task cancellation handler via withTaskCancellationHandler so that when Swift cancels the Task (e.g., view pop or navigation transition), the Kotlin job is explicitly cancelled via its handle. It intercepts CancellationException across the interop boundary and maps it directly to Swift's native CancellationError, respecting structured concurrency semantics without triggering unhandled error crashes. ```swift // GOOD: Explicit cancellation propagation bridging Swift Task to Kotlin Job and mapping CancellationException func loadUserProfile(userId: String) async throws -> UserProfile { let handle = AtomicReference<SharedCommonCancellable?>(nil) return try await withTaskCancellationHandler { try Task.checkCancellation() do { return try await withCheckedThrowingContinuation { continuation in let cancellable = userViewModel.fetchProfileCancellable(id: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } handle.set(cancellable) } } catch let nsError as NSError where nsError.isKotlinCancellationException { throw CancellationError() } } onCancel: { handle.get()?.cancel() } } extension NSError { var isKotlinCancellationException: Bool { domain == "KotlinException" && userInfo["KotlinExceptionType"] as? String == "kotlinx.coroutines.CancellationException" } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Structured Coroutine Cancellation Propagation on iOS Main RunLoop

KMP Structured Coroutine Cancellation Propagation on iOS Main RunLoop defines an industrial-grade behavioral standard for mobile engineering. Standardizes Swift-Kotlin task cancellation bridging across the Kotlin/Native boundary to prevent unhandled CancellationException termination on the iOS Main RunLoop. Enforces explicit Task.withTaskCancellationHandler lifecycle coupling and translates Kotlin CancellationException into Swift's native CancellationError during high-frequency UI navigation transitions. 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: Leaking Orphaned Kotlin Coroutines and Crashing iOS Runtimes via Unhandled CancellationException Across Swift Concurrency Bridges 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	Leaking Orphaned Kotlin Coroutines and Crashing iOS Runtimes via Unhandled CancellationException Across Swift Concurrency Bridges	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 bridge Swift Task cancellation to Kotlin Job cancellation using Task.withTaskCancellationHandler or an established compiler-plugin abstraction (e.g., SKIE).

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.