Swift 6 Actor Isolation and Sendable Safety for KMP Export Boundaries

--- description: Swift 6 Actor Isolation and Sendable Safety for KMP Export Boundaries - Enforces complete compile-time data race safety under Swift 6 strict concurrency when consuming Kotlin Multiplatform (KMP) shared framework binaries. Prohibits direct access to non-Sendable Kotlin runtime object graphs across native Swift actor or Task boundaries without explicit actor isolation or value-type bridging. globs: iosApp/**/*.swift, shared/**/*.kt, **/*Bridge*.swift, **/*RepositoryAdapter*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swift-6-kmp-native-export-actor-boundary" --- # Swift 6 Actor Isolation and Sendable Safety for KMP Export Boundaries > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Passing Unchecked Mutable KMP Objective-C Export References Across Swift Concurrency Boundaries ## System Constraints You are a Principal Mobile Architect enforcing Swift 6 Complete Concurrency Checking and Kotlin Multiplatform Native export invariants. You must prevent memory corruption, runtime freeze panics, and data races when KMP Objective-C exported classes cross Swift 6 actor boundaries. Enforce Sendable wrappers, value-type snapshotting, or dedicated Actor-isolation for all shared state. ## Strict Guidelines - Engineers MUST treat all KMP Objective-C runtime classes (subclasses of KotlinBase) as non-Sendable by default under Swift 6 strict concurrency. - Engineers MUST NOT cross async Task or actor isolation boundaries using raw mutable KMP shared references without explicit value projection or thread confinement. - Engineers MUST confine KMP object graph lifecycles to a dedicated actor (e.g., @MainActor or a bespoke global actor like KotlinRuntimeActor) or project them immediately into Swift native Sendable structs. - Engineers MUST NOT decorate unverified KMP Objective-C class instances with @unchecked Sendable unless the underlying Kotlin object is provably thread-safe, immutable, and protected against concurrent mutation. - Bridge adapters MUST consume Kotlin Coroutines via structured async/await adapters that strictly return Sendable native Swift DTOs or collections. - Components NEVER expose live Kotlin Flow collectors directly across multiple uncoordinated Swift actors without converting the sequence to an AsyncStream projecting Sendable elements. ## Bad vs Good Implementations ### KMP Bridge Boundary Crossing with Actor Isolation vs Unchecked Reference Sharing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: KotlinBase classes exported to Objective-C headers lack Sendable annotations. Moving self.kotlinRepository and returning mutable SharedUser across an uncoordinated Task.detached triggers Swift 6 strict concurrency compiler errors and risks native runtime crashes due to Kotlin/Native ARC boundary mismatches. ```swift import Shared // ANTI-PATTERN: Direct exposure of non-Sendable KMP reference across Swift 6 concurrency boundaries final class SessionManager { private let kotlinRepository: SharedUserRepository init(repository: SharedUserRepository) { self.kotlinRepository = repository } func refreshUserProfile() async -> UserProfileModel { // SharedUserRepository (KotlinBase) is non-Sendable. // Dispatching to detached or parallel tasks causes Swift 6 compile-time error // or leads to memory corruption across native thread boundaries. return await Task.detached { let kmpUser = self.kotlinRepository.getCurrentUser() return kmpUser // Error: non-Sendable type 'SharedUser' returned across actor boundaries }.value } } ``` #### Production Standard (Correct) > **Standard**: The KMP repository is isolated entirely to a dedicated global actor (KotlinRuntimeActor). All calls crossing Swift concurrency boundaries return immutable, native Sendable structs (UserProfileSnapshot), guaranteeing strict Swift 6 data-race freedom at compile time. ```swift import Shared // PRODUCTION INVARIANT: Value-type projection and strict actor isolation public struct UserProfileSnapshot: Sendable, Equatable { public let id: String public let displayName: String public let email: String } @globalActor public actor KotlinRuntimeActor { public static let shared = KotlinRuntimeActor() } @KotlinRuntimeActor public final class SafeSessionBridge { private let kotlinRepository: SharedUserRepository public init(repository: SharedUserRepository) { self.kotlinRepository = repository } public func fetchUserProfile() async throws -> UserProfileSnapshot { // Execution is strictly isolated to KotlinRuntimeActor. // Values crossing the boundary are mapped immediately to Sendable Swift structs. let kmpUser = try await self.kotlinRepository.getCurrentUserAsync() return UserProfileSnapshot( id: kmpUser.id, displayName: kmpUser.displayName, email: kmpUser.email ) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Swift 6 Actor Isolation and Sendable Safety for KMP Export Boundaries

Swift 6 Actor Isolation and Sendable Safety for KMP Export Boundaries defines an industrial-grade behavioral standard for mobile engineering. Enforces complete compile-time data race safety under Swift 6 strict concurrency when consuming Kotlin Multiplatform (KMP) shared framework binaries. Prohibits direct access to non-Sendable Kotlin runtime object graphs across native Swift actor or Task boundaries without explicit actor isolation or value-type bridging. 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: Passing Unchecked Mutable KMP Objective-C Export References Across Swift Concurrency Boundaries 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	Passing Unchecked Mutable KMP Objective-C Export References Across Swift Concurrency Boundaries	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 treat all KMP Objective-C runtime classes (subclasses of KotlinBase) as non-Sendable by default under Swift 6 strict concurrency.

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.