Kotlin Multiplatform Swift Task Cancellation Boundary Guardrail

--- description: Kotlin Multiplatform Swift Task Cancellation Boundary Guardrail - Enforces strict bidirectional cancellation propagation across the Kotlin Multiplatform Objective-C/Swift interop boundary. Prevents zombie coroutine execution, Darwin thread pool exhaustion, and memory leaks caused by uncoordinated Swift Task and Kotlin Coroutine lifecycles. globs: iosApp/**/*.swift, shared/src/**/*.kt, shared/src/**/*.swift, **/bridge/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-task-cancellation-boundary" --- # Kotlin Multiplatform Swift Task Cancellation Boundary Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unlinked Swift Continuations and Dangling Kotlin Bridge Jobs ## System Constraints You are a Principal Mobile Systems Architect specializing in Kotlin Multiplatform (KMP) and Swift Concurrency integration. Your responsibility is to strictly enforce bidirectional lifecycle and cancellation guarantees across the Obj-C/Swift interop boundary. Every asynchronous call crossing the bridge must guarantee immediate propagation of Swift Task cancellation to the underlying Kotlin Job, and propagate Kotlin CancellationException as Swift CancellationError without thread starvation or uncollected coroutine scopes. ## Strict Guidelines - Engineers MUST ALWAYS register cancellation hooks using 'withTaskCancellationHandler' or verified toolchains (e.g., SKIE or KMP-NativeCoroutines) when wrapping Kotlin suspend functions in Swift async APIs. - Engineers MUST ALWAYS cancel the underlying Kotlin Job when a Swift Task is cancelled, ensuring coroutine dispatchers release native worker threads immediately. - Engineers MUST NEVER use raw 'withCheckedContinuation' without attaching a cancellation handler that actively invokes the Kotlin Job's cancellation handle. - Code bridging Kotlin Flows to Swift 'AsyncSequence' or 'AsyncThrowingStream' MUST bind 'onTermination' to explicitly cancel the underlying Flow collector Job. - Kotlin bridge wrappers MUST rethrow Kotlin 'CancellationException' and map it cleanly to Swift 'CancellationError', avoiding swallowing cancellations as generic runtime exceptions. - Components NEVER bind native UI lifecycles directly to unbounded Kotlin CoroutineScopes without explicit lifecycle-aware tear-down triggers on the Swift side. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Task with Cancellation Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to capture and invoke the Kotlin bridge handle during cancellation leaves the underlying Kotlin coroutine executing indefinitely, causing native thread starvation and unnecessary network/battery usage. ```swift import SharedKit func fetchUserProfile(userId: String) async throws -> UserProfile { // BAD: Using raw withCheckedThrowingContinuation ignores Swift Task cancellation. // If the caller's Task is cancelled or the SwiftUI view unmounts, the underlying // Kotlin coroutine runs indefinitely on the Kotlin background thread pool. return try await withCheckedThrowingContinuation { continuation in SharedUserApi().getUserProfile(id: 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**: Wrapping the continuation in 'withTaskCancellationHandler' captures the Kotlin cancellation handle and invokes 'cancel()' the instant the Swift Task is cancelled, preserving cooperative cancellation across both runtimes. ```swift import SharedKit func fetchUserProfile(userId: String) async throws -> UserProfile { // GOOD: Holds reference to Kotlin Cancellable/Job and propagates Swift Task cancellation immediately. var cancellableJob: SharedKit.Cancellable? = nil return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in cancellableJob = SharedUserApi().getUserProfile(id: userId) { profile, error in if let error = error { if error._code == KotlinExceptionConstants.cancellationCode { continuation.resume(throwing: CancellationError()) } else { continuation.resume(throwing: error) } } else if let profile = profile { continuation.resume(returning: profile) } } } } onCancel: { cancellableJob?.cancel() } } ``` ### Bridging Kotlin Flow to Swift AsyncThrowingStream #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When the Swift consumer terminates or drops the AsyncThrowingStream iteration, the underlying Kotlin coroutine collector remains active and continues to pump events, causing severe memory leaks. ```swift import SharedKit func observeUserEvents() -> AsyncThrowingStream<UserEvent, Error> { // BAD: Flow collector continues indefinitely because termination callback is absent. return AsyncThrowingStream { continuation in SharedEventRepository().watchEvents().collect( onEach: { event in continuation.yield(event) }, onCompletion: { error in if let error = error { continuation.finish(throwing: error) } else { continuation.finish() } } ) } } ``` #### Production Standard (Correct) > **Standard**: Registering 'onTermination' ensures that when the Swift AsyncSequence is aborted or finishes early, the underlying Kotlin collection Job is promptly cancelled, stopping further event generation. ```swift import SharedKit func observeUserEvents() -> AsyncThrowingStream<UserEvent, Error> { // GOOD: Explicitly cancels the Kotlin collector job via onTermination. return AsyncThrowingStream { continuation in let collectorJob = SharedEventRepository().watchEvents().collect( onEach: { event in continuation.yield(event) }, onCompletion: { error in if let error = error { continuation.finish(throwing: error) } else { continuation.finish() } } ) continuation.onTermination = { @Sendable _ in collectorJob.cancel() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift Task Cancellation Boundary Guardrail

Kotlin Multiplatform Swift Task Cancellation Boundary Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict bidirectional cancellation propagation across the Kotlin Multiplatform Objective-C/Swift interop boundary. Prevents zombie coroutine execution, Darwin thread pool exhaustion, and memory leaks caused by uncoordinated Swift Task and Kotlin Coroutine lifecycles. 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: Unlinked Swift Continuations and Dangling Kotlin Bridge Jobs 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	Unlinked Swift Continuations and Dangling Kotlin Bridge Jobs	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 register cancellation hooks using 'withTaskCancellationHandler' or verified toolchains (e.g., SKIE or KMP-NativeCoroutines) when wrapping Kotlin suspend functions in Swift async APIs.

Engineers MUST ALWAYS register cancellation hooks using 'withTaskCancellationHandler' or verified toolchains (e.g., SKIE or KMP-NativeCoroutines) when wrapping Kotlin suspend functions in Swift async APIs.

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.