KMP Native Memory Isolation & Swift 6 Structured Concurrency Bridging

--- description: KMP Native Memory Isolation & Swift 6 Structured Concurrency Bridging - Governs thread-safe bidirectional state sharing and structured concurrency interop between Kotlin Coroutines and Swift 6 Sendable actors without GC pressure or main-thread hitching. Enforces SKIE/Swift-export bridging protocols, non-leaking cancellation token handlers, and immutable boundary transfer to satisfy strict Swift 6 concurrency invariants alongside Kotlin Native's Garbage Collector. globs: shared/src/commonMain/**/*.kt, shared/src/iosMain/**/*.kt, iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-memory-swift-concurrency-interop" --- # KMP Native Memory Isolation & Swift 6 Structured Concurrency Bridging > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bridging raw Kotlin Coroutine Flows and Shared State directly into Swift without Sendable wrappers, explicit scope lifetime management, and freeze/copy boundary invariants. ## System Constraints You are a Principal Mobile Architect enforcing strict Kotlin Multiplatform (KMP) Native Memory Isolation and Swift 6 Concurrency interop standards. Mandate thread-safe bidirectional state sharing, zero-copy read-only boundary patterns, and structured lifetime binding between Kotlin Coroutines and Swift 6 Task/Actor systems. Never permit unmanaged Job/Task lifetimes or mutable cross-runtime object graphs. ## Strict Guidelines - Engineers MUST ALWAYS expose Kotlin StateFlow and suspend functions to Swift via strictly typed, async-await and AsyncSequence bindings generated by tools such as SKIE or native Swift-Export. - Engineers MUST NEVER leak references across the Kotlin-Swift runtime boundary: objects crossing the boundary MUST either be deeply immutable value types (@Immutable/Sendable) or encapsulated behind concurrency-safe thread confinements (Swift Actors or Kotlin Channels with confined dispatchers). - Engineers MUST ALWAYS bridge Swift Task cancellation explicitly to Kotlin Coroutine Job cancellation using Swift's `withTaskCancellationHandler` to ensure native coroutines are cancelled when Swift scopes teardown. - Code MUST avoid passing Swift closures retaining Kotlin reference-counted bridge instances back into asynchronous Kotlin background dispatchers to prevent circular GC retention and cross-runtime memory leaks. - Services MUST ensure Kotlin Native GC runs deterministically without thread starvation by never blocking Kotlin Dispatchers.Default or Swift Cooperative Thread Pool worker threads with synchronous mutex locks crossing boundaries. ## Bad vs Good Implementations ### Swift 6 Cancellation and StateFlow Stream Consumption via AsyncSequence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw callbacks retain Kotlin references, fail Swift 6 strict concurrency checks (missing Sendable and Actor isolation), and cause zombie tasks on iOS when the enclosing object deallocates without explicit `closeable.close()` execution. ```swift import Shared // ANTI-PATTERN: Direct subscription to Flow without cancellation lifecycle management or Sendable boundary enforcement class UserProfileViewModel: ObservableObject { @Published var state: UserState? = nil private var closeable: KtorCloseable? = nil func observe(repository: UserRepository) { // Unstructured observation: leaks memory if view disappears, ignores Swift 6 concurrency actors self.closeable = repository.userFlow.watch { [weak self] state in DispatchQueue.main.async { self?.state = state } } } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates state inside Swift's `@MainActor`, uses `Task` with structured cancellation, and handles boundary items via Swift AsyncSequence mapped directly to Kotlin `StateFlow`, eliminating reference leaks and GC boundary deadlocks. ```swift import Shared // PRODUCTION FIX: Swift 6 Actor-isolated observation bridging SKIE/AsyncSequence with Task cancellation @MainActor public final class UserProfileViewModel: ObservableObject { @Published public private(set) var state: UserState private var observationTask: Task<Void, Never>? = nil public init(initialState: UserState) { self.state = initialState } public func startObserving(repository: UserRepository) { observationTask?.cancel() observationTask = Task { [weak self] in // SKIE or custom AsyncSequence bridge maintaining structured cancellation for await updatedState in repository.userFlow { guard !Task.isCancelled else { break } self?.state = updatedState } } } deinit { observationTask?.cancel() } } ``` ### Kotlin Native Coroutine Job Bridging to Swift Task Completion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns an unmanaged coroutine scope without cancellation propagation; invoking raw Swift callbacks directly from background Kotlin dispatchers violates Swift 6 Actor isolation and causes undefined thread jumps. ```kotlin // ANTI-PATTERN: Leaking suspend function bridge without Job cancellation hook across Objective-C interop package com.example.shared import kotlinx.coroutines.* class DataBridge { private val scope = CoroutineScope(Dispatchers.Default) fun fetchDataAsync(callback: (String) -> Unit) { scope.launch { val data = performLongRunningWork() callback(data) // Runs on Kotlin Dispatcher, invokes unisolated Swift pointer } } private suspend fun performLongRunningWork(): String = "payload" } ``` #### Production Standard (Correct) > **Standard**: Provides direct `suspend` hooks compatible with Swift async/await (or SKIE bridging), guarantees Main dispatcher callback boundaries, and returns a cancellation handle to bridge `withTaskCancellationHandler` on the Swift layer. ```kotlin // PRODUCTION FIX: Structured Suspend Bridge with Cancellation Token Support package com.example.shared import kotlinx.coroutines.* class DataBridge { private val supervisorScope = CoroutineScope(SupervisorJob() + Dispatchers.Default) @Throws(CancellationException::class, Exception::class) suspend fun fetchData(): String = withContext(Dispatchers.Default) { performLongRunningWork() } // Exposed bridge helper for native targets lacking direct suspend codegen fun fetchDataCancellable( onSuccess: (String) -> Unit, onError: (Throwable) -> Unit ): () -> Unit { val job = supervisorScope.launch { try { val result = performLongRunningWork() withContext(Dispatchers.Main) { onSuccess(result) } } catch (e: CancellationException) { // Structured cooperative cancellation } catch (t: Throwable) { withContext(Dispatchers.Main) { onError(t) } } } return { job.cancel() } } private suspend fun performLongRunningWork(): String = "payload" } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Native Memory Isolation & Swift 6 Structured Concurrency Bridging

KMP Native Memory Isolation & Swift 6 Structured Concurrency Bridging defines an industrial-grade behavioral standard for mobile engineering. Governs thread-safe bidirectional state sharing and structured concurrency interop between Kotlin Coroutines and Swift 6 Sendable actors without GC pressure or main-thread hitching. Enforces SKIE/Swift-export bridging protocols, non-leaking cancellation token handlers, and immutable boundary transfer to satisfy strict Swift 6 concurrency invariants alongside Kotlin Native's Garbage Collector. 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: Bridging raw Kotlin Coroutine Flows and Shared State directly into Swift without Sendable wrappers, explicit scope lifetime management, and freeze/copy boundary invariants. 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	Bridging raw Kotlin Coroutine Flows and Shared State directly into Swift without Sendable wrappers, explicit scope lifetime management, and freeze/copy boundary invariants.	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 expose Kotlin StateFlow and suspend functions to Swift via strictly typed, async-await and AsyncSequence bindings generated by tools such as SKIE or native Swift-Export.

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.