KMP Swift-Export Concurrency & Thread-Boundary Invariants

--- description: KMP Swift-Export Concurrency & Thread-Boundary Invariants - Enforces strict actor isolation, Sendable boundary enforcement, and cooperative cancellation propagation when bridging Kotlin Native Coroutines into Swift 6 Concurrency. Prevents cooperative thread pool starvation, ARC-to-Kotlin GC cross-runtime reference retention cycles, and actor reentrancy data corruption. globs: iosApp/**/*.swift, shared/src/commonMain/**/*.kt, shared/src/iosMain/**/*.kt, shared/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-concurrency-actor-invariants" --- # KMP Swift-Export Concurrency & Thread-Boundary Invariants > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Mutable Kotlin References Across Swift 6 Actor Boundaries Without Cancellation Synchronization ## System Constraints You are a Principal Engineer enforcing Kotlin Multiplatform (KMP) Swift-Export and Swift 6 Concurrency invariants. You must mandate deterministic actor isolation, strict non-blocking coroutine execution, Sendable conformance on export boundaries, and synchronous cancellation bridging across Swift Tasks and Kotlin Jobs. ## Strict Guidelines - Engineers MUST ALWAYS isolate Kotlin Native bridged stateful references within a dedicated Swift Actor or confine them to @MainActor; never pass mutable Kotlin Native objects across arbitrary Swift actor domains. - Engineers MUST ALWAYS wire Swift Task cancellation directly to Kotlin coroutine Job cancellation via `withTaskCancellationHandler` to prevent orphan jobs from leaking memory and draining device power. - Engineers MUST NOT execute blocking operations or unconfined Kotlin dispatchers (`Dispatchers.Unconfined`) within exported suspend functions bridged into Swift cooperative thread pools. - Services MUST project Kotlin Flow and Coroutine emissions across the Swift boundary exclusively via immutable, Sendable DTOs or primitive value types, never raw mutable state holders. - Components NEVER bridge async operations using unmanaged completion handlers that capture `self` strongly, avoiding bidirectional ARC-GC retention cycles between Kotlin's Garbage Collector and Swift's Automatic Reference Counting. ## Bad vs Good Implementations ### Bridging Kotlin Suspend to Swift 6 Actor with Cancellation and Sendable Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example violates Swift 6 strict concurrency checks: the Kotlin class reference escapes actor boundaries without Sendable protection, completion handlers create memory leaks between ARC and Kotlin GC, and canceling the Swift Task fails to cancel the underlying Kotlin coroutine Job. ```swift // Flawed Swift 6 bridging: mutable Kotlin reference cross-actor leak, no cancellation wiring, strong self cycle class UserRepositoryBridge { private let kotlinRepository: SharedUserRepository // Kotlin Native class reference func fetchUserProfile(userId: String) async -> UserProfileDTO? { // BAD: Escapes actor domain; ignores Swift Task cancellation; leaks Kotlin Job if Task is canceled return await withCheckedContinuation { continuation in kotlinRepository.fetchUser(id: userId) { profile, error in continuation.resume(returning: profile) } } } } ``` #### Production Standard (Correct) > **Standard**: The good example encapsulates the non-Sendable Kotlin Native object within a Swift actor, maps response types into an immutable Swift Sendable struct, and wires `withTaskCancellationHandler` directly to the Kotlin Coroutine Job handle to guarantee deterministic cancellation. ```swift // Robust Swift 6 Actor bridge: strict isolation, cooperative cancellation hook, and Sendable projection public actor UserProfileManager { private let repository: SharedUserRepository public init(repository: SharedUserRepository) { self.repository = repository } public func fetchUserProfile(userId: String) async throws -> SwiftUserProfile { var jobHandle: Kotlinx_coroutines_coreJob? = nil return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in jobHandle = repository.fetchUser( id: userId, onSuccess: { profile in // Convert to Swift-native Sendable struct at boundary continuation.resume(returning: SwiftUserProfile(from: profile)) }, onError: { error in continuation.resume(throwing: error.asSwiftError()) } ) } } onCancel: { // Cancel underlying Kotlin Job immediately when Swift Task is canceled jobHandle?.cancel(cause: nil) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift-Export Concurrency & Thread-Boundary Invariants

KMP Swift-Export Concurrency & Thread-Boundary Invariants defines an industrial-grade behavioral standard for mobile engineering. Enforces strict actor isolation, Sendable boundary enforcement, and cooperative cancellation propagation when bridging Kotlin Native Coroutines into Swift 6 Concurrency. Prevents cooperative thread pool starvation, ARC-to-Kotlin GC cross-runtime reference retention cycles, and actor reentrancy data corruption. 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: Leaking Mutable Kotlin References Across Swift 6 Actor Boundaries Without Cancellation Synchronization 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	Leaking Mutable Kotlin References Across Swift 6 Actor Boundaries Without Cancellation Synchronization	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 isolate Kotlin Native bridged stateful references within a dedicated Swift Actor or confine them to @MainActor

Engineers MUST ALWAYS isolate Kotlin Native bridged stateful references within a dedicated Swift Actor or confine them to @MainActor; never pass mutable Kotlin Native objects across arbitrary Swift actor domains.

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.