Deterministic KMP Coroutine-to-Swift Task Cancellation Propagation

--- description: Deterministic KMP Coroutine-to-Swift Task Cancellation Propagation - Enforces bidirectional, deterministic cancellation propagation and resource deallocation across the native Swift Concurrency Task boundary and Kotlin Coroutine runtime. Prevents orphaned asynchronous executions, thread starvation, and memory leaks caused by Kotlin/Native suspend-to-Swift async bridging conventions (SKIE or standard cinterop). globs: **/*.kt, **/*.swift, **/iosApp/**/*.swift, **/shared/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-coroutine-swift-task-cancellation-propagation-kotlin-multiplat-695" --- # Deterministic KMP Coroutine-to-Swift Task Cancellation Propagation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Orphaned Kotlin Coroutines from Unbridged Swift Task Lifecycle Deallocation ## System Constraints You are a Principal Mobile Architect enforcing strict lifecycle and cancellation invariants across Kotlin Multiplatform and Swift Concurrency boundaries. Suspend functions and async streams exposed to Swift must propagate cooperative cancellation instantly. Raw Swift Task cancellation does not automatically tear down standard Kotlin coroutine jobs unless explicitly hooked into a Job cancellation bridge or managed via SKIE coroutine cancellation adapters. You must enforce explicit cancellation-handling mechanisms, prevent GlobalScope or unstructured launch usage in shared KMP layers, and guarantee deterministic release of Kotlin Native runtime objects on the iOS target. ## Strict Guidelines - Engineers MUST ALWAYS expose KMP asynchronous streams as SKIE-wrapped or explicitly cancellable bridges (e.g., passing a Kotlin `Job` reference or using `withTaskCancellationHandler`) when bridging Kotlin `Flow` or `suspend` functions to Swift `AsyncSequence` or `async` methods. - Engineers MUST NOT rely on raw Kotlin Native default Swift async export without SKIE or a custom `withTaskCancellationHandler` wrapper, as standard ObjC-exported suspend completions fail to register Swift `Task.isCancelled` transitions to the underlying Kotlin `Job`. - Engineers MUST ALWAYS ensure Swift call sites wrap long-running or stream-based calls in `withTaskCancellationHandler` to invoke the underlying Kotlin `Job.cancel(cause:)` immediately upon Swift Task cancellation. - Engineers MUST NOT launch unstructured coroutines via `GlobalScope.launch` or unbounded `CoroutineScope` instances in common code that expose interfaces to native platforms; every CoroutineScope MUST be bound to a distinct lifecycle owner with explicit `cancel()` hooks. - Kotlin code MUST check coroutine active state using `yield()` or `ensureActive()` inside CPU-bound loops across the boundary, guaranteeing cooperative cancellation is honored as soon as the Swift Task signals abort. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Task Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default Objective-C export bridging generates an async Swift signature backed by a completion handler. When the calling Swift Task is cancelled, no signal is sent back to the Kotlin runtime, leaving the Kotlin coroutine running, wasting CPU/network, and potentially leaking state. ```swift // BAD: Direct invocation of Kotlin suspend function in Swift Task. // Cancelling this Task leaves the underlying Kotlin coroutine executing indefinitely in the K/N worker thread pool. import SharedKit func fetchUserData(userId: String) async throws -> UserProfile { let repository = UserRepository() // Default KMP ObjC-export does not wire Swift Task cancellation back to Kotlin Job return try await repository.fetchUserProfile(userId: userId) } ``` #### Production Standard (Correct) > **Standard**: Using withTaskCancellationHandler guarantees that if the Swift Task lifecycle terminates or cancels, the underlying Kotlin Job is immediately cancelled, freeing Kotlin/Native worker threads and associated memory. ```swift // GOOD: Deterministic two-way cancellation propagation using withTaskCancellationHandler import SharedKit func fetchUserData(userId: String) async throws -> UserProfile { let repository = UserRepository() let wrapper = repository.fetchUserProfileCancellable(userId: userId) return try await withTaskCancellationHandler(operation: { try await wrapper.awaitResult() }, onCancel: { wrapper.job.cancel(cause: nil) }) } ``` ### Kotlin Common API Explicit Job and Cancellation Hook Exposure #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Pure suspend functions exported through standard KMP ObjC interop convert to completion handlers without exposing the Coroutine Job, preventing native Swift consumers from terminating active work during view dismissal. ```kotlin // BAD: Exposing a pure suspend function without cancellation handle for platforms lacking compiler-level bridges like SKIE package com.example.repository import kotlinx.coroutines.delay class UserRepository { suspend fun fetchUserProfile(userId: String): UserProfile { // Heavy operations without explicit lifecycle handles exposed to ObjC/Swift delay(5000) return UserProfile(id = userId, name = "Verified User") } } ``` #### Production Standard (Correct) > **Standard**: The CancellableTask abstraction explicitly pairs the ongoing Job with the deferred result, allowing native platforms to trigger job.cancel() via native teardown routines or Task cancellation listeners. ```kotlin // GOOD: Providing explicit CancellableTask bridge exposing the Kotlin Job to native callers package com.example.repository import kotlinx.coroutines.* class CancellableTask<T>(val job: Job, val awaitResult: suspend () -> T) class UserRepository(private val scope: CoroutineScope) { fun fetchUserProfileCancellable(userId: String): CancellableTask<UserProfile> { val deferred = scope.async(start = CoroutineStart.LAZY) { ensureActive() delay(5000) UserProfile(id = userId, name = "Verified User") } val job = scope.launch(start = CoroutineStart.UNDISPATCHED) { deferred.start() } return CancellableTask(job = job, awaitResult = { deferred.await() }) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic KMP Coroutine-to-Swift Task Cancellation Propagation

Deterministic KMP Coroutine-to-Swift Task Cancellation Propagation defines an industrial-grade behavioral standard for mobile engineering. Enforces bidirectional, deterministic cancellation propagation and resource deallocation across the native Swift Concurrency Task boundary and Kotlin Coroutine runtime. Prevents orphaned asynchronous executions, thread starvation, and memory leaks caused by Kotlin/Native suspend-to-Swift async bridging conventions (SKIE or standard cinterop). 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 Coroutines from Unbridged Swift Task Lifecycle Deallocation 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 Coroutines from Unbridged Swift Task Lifecycle Deallocation	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 expose KMP asynchronous streams as SKIE-wrapped or explicitly cancellable bridges (e.g., passing a Kotlin `Job` reference or using `withTaskCancellationHandler`) when bridging Kotlin `Flow` or `suspend` functions to Swift `AsyncSequence` or `async` methods.

Engineers MUST ALWAYS expose KMP asynchronous streams as SKIE-wrapped or explicitly cancellable bridges (e.g., passing a Kotlin `Job` reference or using `withTaskCancellationHandler`) when bridging Kotlin `Flow` or `suspend` functions to Swift `AsyncSequence` or `async` methods.

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.