KMP Bi-Directional Swift Task to Coroutine Cancellation Bridge

--- description: KMP Bi-Directional Swift Task to Coroutine Cancellation Bridge - Enforces deterministic, bi-directional cooperative cancellation bridging between Swift async/await Tasks and Kotlin Coroutine Jobs across the Kotlin/Native boundary. Eliminates orphaned background execution threads, UI memory retention cycles, and phantom network operations when Swift views discard active tasks. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt, **/*Bridge*.swift, **/*Adapter*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-task-cancellation-bridge-standard" --- # KMP Bi-Directional Swift Task to Coroutine Cancellation Bridge > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Orphaned Kotlin Coroutine Execution on Swift Task Cancellation ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Swift Concurrency interoperability. You strictly mandate that every Kotlin suspend function or Flow consumed by Swift async/await tasks guarantees deterministic bi-directional cancellation propagation. Never allow unmanaged suspend invocations or detached CoroutineScopes that do not bind Swift Task lifecycle to Kotlin Job lifecycle. ## Strict Guidelines - Engineers MUST ALWAYS wrap raw Kotlin/Native suspend exports with `withTaskCancellationHandler` in Swift or rely on verified structured concurrency adapters (e.g., SKIE or KMP-NativeCoroutines) that bind Swift cancellation directly to `Job.cancel()`. - Engineers MUST NOT invoke Kotlin suspend functions directly via raw Swift `async` wrappers without binding the Swift cancellation handler to the returned Kotlin `Cancellable` or `Job` handle. - Kotlin iOS bridge interfaces MUST return a handle exposing `cancel()` or accept a cooperative cancellation token across the Objective-C bridging barrier. - Shared Flows exposed to iOS MUST be collected using a lifecycle-aware wrapper that cancels the underlying Kotlin `Job` immediately when the Swift `AsyncSequence` terminates or throws `CancellationError`. - SwiftUI views MUST NEVER fire-and-forget Kotlin coroutines in `.task` or `.onAppear` without structured cancellation hooks; abandoning a view MUST immediately propagate cancellation down to active CoroutineContext dispatchers. ## Bad vs Good Implementations ### Bridging Swift Task Cancellation to Kotlin Coroutine Job #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default Objective-C Swift interop generates an async wrapper for suspend functions, but Swift Task cancellation does not propagate to the underlying Kotlin Job. The background thread in Kotlin continues executing unobserved, wasting battery, network, and memory. ```swift import SharedKit final class ProfileViewModel: ObservableObject { private let repository: UserProfileRepository init(repository: UserProfileRepository) { self.repository = repository } func loadProfile(userId: String) async throws -> UserProfile { // ANTI-PATTERN: Direct invocation of unbridged suspend function. // If the Swift Task is cancelled (e.g. view dismissed), the underlying // Kotlin coroutine continues executing on Dispatchers.Default unchecked. return try await repository.fetchUserProfile(id: userId) } } ``` #### Production Standard (Correct) > **Standard**: Wraps the bridging continuation in `withTaskCancellationHandler` to immediately trigger the Kotlin `CancellableHandle.cancel()` upon Swift Task cancellation, ensuring instantaneous termination of background work. ```swift import SharedKit final class ProfileViewModel: ObservableObject { private let repository: UserProfileRepository init(repository: UserProfileRepository) { self.repository = repository } func loadProfile(userId: String) async throws -> UserProfile { // PRODUCTION INVARIANT: Cooperative bi-directional cancellation bridge. var cancellableHandle: CancellableHandle? = nil return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in cancellableHandle = repository.fetchUserProfileWithCancel(id: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } else { continuation.resume(throwing: CancellationError()) } } } } onCancel: { // Propagates Swift Task cancellation directly into Kotlin Job.cancel() cancellableHandle?.cancel() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Bi-Directional Swift Task to Coroutine Cancellation Bridge

KMP Bi-Directional Swift Task to Coroutine Cancellation Bridge defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, bi-directional cooperative cancellation bridging between Swift async/await Tasks and Kotlin Coroutine Jobs across the Kotlin/Native boundary. Eliminates orphaned background execution threads, UI memory retention cycles, and phantom network operations when Swift views discard active tasks. 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: Orphaned Kotlin Coroutine Execution on Swift Task Cancellation 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	Orphaned Kotlin Coroutine Execution on Swift Task Cancellation	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 wrap raw Kotlin/Native suspend exports with `withTaskCancellationHandler` in Swift or rely on verified structured concurrency adapters (e.g., SKIE or KMP-NativeCoroutines) that bind Swift cancellation directly to `Job.cancel()`.

Engineers MUST ALWAYS wrap raw Kotlin/Native suspend exports with `withTaskCancellationHandler` in Swift or rely on verified structured concurrency adapters (e.g., SKIE or KMP-NativeCoroutines) that bind Swift cancellation directly to `Job.cancel()`.

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.