Kotlin Multiplatform 2.1 SKIE Swift Task Cancellation Bridge

--- description: Kotlin Multiplatform 2.1 SKIE Swift Task Cancellation Bridge - Enforces strict propagation of Swift Structured Concurrency Task cancellation into Kotlin Coroutine Job hierarchies across the Kotlin/Native Objective-C interop boundary. Prevents zombie background coroutines, memory leaks, and CPU thrashing on iOS when SwiftUI views or Task trees are cancelled. Mandates the use of Touchlab SKIE's bidirectional cancellation bridges or structured withTaskCancellationHandler wrappers over unmanaged completion-handler calls. globs: iosApp/**/*.swift, shared/src/iosMain/kotlin/**/*.kt, shared/src/commonMain/kotlin/**/*.kt, shared/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skie-swift-task-cancellation-bridge" --- # Kotlin Multiplatform 2.1 SKIE Swift Task Cancellation Bridge > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbridged Objective-C Completion Handlers Disconnecting Swift Task Cancellation from Kotlin Coroutine Jobs ## System Constraints You are a Principal Mobile Architect enforcing strict Kotlin Multiplatform 2.1 and Touchlab SKIE concurrency invariants on iOS. When consuming Kotlin suspend functions or Flow streams in Swift Structured Concurrency contexts, you must guarantee that Swift Task cancellation deterministically cancels underlying Kotlin Coroutine Jobs across the Objective-C runtime boundary. Never allow disconnected async calls or discarded Job handles that lead to zombie thread execution. ## Strict Guidelines - Engineers MUST ALWAYS verify that SKIE is configured in `build.gradle.kts` with `features { coroutines = true }` enabled for shared iOS frameworks to generate native async/await bridges. - Engineers MUST NEVER invoke Kotlin suspend functions using legacy Objective-C completion-handler callbacks inside Swift `async/await` contexts without wrapping them in an explicit cancellation mechanism (such as `withTaskCancellationHandler` or SKIE's generated wrappers). - Engineers MUST ALWAYS use SKIE's generated Swift `AsyncSequence` extensions when consuming Kotlin `Flow` instances in Swift to ensure terminating the loop immediately cancels the Kotlin `FlowCollector` job. - Engineers MUST ensure that any manual Kotlin/Native interop passing a `CancellationToken` or completion callback binds the Swift `Task.isCancelled` handler directly to `kotlinx.coroutines.Job.cancel()`. - Engineers MUST NOT use `GlobalScope` or unbounded `CoroutineScope(Dispatchers.Default)` in Kotlin when exposing APIs to iOS; all scopes must be tied to a managed lifecycle (e.g., `ViewModel` or `CancellableCoroutine`). ## Bad vs Good Implementations ### Consuming Kotlin Suspend Functions via SKIE Structured Concurrency Bridge vs Legacy Completion Callback #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using standard Kotlin/Native completion blocks creates an unmanaged continuation. When the parent Swift Task is cancelled (e.g., user navigates back in SwiftUI), Swift abandons the continuation, but the Kotlin Coroutine Job has zero knowledge of the cancellation and continues running to completion. ```swift // BAD: Consuming Kotlin suspend function via default Objective-C export // Swift Task cancellation has no bridge to the underlying Kotlin coroutine Job. func fetchUserProfile(id: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in // Invoking raw exported completion handler UserRepositoryKt.fetchUserProfile(id: id) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } // Anti-pattern: When this Swift Task is cancelled, the Kotlin Job continues // executing on the background dispatcher, leaking network sockets and memory. } } ``` #### Production Standard (Correct) > **Standard**: SKIE's native async/await bridge automatically captures the ambient Swift Task cancellation state and binds it directly to the underlying Kotlin Job. The alternative shows how to manually invoke `jobRef?.cancel(cause: nil)` inside `withTaskCancellationHandler` if SKIE is unavailable. ```swift // GOOD: Consuming Kotlin suspend functions directly via SKIE-generated async bridge // SKIE automatically translates Swift Task cancellation into kotlinx.coroutines.Job.cancel() func fetchUserProfile(id: String) async throws -> UserProfile { // SKIE generates: func fetchUserProfile(id: String) async throws -> UserProfile // If this Swift Task is cancelled, SKIE triggers cancellation of the backing Kotlin Coroutine Job return try await userRepository.fetchUserProfile(id: id) } // ALTERNATIVE (Manual Bridge without SKIE): Explicitly wiring withTaskCancellationHandler func fetchUserProfileManual(id: String) async throws -> UserProfile { var jobRef: SharedJob? = nil return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in jobRef = UserRepositoryKt.fetchUserProfileCancellable(id: id) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } } } onCancel: { // Explicitly propagate Swift Task cancellation to Kotlin Job jobRef?.cancel(cause: nil) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 SKIE Swift Task Cancellation Bridge

Kotlin Multiplatform 2.1 SKIE Swift Task Cancellation Bridge defines an industrial-grade behavioral standard for mobile engineering. Enforces strict propagation of Swift Structured Concurrency Task cancellation into Kotlin Coroutine Job hierarchies across the Kotlin/Native Objective-C interop boundary. Prevents zombie background coroutines, memory leaks, and CPU thrashing on iOS when SwiftUI views or Task trees are cancelled. Mandates the use of Touchlab SKIE's bidirectional cancellation bridges or structured withTaskCancellationHandler wrappers over unmanaged completion-handler calls. 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: Unbridged Objective-C Completion Handlers Disconnecting Swift Task Cancellation from Kotlin Coroutine Jobs 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	Unbridged Objective-C Completion Handlers Disconnecting Swift Task Cancellation from Kotlin Coroutine Jobs	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 verify that SKIE is configured in `build.gradle.kts` with `features { coroutines = true }` enabled for shared iOS frameworks to generate native async/await bridges.

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.