KMP to Swift 6 Strict Concurrency Boundary & Actor Isolation Standard

--- description: KMP to Swift 6 Strict Concurrency Boundary & Actor Isolation Standard - Enforces thread-safe, `@Sendable`-compliant boundary transitions between Kotlin/Native Coroutines and Swift 6 Actor-isolated execution contexts. Eliminates unsafe pointer passing, silent cross-thread data races, and SIGSEGV memory faults originating from bridging Objective-C runtime references across 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-strict-concurrency-actor-bridge" --- # KMP to Swift 6 Strict Concurrency Boundary & Actor Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Exposing Raw KMP References to Swift Actors via Non-Sendable Bridges and Unbounded Callbacks ## System Constraints You are a Principal Mobile Systems Architect specializing in Kotlin Multiplatform and Swift 6 native runtime integration. Your mandate is to enforce absolute compile-time and runtime concurrency safety across the Kotlin/Native-Swift bridge under Swift 6 `-strict-concurrency=complete` mode. Disallow bridging mutable Kotlin reference types into Swift Actors without Sendable encapsulation. Mandate structured cancellation propagation from Swift `Task` trees to Kotlin `Job` handles, prevent escaping raw Kotlin callbacks across actor boundaries, and reject any bypass of Swift 6 data-race safety invariants. ## Strict Guidelines - Engineers MUST ALWAYS isolate Kotlin/Native interop wrappers using Swift 6 value types (structs/enums) conforming to `Sendable`, or annotate bridge adapters with `@preconcurrency import` accompanied by explicit synchronization wrappers. - Engineers MUST NOT cross Swift `actor` or `@MainActor` boundaries using raw, mutable Kotlin class instances generated by the Kotlin/Native Objective-C bridge. - Code SHOULD leverage SKIE (Swift-Kotlin Interface Enhancer) or explicitly map Kotlin `StateFlow`/`SharedFlow` into Swift `AsyncStream<SendableType>` with structured cancellation. - Services MUST bind Swift `withTaskCancellationHandler` directly to the underlying Kotlin `Job.cancel()` to prevent leaked background coroutine executions on iOS dispatch queues. - Components NEVER execute raw Kotlin callback closures directly inside Swift actor methods without explicit `@Sendable` boundary guarantees and thread handoffs via `Task` or `actor` executors. ## Bad vs Good Implementations ### Bridging Kotlin Flow to Swift 6 Actor Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin Native classes exported to Objective-C do not satisfy Swift 6 `Sendable` requirements. Bridging them into an actor via an unconstrained callback violates strict concurrency invariants, causing compiler errors under Swift 6 or undefined memory behavior when multiple threads access the Kotlin runtime pointer. ```swift // ANTI-PATTERN: Passing non-Sendable Kotlin Flow collector directly into Swift Actor // Bypasses Swift 6 Complete Concurrency, causes data races or crashes under strict mode import SharedKit actor AccountStateManager { private var currentState: AccountStateModel? // Bridged KMP class (non-Sendable) private let repository = SharedAccountRepository() // Kotlin Native instance func startObserving() { // Error: Kotlin completion block is not @Sendable, captures mutable KMP reference repository.observeAccountState { [weak self] state in Task { [weak self] in // Crosses actor boundary with non-sendable Kotlin reference await self?.updateState(state) } } } private func updateState(_ state: AccountStateModel) { self.currentState = state } } ``` #### Production Standard (Correct) > **Standard**: Transforms the Kotlin model into a pure Swift 6 `Sendable` value type immediately at the emission boundary, pipes emissions through `AsyncStream`, and cleanly propagates `onTermination` cancellation back to the Kotlin `Job` / `Cancellable`, fully respecting Swift 6 actor isolation. ```swift // PRODUCTION STANDARD: Isolated Sendable DTO boundary with structured cancellation import SharedKit public struct ImmutableAccountState: Sendable, Equatable { public let id: String public let balanceMicroUnits: Int64 public let isLocked: Bool } actor AccountStateManager { private var currentState: ImmutableAccountState? private let repository: SharedAccountRepository private var observationTask: Task<Void, Never>? init(repository: SharedAccountRepository) { self.repository = repository } func startObserving() { observationTask?.cancel() observationTask = Task { [weak self, repository] in let stream = AsyncStream<ImmutableAccountState> { continuation in let cancellable = repository.watchAccountState { // Explicitly transform Kotlin reference to Swift Sendable value type let sendableState = ImmutableAccountState( id: $0.id, balanceMicroUnits: $0.balanceMicroUnits, isLocked: $0.isLocked ) continuation.yield(sendableState) } continuation.onTermination = { @Sendable _ in cancellable.cancel() // Propagate cancellation to Kotlin Job } } for await state in stream { guard !Task.isCancelled else { break } self?.currentState = state } } } deinit { observationTask?.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP to Swift 6 Strict Concurrency Boundary & Actor Isolation Standard

KMP to Swift 6 Strict Concurrency Boundary & Actor Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces thread-safe, `@Sendable`-compliant boundary transitions between Kotlin/Native Coroutines and Swift 6 Actor-isolated execution contexts. Eliminates unsafe pointer passing, silent cross-thread data races, and SIGSEGV memory faults originating from bridging Objective-C runtime references across 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: Exposing Raw KMP References to Swift Actors via Non-Sendable Bridges and Unbounded Callbacks 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	Exposing Raw KMP References to Swift Actors via Non-Sendable Bridges and Unbounded Callbacks	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 interop wrappers using Swift 6 value types (structs/enums) conforming to `Sendable`, or annotate bridge adapters with `@preconcurrency import` accompanied by explicit synchronization wrappers.

Engineers MUST ALWAYS isolate Kotlin/Native interop wrappers using Swift 6 value types (structs/enums) conforming to `Sendable`, or annotate bridge adapters with `@preconcurrency import` accompanied by explicit synchronization wrappers.

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.