Kotlin Multiplatform 2.1 Swift Concurrency Task Cancellation Bridge

--- description: Kotlin Multiplatform 2.1 Swift Concurrency Task Cancellation Bridge - Mandates strict bidirectional cancellation propagation and explicit memory lifecycle boundaries across the Kotlin Multiplatform 2.1 Kotlin/Native and Swift async/await ABI. Prevents memory retention cycles and orphaned Kotlin coroutines running indefinitely in background dispatchers after parent Swift Tasks are cancelled. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-concurrency-cancellation-bridge-guardrail" --- # Kotlin Multiplatform 2.1 Swift Concurrency Task Cancellation Bridge > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Orphaned Background Coroutines and ARC Retention Cycles Across Swift Task ABI ## System Constraints You are a Principal Mobile Architect enforcing bulletproof Kotlin Multiplatform 2.1 and Swift Concurrency integration standards. Your primary objective is eliminating uncollected coroutines, memory leaks, and broken task lifecycles when crossing the Kotlin/Native Objective-C/Swift ABI boundary. Enforce structured concurrency and explicit bidirectional cancellation hooks. ## Strict Guidelines - Engineers MUST ALWAYS bind Swift `Task` cancellation directly to the underlying Kotlin `Job` using `withTaskCancellationHandler` when calling Kotlin suspend functions through raw interop closures. - Engineers MUST NOT rely on default Kotlin/Native Objective-C completion blocks without managing strong reference releases, as ARC-retained Swift closures retain Kotlin GC root references indefinitely. - Code SHOULD utilize SKIE or a battle-tested `CancellableTask` wrapper protocol that guarantees `Job.cancel()` is invoked immediately when `Task.isCancelled` evaluates to true. - Services MUST ensure Kotlin `Flow` wrappers propagating into Swift `AsyncStream` or `AsyncSequence` explicitly invoke `job.cancel(CancellationException())` on the `onTermination` callback. - Components NEVER capture strong references to Swift classes, SwiftUI Views, or Observable models within asynchronous Kotlin bridge completion handlers. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Async/Await with Cooperative Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the calling Swift Task is cancelled before the Kotlin coroutine completes, this continuation simply leaks or throws CancellationError while the underlying Kotlin coroutine continues executing in the Kotlin background dispatcher, wasting memory, CPU, and network I/O. ```swift // Flawed bridge: Orphaned coroutine when Task is cancelled, strong capture cycle func fetchUserData(userId: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in // Invokes KMP 2.1 suspend fun exposed as Obj-C completion block SharedRepository().fetchUserProfile(userId: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } } } ``` #### Production Standard (Correct) > **Standard**: Leverages withTaskCancellationHandler to synchronously trigger Kotlin's Job.cancel() as soon as the Swift Task is aborted, preventing orphaned execution and immediately releasing bridged memory. ```swift // Production-grade bridge: Propagates Task cancellation directly to Kotlin Job func fetchUserData(userId: String) async throws -> UserProfile { var jobRef: Kotlinx_coroutines_coreJob? = nil return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in jobRef = SharedRepository().fetchUserProfile(userId: 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: { // Immediate cancellation propagation across ABI boundary jobRef?.cancel(cause: nil) } } ```

Architectural Specification & Invariant Rationale

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

Kotlin Multiplatform 2.1 Swift Concurrency Task Cancellation Bridge defines an industrial-grade behavioral standard for mobile engineering. Mandates strict bidirectional cancellation propagation and explicit memory lifecycle boundaries across the Kotlin Multiplatform 2.1 Kotlin/Native and Swift async/await ABI. Prevents memory retention cycles and orphaned Kotlin coroutines running indefinitely in background dispatchers after parent Swift Tasks are cancelled. 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 Background Coroutines and ARC Retention Cycles Across Swift Task ABI 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 Background Coroutines and ARC Retention Cycles Across Swift Task ABI	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 `Task` cancellation directly to the underlying Kotlin `Job` using `withTaskCancellationHandler` when calling Kotlin suspend functions through raw interop closures.

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.