KMP Swift Concurrency Cancellation Bridge & Thread Leak Invariant

--- description: KMP Swift Concurrency Cancellation Bridge & Thread Leak Invariant - Enforces deterministic, bidirectional cancellation bridging between Kotlin Coroutines (Job) and Swift Structured Concurrency (Task/TaskGroup). Eliminates Darwin dispatch thread pool exhaustion and orphaned continuation memory leaks across the Kotlin/Native Objective-C interop boundary. globs: iosApp/**/*.{swift,h,m}, shared/src/iosMain/**/*.{kt,swift}, shared/src/commonMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-concurrency-cancellation-bridge-guardrail-kmp-swift-concur-498" --- # KMP Swift Concurrency Cancellation Bridge & Thread Leak Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dangling Swift CheckedContinuation Leaking Darwin Threads on Unbridged Kotlin Coroutine Cancellation ## System Constraints You are a Principal Mobile Architect enforcing absolute memory safety and concurrency invariants across Kotlin Multiplatform (KMP) and Swift Structured Concurrency boundaries. You MUST prevent Darwin thread pool starvation and unhandled continuation retention when bridging Kotlin Jobs and Swift Tasks. ## Strict Guidelines - Engineers MUST ALWAYS wrap Kotlin Native suspend functions or Flow collectors in Swift with `withTaskCancellationHandler` to forward Swift Task cancellations directly to the underlying Kotlin `Job.cancel(cause:)`. - Engineers MUST NOT rely on default Kotlin-to-Objective-C async bridge generation without handling `CancellationException` translation to Swift's native `CancellationError`. - Bridge adapters MUST guarantee that `CheckedContinuation` is resumed EXACTLY ONCE; dropping a continuation during a cancel or unhandled KMP exception permanently leaks Darwin worker threads. - Swift `TaskGroup` child tasks consuming Kotlin Flows MUST explicitly cancel their Kotlin Collector Jobs in an `onTermination` or `defer` block before leaving scope. - Engineers MUST NEVER dispatch asynchronous bridge callbacks onto unconfined GCD queues without thread-safe atomics or Actor isolation guarding continuation state transitions. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Async with Cancellation Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the parent Swift Task is cancelled before the Kotlin coroutine completes, the cancellation is never signaled to Kotlin. If Kotlin internally cancels or times out, the completion block is either skipped or delivers an unmapped CancellationException, leaving the Swift CheckedContinuation hanging forever and leaking a thread. ```swift import Shared // ANTI-PATTERN: Native suspend export invoked directly without Task cancellation hooks. // Cancelling the enclosing Swift Task leaves the Kotlin Job running indefinitely // and locks Darwin thread resources. func fetchUserProfile(userId: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in UserProfileRepository().getUserProfile(id: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } // BUG: If Swift Task is cancelled, Kotlin job remains active. // If Kotlin cancels silently with CancellationException, continuation never resumes. } } } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses `withTaskCancellationHandler` to immediately cancel the Kotlin `job` when Swift initiates task cancellation, wraps references atomically to avoid data races, and translates Kotlin cancellation exceptions directly into `CancellationError` ensuring the continuation is always resumed exactly once. ```swift import Shared // PRODUCTION INVARIANT: Bidirectional bridge with deterministic cancellation // and guaranteed single-resumption of Swift CheckedContinuation. func fetchUserProfile(userId: String) async throws -> UserProfile { let repository = UserProfileRepository() let canceller = AtomicKotlinJobHolder() return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in let job = repository.getUserProfile(id: userId) { profile, error in canceller.clear() if let error = error { let nsError = error as NSError if nsError.isKotlinCancellationException() { continuation.resume(throwing: CancellationError()) } else { continuation.resume(throwing: error) } } else if let profile = profile { continuation.resume(returning: profile) } else { continuation.resume(throwing: CancellationError()) } } canceller.set(job: job) } } onCancel: { canceller.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift Concurrency Cancellation Bridge & Thread Leak Invariant

KMP Swift Concurrency Cancellation Bridge & Thread Leak Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, bidirectional cancellation bridging between Kotlin Coroutines (Job) and Swift Structured Concurrency (Task/TaskGroup). Eliminates Darwin dispatch thread pool exhaustion and orphaned continuation memory leaks across the Kotlin/Native Objective-C interop boundary. 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 Swift CheckedContinuation Leaking Darwin Threads on Unbridged Kotlin Coroutine 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	Dangling Swift CheckedContinuation Leaking Darwin Threads on Unbridged Kotlin Coroutine 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 Native suspend functions or Flow collectors in Swift with `withTaskCancellationHandler` to forward Swift Task cancellations directly to the underlying Kotlin `Job.cancel(cause

Engineers MUST ALWAYS wrap Kotlin Native suspend functions or Flow collectors in Swift with `withTaskCancellationHandler` to forward Swift Task cancellations directly to the underlying Kotlin `Job.cancel(cause:)`.

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.