KMP Native Darwin Coroutine Memory Ownership & Runloop Decoupling Standard

--- description: KMP Native Darwin Coroutine Memory Ownership & Runloop Decoupling Standard - Enforces strict unidirectional memory ownership and explicit scope teardown between Kotlin/Native coroutine runtimes and Apple platform ARC runloops. Prevents bidirectional reference cycles between Swift ARC-managed instances and Kotlin/Native GC roots that trigger worker thread exhaustion and process-level deadlocks. Guarantees non-blocking dispatch boundary isolation across Apple DispatchQueues and Kotlin Dispatchers. globs: **/iosApp/**/*.swift, **/shared/**/darwinMain/**/*.kt, **/shared/**/iosMain/**/*.kt, **/shared/**/appleMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-darwin-coroutine-arc-ownership-invariant" --- # KMP Native Darwin Coroutine Memory Ownership & Runloop Decoupling Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining Long-Lived Kotlin Coroutine Scopes in Swift ARC Objects Without Cooperative Cancellation Hooks ## System Constraints You are a Principal Mobile Architect enforcing strict memory and threading boundaries between Kotlin Multiplatform (Native) and Apple Darwin runtimes. You must eliminate all bidirectional strong retain cycles between Swift ARC references and Kotlin/Native GC roots. You must ensure all exposed Flows, Suspend functions, and CoroutineScopes bridge safely into Darwin's lifecycle without deadlocking MainRunLoop or leaking background worker threads. ## Strict Guidelines - Engineers MUST ALWAYS tie bridged Kotlin CoroutineScopes or Jobs directly to Darwin lifecycle boundaries (e.g., SwiftUI .task, UIViewController deinit, or Swift structured Concurrency Task.cancel). - Engineers MUST NOT capture strong Swift self references within escaping closures passed to Kotlin suspend functions or CoroutineScope builders. - Code MUST wrap long-lived Flow collectors on Darwin platforms in disposable handles or SKIE auto-cancelling wrappers to ensure swift deinit immediately cancels the underlying Kotlin Job. - Services MUST NEVER invoke Kotlin runBlocking on the Darwin Main Dispatch Queue (MainThread), as it produces fatal dispatch deadlocks with Apple's RunLoop. - Components NEVER expose raw global CoroutineScope (e.g., GlobalScope) across the Kotlin/Native boundary; all boundary entry points must accept or bind to a strictly bounded, cancellable Job hierarchy. ## Bad vs Good Implementations ### Darwin Swift ViewModel Consuming Kotlin KMP Coroutine/Flow #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The watch closure retains a strong reference to self while the Kotlin collector retains the closure as a GC root. Because the returned watch cancellation token is discarded, neither ARC nor the Kotlin/Native GC can collect the cycle, leaking worker threads and memory. ```swift import shared final class ProfileViewModel: ObservableObject { private let repository = UserRepository() @Published var user: User? = nil func startObserving() { // BAD: Escaping closure captures strong 'self', underlying Kotlin Job // is unmanaged and retains the Swift class via the completion callback. // If ProfileViewModel is popped, the collector thread leaks permanently. repository.observeUser().watch { [self] user in self.user = user } } } ``` #### Production Standard (Correct) > **Standard**: Uses Swift structured concurrency (or SKIE async-stream bridging) bound to an explicit Task. self is captured weakly, preventing ARC retain cycles. Cancellation is explicitly triggered on deinit, breaking the GC root in Kotlin/Native. ```swift import shared import Combine final class ProfileViewModel: ObservableObject { private let repository = UserRepository() @Published var user: User? = nil private var observationTask: Task<Void, Never>? = nil func startObserving() { observationTask?.cancel() // GOOD: Bounded Swift Task lifecycle with weak capture observationTask = Task { [weak self] in do { for await user in self?.repository.observeUser() ?? [] { guard !Task.isCancelled else { break } await MainActor.run { [weak self] in self?.user = user } } } catch { // Handle cancellation or stream termination gracefully } } } deinit { // Guarantees ARC deallocation triggers immediate Kotlin coroutine cancellation observationTask?.cancel() } } ``` ### Kotlin/Native Darwin Main Thread Dispatcher Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking runBlocking on Darwin's Main thread starves the Apple CFRunLoop and Mach port messaging, resulting in Watchdog termination (0x8badf00d) or immediate deadlocks. ```kotlin // BAD: Blocking the Darwin main thread waiting for an async job fun fetchInitialDataBlocking(): ProfileData = runBlocking(Dispatchers.Main) { // Invoking runBlocking on Darwin Main blocks the CFRunLoop, // deadlocking whenever underlying calls dispatch back to Main apiClient.loadProfile() } ``` #### Production Standard (Correct) > **Standard**: Uses Dispatchers.Main.immediate with an isolated SupervisorJob, exposing a DisposableHandle to the Apple caller. Cancellation is explicitly cooperative without blocking the Darwin runloop. ```kotlin // GOOD: Fully asynchronous Darwin boundary with cooperative cancellation support fun fetchInitialDataAsync( onSuccess: (ProfileData) -> Unit, onError: (Throwable) -> Unit ): DisposableHandle { val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate) val job = scope.launch { try { val profile = apiClient.loadProfile() onSuccess(profile) } catch (e: CancellationException) { throw e } catch (t: Throwable) { onError(t) } } return DisposableHandle { job.cancel() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Native Darwin Coroutine Memory Ownership & Runloop Decoupling Standard

KMP Native Darwin Coroutine Memory Ownership & Runloop Decoupling Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict unidirectional memory ownership and explicit scope teardown between Kotlin/Native coroutine runtimes and Apple platform ARC runloops. Prevents bidirectional reference cycles between Swift ARC-managed instances and Kotlin/Native GC roots that trigger worker thread exhaustion and process-level deadlocks. Guarantees non-blocking dispatch boundary isolation across Apple DispatchQueues and Kotlin Dispatchers. 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: Retaining Long-Lived Kotlin Coroutine Scopes in Swift ARC Objects Without Cooperative Cancellation Hooks 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	Retaining Long-Lived Kotlin Coroutine Scopes in Swift ARC Objects Without Cooperative Cancellation Hooks	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 tie bridged Kotlin CoroutineScopes or Jobs directly to Darwin lifecycle boundaries (e.g., SwiftUI .task, UIViewController deinit, or Swift structured Concurrency Task.cancel).

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.