KMP Swift Export Actor-Isolation and Cooperative Thread Pool Boundary Guardrail

--- description: KMP Swift Export Actor-Isolation and Cooperative Thread Pool Boundary Guardrail - Enforces strict isolation boundaries when bridging Kotlin Coroutines with Swift Actors across Kotlin Multiplatform's Swift Export and Objective-C interop layers. Prevents Swift cooperative thread-pool exhaustion and unsafe cross-actor mutable pointer access by mandating detached execution contexts, value-type payloads, and explicit cancellation mapping across the FFI runtime. globs: iosApp/**/*.swift, shared/src/iosMain/kotlin/**/*.kt, shared/src/commonMain/kotlin/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-actor-isolation-boundary" --- # KMP Swift Export Actor-Isolation and Cooperative Thread Pool Boundary Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Directly invoking blocking Kotlin Suspend functions from Swift Actors causing cooperative thread pool deadlock and data races ## System Constraints You are a Principal Engineer enforcing strict memory safety and concurrency invariants across the Kotlin Multiplatform (KMP) Swift Export and Swift Concurrency boundary. Mandate strict actor isolation, preventing any direct cross-actor mutation, unconfined dispatcher exposure, or unmanaged continuation bridging that can exhaust Swift's fixed cooperative thread pool. ## Strict Guidelines - Engineers MUST ALWAYS isolate Kotlin Coroutine callbacks outside Swift actor boundaries using nonisolated async wrapper functions or explicit Task.detached with checked continuations. - Engineers MUST NOT pass mutable Kotlin class instances across the Swift Export boundary into Swift actors without validating Sendable compliance or transforming payloads into immutable Swift structs or primitives. - Code SHOULD enforce bidirectional cancellation by linking Swift's Task cancellation handlers directly to Kotlin's kotlinx.coroutines.Job cancellation primitives via DisposableHandle. - Services MUST dispatch Kotlin suspend functions through Dispatchers.Default or a dedicated worker Dispatcher on the Kotlin side, NEVER allowing execution to seize the main thread or starve Swift's cooperative pool (libdispatch QoS inversion). - Components NEVER capture raw unmanaged Kotlin/Native stable pointers or raw object references inside long-lived Swift escaping closures without ARC ownership verification. ## Bad vs Good Implementations ### Bridging Kotlin Suspend Function to Swift Actor Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling KMP-generated suspend bridging functions within a Swift actor risks thread starvation on Swift's limited cooperative thread pool (number of CPU cores). If the Kotlin side switches dispatchers or performs synchronous I/O on the calling thread, it blocks the actor executor. Furthermore, assigning non-Sendable mutable KMP objects inside the actor violates Swift data-race safety. ```swift actor AccountSyncManager { private let kmpRepository: KmpAccountRepository private var cachedState: AccountState? init(repository: KmpAccountRepository) { self.kmpRepository = repository } func synchronize() async throws { // CRITICAL BUG: Direct call to KMP generated async bridges implicitly inherits actor executor // but Kotlin coroutine suspension interacts with pthread locks, blocking Swift's cooperative thread pool. // Passing mutable KMP reference allows direct actor-reentrant mutations. let rawResult = try await kmpRepository.fetchAccountDetails() self.cachedState = rawResult // Potential race condition & memory leak via Kotlin retain cycles } } ``` #### Production Standard (Correct) > **Standard**: The Kotlin suspend operation is executed in a detached task, isolating Swift's actor executor from cross-runtime suspension latency. Cancellation is mapped bidirectionally to avoid orphan coroutines, and mutable KMP references are mapped into an immutable Sendable Swift struct before crossing back into the actor. ```swift actor AccountSyncManager { private let kmpRepository: KmpAccountRepository private var cachedState: ImmutableAccountState? init(repository: KmpAccountRepository) { self.kmpRepository = repository } func synchronize() async throws { // Production Fix: Decouple execution context to prevent cooperative pool starvation, // map cancellation properly, and project into an immutable Sendable Swift model. let dto: ImmutableAccountState = try await Task.detached(priority: .userInitiated) { [repository = self.kmpRepository] in try await withTaskCancellationHandler { let rawKmpData = try await repository.fetchAccountDetails() return ImmutableAccountState(id: rawKmpData.id, balance: rawKmpData.balance) } onCancel: { repository.cancelFetch() } }.value self.cachedState = dto } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift Export Actor-Isolation and Cooperative Thread Pool Boundary Guardrail

KMP Swift Export Actor-Isolation and Cooperative Thread Pool Boundary Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation boundaries when bridging Kotlin Coroutines with Swift Actors across Kotlin Multiplatform's Swift Export and Objective-C interop layers. Prevents Swift cooperative thread-pool exhaustion and unsafe cross-actor mutable pointer access by mandating detached execution contexts, value-type payloads, and explicit cancellation mapping across the FFI runtime. 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: Directly invoking blocking Kotlin Suspend functions from Swift Actors causing cooperative thread pool deadlock and data races 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	Directly invoking blocking Kotlin Suspend functions from Swift Actors causing cooperative thread pool deadlock and data races	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 Coroutine callbacks outside Swift actor boundaries using nonisolated async wrapper functions or explicit Task.detached with checked continuations.

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.