Kotlin Multiplatform to Swift Structured Concurrency Bi-Directional Cancellation Guardrail

--- description: Kotlin Multiplatform to Swift Structured Concurrency Bi-Directional Cancellation Guardrail - Enforces deterministic, bidirectional propagation between Swift Structured Concurrency Task cancellation and Kotlin Coroutines Job cancellation across the Objective-C/C export boundary. Eliminates orphaned worker threads, uncollected completion closures, and unmanaged memory retention across Swift-KMP module boundaries. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/appleMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-concurrency-cancellation-bridge-barrier" --- # Kotlin Multiplatform to Swift Structured Concurrency Bi-Directional Cancellation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Orphaned Kotlin Coroutines and Leaked Native Continuations via Unhandled Swift Task Cancellation ## System Constraints You are a Principal Mobile Architect enforcing bulletproof Kotlin Multiplatform (KMP) and Swift Concurrency interoperability. You must strictly mandate bidirectional cancellation contracts between Swift's `Task` tree and Kotlin's `Job` hierarchy. Reject any unmanaged `withCheckedThrowingContinuation` or raw callback-based Kotlin suspend bridge that ignores cooperative cancellation or leaks native dispatch closures. ## Strict Guidelines - Engineers MUST ALWAYS wrap Kotlin suspend bridges inside `withTaskCancellationHandler` or use vetted tools (e.g., SKIE or KMP-NativeCoroutines) that register an active `onCancel` handler to cancel the underlying Kotlin `Job`. - Engineers MUST NOT bridge Kotlin suspend functions into Swift using bare `withCheckedContinuation` or `withCheckedThrowingContinuation` without binding `onCancel` to the returned cancellable handle. - Code SHOULD immediately propagate Swift Task cancellation by issuing `job.cancel(cause: CancellationException)` to prevent background thread starvation and CPU battery drain. - Services MUST ensure that cancellation cleanup on the Kotlin side immediately triggers the Swift continuation with a `CancellationError` rather than leaving the continuation dangling forever. - Components NEVER retain strong references to Swift continuations inside long-lived Kotlin native structures without nullifying them upon invocation or cancellation. ## Bad vs Good Implementations ### Bridging Kotlin Suspend to Swift async/await with Task Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The continuation ignores Swift's Task cancellation tree entirely. When the Swift caller cancels, the KMP Job keeps executing on the Kotlin dispatcher, causing orphaned thread execution, duplicate side effects, and leaks of the completion closure. ```swift // BAD: Suspended Kotlin execution is decoupled from Swift Task lifecycle. // If the calling Swift Task is cancelled (e.g. view dismissed), the Kotlin Coroutine // continues running indefinitely in the background, leaking memory and network resources. func fetchUserProfile(id: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in UserProfileRepository().fetchUser(id: id) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } } } ``` #### Production Standard (Correct) > **Standard**: The bridge couples the Swift Task cancellation signal directly to the Kotlin Coroutine via `withTaskCancellationHandler`. When the caller cancels, `onCancel` immediately invokes `cancel()` on the Kotlin handle, freeing resources across the runtime barrier. ```swift // GOOD: Bidirectional cancellation bridge using withTaskCancellationHandler and Job cancellation handle. import SharedKit func fetchUserProfile(id: String) async throws -> UserProfile { let repository = UserProfileRepository() var cancellableJob: CancellableTask? = nil return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in cancellableJob = repository.fetchUserCancellable(id: id) { profile, error in if let error = error { if error is KotlinCancellationException { continuation.resume(throwing: CancellationError()) } else { continuation.resume(throwing: error) } } else if let profile = profile { continuation.resume(returning: profile) } else { continuation.resume(throwing: BridgeError.unexpectedNilState) } } } } onCancel: { cancellableJob?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform to Swift Structured Concurrency Bi-Directional Cancellation Guardrail

Kotlin Multiplatform to Swift Structured Concurrency Bi-Directional Cancellation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, bidirectional propagation between Swift Structured Concurrency Task cancellation and Kotlin Coroutines Job cancellation across the Objective-C/C export boundary. Eliminates orphaned worker threads, uncollected completion closures, and unmanaged memory retention across Swift-KMP module boundaries. 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 and Leaked Native Continuations via Unhandled Swift Task Cancellation 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 and Leaked Native Continuations via Unhandled Swift Task Cancellation	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 suspend bridges inside `withTaskCancellationHandler` or use vetted tools (e.g., SKIE or KMP-NativeCoroutines) that register an active `onCancel` handler to cancel the underlying Kotlin `Job`.

Engineers MUST ALWAYS wrap Kotlin suspend bridges inside `withTaskCancellationHandler` or use vetted tools (e.g., SKIE or KMP-NativeCoroutines) that register an active `onCancel` handler to cancel 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.