Deterministic Kotlin Coroutine to Swift Structured Concurrency Bridge

--- description: Deterministic Kotlin Coroutine to Swift Structured Concurrency Bridge - Enforces strict bidirectional cancellation propagation and lifecycle binding between Kotlin Coroutines and Swift Structured Concurrency. Prevents GCD worker thread-pool starvation and cross-runtime reference cycle memory leaks between Kotlin's GC and Swift ARC. 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-structured-concurrency-bridge" --- # Deterministic Kotlin Coroutine to Swift Structured Concurrency Bridge > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unmanaged Detached Task Bridging Leaking Zombie Coroutines and Native ARC Retain Cycles ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform (KMP) and Apple Platform Interoperability. You mandate deterministic concurrency boundaries between Kotlin Native and Swift. Enforce strict bidirectional cancellation mapping between Kotlin Coroutine Jobs and Swift Task hierarchies, eliminate detached Task spawns across the FFI boundary, and prevent retain cycles across the Kotlin GC / Apple ARC barrier. ## Strict Guidelines - Engineers MUST ALWAYS bind Swift `Task` cancellation to Kotlin `CancellableContinuation` or `Job.cancel()` via `withTaskCancellationHandler`. - Engineers MUST NOT bridge Kotlin suspending functions or `Flow` emissions using detached, unmanaged Swift `Task { ... }` blocks or escaping callbacks without lifecycle disposal. - Engineers MUST ensure Kotlin `CoroutineScope` instances on the native boundary are tied to explicit lifecycle owners (e.g., Swift `ObservableObject` or UIKit `UIViewController` deinitialization). - Services MUST clean up active `Job` references immediately upon Swift task completion or failure to prevent Kotlin-ObjC export wrapper retain cycles. - Components NEVER bridge Kotlin `StateFlow` or `SharedFlow` into Swift without wrapping emission listeners in cooperative cancellation-aware `AsyncSequence` or SKIE auto-generated async adapters. ## Bad vs Good Implementations ### Bridging Kotlin Suspending Function to Swift Async/Await with Deterministic Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to attach a cancellation handler leaves the underlying Kotlin coroutine executing indefinitely when the enclosing Swift Task is cancelled, causing thread-pool starvation and uncollected garbage across the runtime bridge. ```swift // BAD: Detached Task or naive completion bridge leaks Kotlin coroutine if Swift caller cancels func fetchUserData(userId: String) async throws -> UserProfile { return try await withCheckedThrowingContinuation { continuation in // Native Kotlin bridge invoking suspend function with a completion handler UserRepositoryBridge().fetchUser(id: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } } // Failure: If the calling Swift Task is cancelled, the Kotlin coroutine continues executing, // holding GCD threads and memory in the Kotlin runtime. } } ``` #### Production Standard (Correct) > **Standard**: Registers an onCancel closure that guarantees the underlying Kotlin Job is cancelled immediately when the calling Swift Task cancels, preserving cooperative execution semantics and freeing runtime resources. ```swift // GOOD: Bidirectional cancellation mapping using withTaskCancellationHandler and Job handle func fetchUserData(userId: String) async throws -> UserProfile { var job: KMPJob? = nil return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in job = UserRepositoryBridge().fetchUserWithJob(id: userId) { profile, error in if let error = error { continuation.resume(throwing: error) } else if let profile = profile { continuation.resume(returning: profile) } else { continuation.resume(throwing: CancellationError()) } } } } onCancel: { // Deterministically cancel the Kotlin Job when the Swift Task is cancelled job?.cancel(cause: nil) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Kotlin Coroutine to Swift Structured Concurrency Bridge

Deterministic Kotlin Coroutine to Swift Structured Concurrency Bridge defines an industrial-grade behavioral standard for mobile engineering. Enforces strict bidirectional cancellation propagation and lifecycle binding between Kotlin Coroutines and Swift Structured Concurrency. Prevents GCD worker thread-pool starvation and cross-runtime reference cycle memory leaks between Kotlin's GC and Swift ARC. 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: Unmanaged Detached Task Bridging Leaking Zombie Coroutines and Native ARC Retain Cycles 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	Unmanaged Detached Task Bridging Leaking Zombie Coroutines and Native ARC Retain Cycles	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 bind Swift `Task` cancellation to Kotlin `CancellableContinuation` or `Job.cancel()` via `withTaskCancellationHandler`.

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.