Kotlin Multiplatform Swift 6 Actor Bridge Isolation Standard

--- description: Kotlin Multiplatform Swift 6 Actor Bridge Isolation Standard - Enforces strict Swift 6 actor isolation boundaries over Kotlin Multiplatform (KMP) coroutine dispatchers and shared native references. Eliminates memory corruption, thread deadlocks, and data races caused by escaping non-Sendable Objective-C bridged pointers into Swift concurrency domains. 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-swift6-actor-bridge-isolation-standard" --- # Kotlin Multiplatform Swift 6 Actor Bridge Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Escaping Non-Sendable Kotlin Native References Across Swift 6 Structured Concurrency Domains ## System Constraints You are a Principal Mobile Architect enforcing the Kotlin Multiplatform (KMP) Swift 6 Actor Bridge Isolation Standard. You must reject any interop code that passes raw, non-Sendable Kotlin Native objects across Swift concurrency domains. Ensure all bridged Kotlin coroutine jobs, flows, and suspend calls are encapsulated in Swift actors, pinned to @MainActor where UI-bound, and translated into immutable Swift Sendable value types at the interface boundary. ## Strict Guidelines - Engineers MUST ALWAYS isolate Kotlin Native suspend and Flow bridges within a dedicated Swift `actor` or pin them to `@MainActor`. - Engineers MUST NOT cross Swift 6 concurrency domains with raw Kotlin Native references; all data crossing the bridge MUST be mapped to Swift `@Sendable` structs or primitive value types. - Engineers MUST NEVER use `@unchecked Sendable` on bridged Kotlin class hierarchies without verified, documented thread-safety and immutable memory pinning. - Bridge wrappers MUST wire Swift `Task` cancellation to the underlying Kotlin `Job` or `Cancellable` instance to prevent detached background execution leaks. - Components NEVER invoke Kotlin Coroutine bridge dispatchers synchronously from an isolated actor context, preventing thread deadlocks between Swift's cooperative pool and Kotlin's worker dispatchers. ## Bad vs Good Implementations ### Bridging Kotlin Shared State Flow to Swift 6 Concurrency #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin Native instances generated through the Objective-C interop header are implicitly non-Sendable. Passing them into detached Swift tasks or across dispatch queues triggers Swift 6 strict concurrency errors, invalid memory dereferencing in the Kotlin Native garbage collector, and potential deadlocks when concurrent mutation occurs. ```swift // BAD: Consuming raw Kotlin Flow directly in Swift 6 without actor isolation import SharedKit import SwiftUI final class ProfileViewModel: ObservableObject { @Published var state: ProfileState? // ProfileState is a generated non-Sendable ObjC class private let repository = ProfileRepository() // Bridged Kotlin class func startObserving() { Task.detached { // Violation: Capturing non-Sendable Kotlin repository across concurrency domain // Violation: Unisolated Flow observation causes data race and memory corruption self.repository.observeProfile().collect(collector: FlowCollector { profile in Task { @MainActor in self.state = profile } }) { error in print("Error: \(String(describing: error))") } } } } ``` #### Production Standard (Correct) > **Standard**: The Kotlin interop object is strictly contained within the `ProfileBridgeCoordinator` actor. Data emitted across the boundary is immediately transformed into a Swift `Sendable` value-type (`UserProfile`). Structured concurrency ensures cancellation propagates directly to the Kotlin coroutine job, preserving thread safety under Swift 6 strict concurrency rules. ```swift // GOOD: Enforcing Swift 6 actor isolation and mapping to Sendable value types import SharedKit import SwiftUI // 1. Immutable Swift domain model conforming to Sendable public struct UserProfile: Sendable, Identifiable { public let id: String public let displayName: String } // 2. Actor isolation for the non-Sendable Kotlin Native boundary actor ProfileBridgeCoordinator { private let repository: ProfileRepository private var activeJob: SharedKit.Cancellable? init(repository: ProfileRepository = ProfileRepository()) { self.repository = repository } func profileStream() -> AsyncThrowingStream<UserProfile, Error> { AsyncThrowingStream { continuation in let job = self.repository.observeProfile().collect(collector: FlowCollector { profile in guard let profile = profile else { return } // Map non-Sendable Kotlin reference to Swift Sendable value type let mapped = UserProfile(id: profile.id, displayName: profile.displayName) continuation.yield(mapped) }) { error in if let error = error { continuation.finish(throwing: error) } else { continuation.finish() } } continuation.onTermination = { @Sendable _ in job.cancel() } } } } // 3. UI Layer strictly bound to MainActor @MainActor final class ProfileViewModel: ObservableObject { @Published private(set) var state: UserProfile? private let coordinator = ProfileBridgeCoordinator() private var observationTask: Task<Void, Never>? func startObserving() { observationTask?.cancel() observationTask = Task { [weak self] in do { for try await profile in await self?.coordinator.profileStream() ?? AsyncThrowingStream({ $0.finish() }) { guard !Task.isCancelled else { break } self?.state = profile } } catch { // Handle structured isolation error } } } deinit { observationTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift 6 Actor Bridge Isolation Standard

Kotlin Multiplatform Swift 6 Actor Bridge Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict Swift 6 actor isolation boundaries over Kotlin Multiplatform (KMP) coroutine dispatchers and shared native references. Eliminates memory corruption, thread deadlocks, and data races caused by escaping non-Sendable Objective-C bridged pointers into Swift concurrency domains. 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: Escaping Non-Sendable Kotlin Native References Across Swift 6 Structured Concurrency Domains 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	Escaping Non-Sendable Kotlin Native References Across Swift 6 Structured Concurrency Domains	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 suspend and Flow bridges within a dedicated Swift `actor` or pin them to `@MainActor`.

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.