KMP Swift Export Strict Concurrency and Actor Isolation Standard

--- description: KMP Swift Export Strict Concurrency and Actor Isolation Standard - Enforces complete Swift 6 concurrency safety on Kotlin Multiplatform (KMP) exported boundaries by requiring explicit actor isolation and strict Sendable barriers. Prevents data races caused by crossing Swift actor domains with unconstrained, mutable Kotlin reference types bridged into native code. globs: **/shared/src/**/*.{kt,kts}, **/iosApp/**/*.{swift}, **/nativeInterop/**/*.{def,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-strict-concurrency-isolation" --- # KMP Swift Export Strict Concurrency and Actor Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking Uncontained Non-Sendable Kotlin Objects Across Swift 6 Concurrency Domains Without Actor Isolation ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform (KMP) Swift Export Strict Concurrency Actor Isolation. With Swift 6 complete concurrency enforcement, bridged Kotlin objects (inheriting from KotlinBase or generated via direct Swift Export) are non-Sendable reference types. You must ensure that no non-Sendable Kotlin bridge reference escapes actor isolation, all UI-touching KMP consumers are bound to @MainActor, and asynchronous background transfers across tasks project strictly Sendable value snapshots or actor-isolated facades. ## Strict Guidelines - Engineers MUST ALWAYS annotate Swift consumption facades with explicit actor boundaries (@MainActor or custom actor) when wrapping stateful KMP-generated classes. - Engineers MUST NOT pass raw KMP-generated reference objects across Swift Task or TaskGroup boundaries unless verified as deeply immutable and explicitly conforming to Sendable. - Swift code SHOULD convert Kotlin DTOs and state models into native Swift immutable Sendable structs before bridging across arbitrary concurrency contexts. - Kotlin-native asynchronous Flows MUST be collected within an actor-isolated context or mapped using an AsyncSequence that yields Sendable value types. - Components NEVER instantiate or mutate shared KMP repositories across concurrent Swift tasks without mutual exclusion enforced by a Swift actor wrapper. ## Bad vs Good Implementations ### Swift 6 Actor Isolation Barrier for Stateful KMP Repository #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Swift 6 Complete Concurrency, Kotlin-bridged types are reference types that do not conform to Sendable. Capturing self.kotlinRepo in a detached Task causes a compile-time strict concurrency error due to crossing actor domains with mutable shared state. ```swift import Shared // ANTI-PATTERN: Exposing non-Sendable Kotlin reference type directly across concurrent Swift 6 contexts public final class NativeUserManager { private let kotlinRepo: UserRepository // KotlinBase non-Sendable reference public init(repo: UserRepository) { self.kotlinRepo = repo } public func syncUserData() { Task.detached { // FAILS IN SWIFT 6: Sending non-Sendable property 'kotlinRepo' across concurrency domain let user = self.kotlinRepo.getCurrentUser() await self.updateUI(user: user) } } private func updateUI(user: User) async { // Mutable state mutated across thread boundaries without actor isolation } } ``` #### Production Standard (Correct) > **Standard**: The NativeUserManager is pinned to @MainActor, guaranteeing that the non-Sendable Kotlin reference is never accessed concurrently. Cross-domain data transfer utilizes an explicit Sendable Swift value-type struct (UserSnapshot). ```swift import Shared // PRODUCTION FIX: Pure Swift Sendable DTO snapshot and Actor-isolated facade public struct UserSnapshot: Sendable, Identifiable { public let id: String public let name: String init(from kotlinUser: User) { self.id = kotlinUser.id self.name = kotlinUser.name } } @MainActor public final class NativeUserManager: ObservableObject { private let kotlinRepo: UserRepository // Retained strictly within @MainActor @Published public private(set) var currentUser: UserSnapshot? public init(repo: UserRepository) { self.kotlinRepo = repo } public func syncUserData() async { // Execution remains isolated to MainActor; data crosses safely as Sendable snapshot let rawUser = self.kotlinRepo.getCurrentUser() self.currentUser = UserSnapshot(from: rawUser) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift Export Strict Concurrency and Actor Isolation Standard

KMP Swift Export Strict Concurrency and Actor Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces complete Swift 6 concurrency safety on Kotlin Multiplatform (KMP) exported boundaries by requiring explicit actor isolation and strict Sendable barriers. Prevents data races caused by crossing Swift actor domains with unconstrained, mutable Kotlin reference types bridged into native code. 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 Uncontained Non-Sendable Kotlin Objects Across Swift 6 Concurrency Domains Without Actor Isolation 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 Uncontained Non-Sendable Kotlin Objects Across Swift 6 Concurrency Domains Without Actor Isolation	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 annotate Swift consumption facades with explicit actor boundaries (@MainActor or custom actor) when wrapping stateful KMP-generated classes.

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.