Kotlin Multiplatform Swift Concurrency Cooperative Cancellation Invariant

--- description: Kotlin Multiplatform Swift Concurrency Cooperative Cancellation Invariant - Mandates bidirectional cooperative cancellation across the Swift-to-Kotlin Native C-interop boundary. Every Swift Task consuming Kotlin Coroutine suspend functions or Flows must bind its lifecycle to the underlying Kotlin Job via withTaskCancellationHandler to guarantee deterministic teardown of unmanaged native allocations and background workloads. 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-cooperative-cancellation-bridge" --- # Kotlin Multiplatform Swift Concurrency Cooperative Cancellation Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Orphaned Kotlin Coroutine Jobs and Leaked Native Memory via Naive Swift Async Bridging ## System Constraints You are a Principal Mobile Architect enforcing absolute lifecycle parity between Apple Swift Concurrency and Kotlin Multiplatform Coroutines. You must prevent memory leaks, abandoned network sessions, and zombie coroutines by enforcing deterministic cooperative cancellation across the Objective-C/Swift interop boundary. ## Strict Guidelines - Engineers MUST ALWAYS wrap Kotlin suspending function calls in Swift with `withTaskCancellationHandler` when converting completions or continuations to `async`/`await`. - Engineers MUST NOT use unmanaged `withCheckedContinuation` or `withUnsafeContinuation` without registering an immediate `onCancel` closure that invokes the underlying Kotlin `Job.cancel()` or `Cancellable.cancel()`. - Swift asynchronous streams consuming Kotlin `Flow` instances MUST explicitly invoke `close()` or cancel the collector's underlying Kotlin `Job` upon Swift `AsyncSequence` iteration termination or consumer cancellation. - Kotlin-facing interop layers MUST return a handle (such as `Job` or a custom `Cancellable` interface) to Swift caller wrappers rather than executing unmonitored launches on global scopes. - Services MUST NEVER rely on Swift reference counting (ARC) or garbage collection finalizers to cancel active Kotlin Coroutine scopes. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Async with Cooperative Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using withCheckedThrowingContinuation without withTaskCancellationHandler creates an unmonitored coroutine job across the C-interop boundary. When the parent Swift Task cancels, fetchUser continues running in KMP until completion. ```swift import Shared func fetchUserData(userId: String) async throws -> UserProfile { // ANTI-PATTERN: Swift Task cancellation has no visibility into the Kotlin Job. // If the calling Swift Task is cancelled, the underlying Kotlin coroutine executes indefinitely, // leaking CPU cycles and network sockets. return try await withCheckedThrowingContinuation { continuation in SharedUserRepository().fetchUser(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**: withTaskCancellationHandler registers an onCancel callback executed immediately when the Swift Task is cancelled. This triggers job.cancel(), cascading cancellation through the Kotlin Coroutine hierarchy across the C-interop bridge. ```swift import Shared func fetchUserData(userId: String) async throws -> UserProfile { var job: KMPJob? = nil return try await withTaskCancellationHandler( operation: { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in // Shared repo returns a cancellable job handle across interop job = SharedUserRepository().fetchUser(userId: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } } }, onCancel: { // Deterministically propagates Swift cancellation to Kotlin Job hierarchy job?.cancel(cause: nil) } ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift Concurrency Cooperative Cancellation Invariant

Kotlin Multiplatform Swift Concurrency Cooperative Cancellation Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates bidirectional cooperative cancellation across the Swift-to-Kotlin Native C-interop boundary. Every Swift Task consuming Kotlin Coroutine suspend functions or Flows must bind its lifecycle to the underlying Kotlin Job via withTaskCancellationHandler to guarantee deterministic teardown of unmanaged native allocations and background workloads. 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 Jobs and Leaked Native Memory via Naive Swift Async Bridging 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 Jobs and Leaked Native Memory via Naive Swift Async Bridging	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 Kotlin suspending function calls in Swift with `withTaskCancellationHandler` when converting completions or continuations to `async`/`await`.

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.