KMP 2.1 SKIE Bidirectional Cancellation and Error Mapping Guardrail

--- description: KMP 2.1 SKIE Bidirectional Cancellation and Error Mapping Guardrail - Enforces strict two-way cooperative cancellation and type-safe error propagation between Kotlin Coroutines and Swift Concurrency via Touchlab SKIE in Kotlin Multiplatform 2.1+. Prevents leaked background jobs, thread deadlocks, swallowed CancellationExceptions, and unhandled Swift Task cancellations across the foreign function interface (FFI) boundary. globs: **/*.kt, **/*.swift, **/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skie-swift-concurrency-cancellation" --- # KMP 2.1 SKIE Bidirectional Cancellation and Error Mapping Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Swallowing CancellationException in Kotlin and Unbounded Detached Swift Task Invocations Leaking Coroutines Across the Obj-C Runtime Boundary ## System Constraints You are a Principal Mobile Architect enforcing bulletproof Kotlin Multiplatform 2.1+ and Touchlab SKIE interoperability. You must eliminate all uncooperative cancellation scenarios, leaked Jobs, uncaught CancellationExceptions, and improper Objective-C bridge conversions between Kotlin Coroutines and Swift async/await. ## Strict Guidelines - Engineers MUST ALWAYS rethrow `kotlinx.coroutines.CancellationException` when catching `Throwable` or `Exception` in Kotlin code exposed to Swift via SKIE. - Engineers MUST NOT map `CancellationException` to sealed UI failure states or domain errors; it must propagate cleanly to allow Swift Task cancellation tracking. - Engineers MUST configure SKIE Swift Concurrency bridges explicitly in `build.gradle.kts` and verify that generated Swift wrappers bind cancellation handles directly to Swift's `withTaskCancellationHandler` or `Task.isCancelled`. - Swift callers MUST invoke Kotlin suspend functions within structured `Task` scopes or explicit async contexts rather than unbound `Task.detached` without storing and managing `Task` handles. - Engineers MUST NEVER use `runBlocking` on the main thread in Kotlin or block the Swift cooperative thread pool waiting for an uncooperative Coroutine Job. - Kotlin Flows exposed through SKIE as `AsyncSequence` MUST use cooperative backpressure and terminate immediately when Swift breaks out of `for try await` loops. ## Bad vs Good Implementations ### Kotlin Coroutine Error Handling: Preserving CancellationException Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Catching `Exception` catches `kotlinx.coroutines.CancellationException`. When Swift cancels its parent `Task`, SKIE cancels the bridged Job; by swallowing the exception and returning a `Result.failure`, the Kotlin runtime fails to clean up coroutine scopes and reports a false domain error back to Swift. ```kotlin class UserRepository(private val api: UserApi) { // ANTI-PATTERN: Catching Exception catches CancellationException, // breaking SKIE's ability to trigger Swift CancellationError suspend fun fetchUserProfile(userId: String): Result<UserProfile> { return try { val profile = api.getUser(userId) Result.success(profile) } catch (e: Exception) { // Leaks coroutine state; Swift Task cancellation is swallowed Result.failure(e) } } } ``` #### Production Standard (Correct) > **Standard**: Explicitly catching and rethrowing `CancellationException` permits Touchlab SKIE's runtime bridge to translate the cancellation directly into Swift's native `CancellationError()`, unblocking the Swift async stack immediately and safely cleaning up coroutine resources. ```kotlin import kotlinx.coroutines.CancellationException import kotlinx.coroutines.ensureActive import kotlin.coroutines.coroutineContext class UserRepository(private val api: UserApi) { // PRODUCTION FIX: Explicitly rethrows CancellationException suspend fun fetchUserProfile(userId: String): Result<UserProfile> { return try { coroutineContext.ensureActive() val profile = api.getUser(userId) Result.success(profile) } catch (e: CancellationException) { throw e } catch (e: Exception) { Result.failure(DomainUserError.NetworkFailure(e)) } } } ``` ### Swift async/await Integration: Structured Task Scope vs Unmanaged Detached Call #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning an unmanaged `Task.detached` breaks Swift Structured Concurrency. If the user navigates away, the view disappears, but the underlying Kotlin coroutine executes indefinitely across the bridge, wasting network bandwidth and memory. ```swift import SharedKit import SwiftUI struct ProfileView: View { @StateObject var viewModel = ProfileViewModel() var body: some View { Text("User Profile") .onAppear { // ANTI-PATTERN: Fire-and-forget detached task ignores view lifecycle // When view disappears, Kotlin suspend execution continues indefinitely Task.detached { _ = try? await viewModel.repository.fetchUserProfile(userId: "123") } } } } ``` #### Production Standard (Correct) > **Standard**: Using SwiftUI's `.task` modifier attaches the call to the structured lifecycle of the View. When the view disappears, Swift cancels the parent `Task`, which SKIE automatically propagates across the FFI boundary to cancel the corresponding Kotlin `Job`. ```swift import SharedKit import SwiftUI struct ProfileView: View { @StateObject var viewModel = ProfileViewModel() var body: some View { Text("User Profile") .task(id: viewModel.userId) { // PRODUCTION FIX: Bound to View lifecycle do { let result = try await viewModel.repository.fetchUserProfile(userId: viewModel.userId) viewModel.process(result) } catch is CancellationError { // SKIE properly converts Kotlin CancellationException to Swift CancellationError viewModel.handleCancellation() } catch { viewModel.handleFailure(error) } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP 2.1 SKIE Bidirectional Cancellation and Error Mapping Guardrail

KMP 2.1 SKIE Bidirectional Cancellation and Error Mapping Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict two-way cooperative cancellation and type-safe error propagation between Kotlin Coroutines and Swift Concurrency via Touchlab SKIE in Kotlin Multiplatform 2.1+. Prevents leaked background jobs, thread deadlocks, swallowed CancellationExceptions, and unhandled Swift Task cancellations across the foreign function interface (FFI) boundary. 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: Swallowing CancellationException in Kotlin and Unbounded Detached Swift Task Invocations Leaking Coroutines Across the Obj-C Runtime Boundary 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	Swallowing CancellationException in Kotlin and Unbounded Detached Swift Task Invocations Leaking Coroutines Across the Obj-C Runtime Boundary	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 rethrow `kotlinx.coroutines.CancellationException` when catching `Throwable` or `Exception` in Kotlin code exposed to Swift via 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.