KMP Coroutine to Swift 6 Structured Concurrency Continuation Bridging Guardrails

--- description: KMP Coroutine to Swift 6 Structured Concurrency Continuation Bridging Guardrails - Enforces deterministic cancellation and strict single-resumption invariants when bridging Kotlin 2.1 suspend coroutines into Swift 6 async/await Task hierarchies. Prevents fatal runtime traps, memory leaks, and cooperative thread pool starvations caused by dropped or duplicated CheckedContinuations and unlinked Kotlin Job handles on iOS. 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-continuation-bridging" --- # KMP Coroutine to Swift 6 Structured Concurrency Continuation Bridging Guardrails > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dangling CheckedContinuations and Unpropagated Swift 6 Task Cancellations Inducing Thread Exhaustion and Memory Leaks ## System Constraints You are a Principal Mobile Systems Architect enforcing bidirectional cancellation and memory safety across the Kotlin Multiplatform (Kotlin 2.1) and Swift 6 language boundary. Swift 6 enforces strict concurrency domain isolation (@Sendable, actor isolation) while Kotlin coroutines rely on cooperative Job cancellation. You must enforce that every bridged continuation adheres to structured concurrency invariants: mandatory Task cancellation hooks, safe atomic single-fire continuation resumption, and clean memory deallocation without reference cycles. ## Strict Guidelines - Engineers MUST ALWAYS bridge Kotlin suspend functions into Swift 6 via `withTaskCancellationHandler` combined with `withCheckedThrowingContinuation` to propagate Swift `Task.cancel()` to the underlying Kotlin `Job`. - Engineers MUST NEVER use `withUnsafeContinuation` across the KMP C-interop/Obj-C boundary; memory bugs or Kotlin coroutine cancellation will lead to silent UB or thread leaks. - Continuations MUST be guarded against multi-resume panics: Kotlin completion handlers can theoretically invoke on error and cancellation simultaneously if wrapper libraries are misconfigured; ensure resumption occurs exactly once via atomic state or thread-safe isolation. - Engineers MUST NOT block the Swift 6 cooperative thread pool (e.g., executing blocking Kotlin operations via runBlocking on the iOS main thread or cooperative queue). - Bridging adapters MUST mark completion handlers and closure arguments `@Sendable` to comply with Swift 6 strict concurrency checking (`SWIFT_STRICT_CONCURRENCY=complete`). - Captured references inside the `onCancel` closure of `withTaskCancellationHandler` MUST NOT retain a strong reference to Swift actor instances or controllers; capture only the specific Kotlin cancellation token or handle. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift 6 Task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the calling Swift Task is cancelled before Kotlin finishes, the continuation is never notified of cancellation, keeping the Swift Task alive and wasting network/CPU on the Kotlin side. Furthermore, if Kotlin cancels internally without invoking the Obj-C completion block, the Swift continuation leaks forever, blocking cooperative pool resources. ```swift // CRITICAL DEFECT: Leaks Swift continuation if Task is cancelled, // ignores Swift 6 Sendable checking, and crashes on duplicate resume. import SharedKit final class ProfileRepositoryBridge { private let kmpRepo: KmpProfileRepository init(kmpRepo: KmpProfileRepository) { self.kmpRepo = kmpRepo } func fetchProfile(id: String) async throws -> UserProfile { // Defect: Bare withCheckedThrowingContinuation without cancellation handler. // If calling Task is cancelled, Swift waits indefinitely for Kotlin completion, // or Kotlin finishes and attempts to resume a discarded Task continuation. return try await withCheckedThrowingContinuation { continuation in kmpRepo.fetchProfile(id: id) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } else { continuation.resume(throwing: BridgeError.unexpectedNil) } } } } } ``` #### Production Standard (Correct) > **Standard**: Wraps the call in `withTaskCancellationHandler` to forward Swift 6 task cancellations directly to the Kotlin job canceller. Enforces an `AtomicState` guard to satisfy `CheckedContinuation`'s single-resumption invariant, marked `Sendable` for Swift 6 compiler compliance without thread pool starvation. ```swift // PRODUCTION STANDARD: Swift 6 Strict Concurrency Safe Bridge import SharedKit import Foundation public final class ProfileRepositoryBridge: Sendable { private let kmpRepo: KmpProfileRepository public init(kmpRepo: KmpProfileRepository) { self.kmpRepo = kmpRepo } public func fetchProfile(id: String) async throws -> UserProfile { // Atomic or Actor-isolated gate ensuring continuation resumes exactly once final class AtomicState: @unchecked Sendable { private let lock = NSLock() private var isResumed = false func resumeOnce( continuation: CheckedContinuation<UserProfile, any Error>, result: Result<UserProfile, any Error> ) { lock.lock() defer { lock.unlock() } guard !isResumed else { return } isResumed = true continuation.resume(with: result) } } let state = AtomicState() var kotlinTaskHandle: SharedKit.CancellableTask? = nil return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<UserProfile, any Error>) in kotlinTaskHandle = kmpRepo.fetchProfile(id: id) { profile, error in if let error = error { state.resumeOnce(continuation: continuation, result: .failure(error)) } else if let profile = profile { state.resumeOnce(continuation: continuation, result: .success(profile)) } else { state.resumeOnce(continuation: continuation, result: .failure(BridgeError.nilResult)) } } } } onCancel: { // Propagate Swift cancellation directly to Kotlin Job kotlinTaskHandle?.cancel() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Coroutine to Swift 6 Structured Concurrency Continuation Bridging Guardrails

KMP Coroutine to Swift 6 Structured Concurrency Continuation Bridging Guardrails defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic cancellation and strict single-resumption invariants when bridging Kotlin 2.1 suspend coroutines into Swift 6 async/await Task hierarchies. Prevents fatal runtime traps, memory leaks, and cooperative thread pool starvations caused by dropped or duplicated CheckedContinuations and unlinked Kotlin Job handles on iOS. 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: Dangling CheckedContinuations and Unpropagated Swift 6 Task Cancellations Inducing Thread Exhaustion and Memory Leaks 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	Dangling CheckedContinuations and Unpropagated Swift 6 Task Cancellations Inducing Thread Exhaustion and Memory Leaks	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 Kotlin suspend functions into Swift 6 via `withTaskCancellationHandler` combined with `withCheckedThrowingContinuation` to propagate Swift `Task.cancel()` to the underlying Kotlin `Job`.

Engineers MUST ALWAYS bridge Kotlin suspend functions into Swift 6 via `withTaskCancellationHandler` combined with `withCheckedThrowingContinuation` to propagate Swift `Task.cancel()` to the underlying Kotlin `Job`.

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.