Kotlin Multiplatform Swift-ARC Cross-Runtime Memory Cycle Isolation

--- description: Kotlin Multiplatform Swift-ARC Cross-Runtime Memory Cycle Isolation - Enforces deterministic memory boundaries across the Kotlin/Native Garbage Collector and Apple Automatic Reference Counting (ARC) runtime bridge. Eliminates dual-runtime retain cycles where Swift objects retain Kotlin objects that indirectly retain Swift callbacks or delegates via Objective-C bridge wrappers, leading to catastrophic native memory leaks and frozen uncollected roots. globs: **/*.kt, **/*.swift, iosApp/**/*.swift, shared/src/commonMain/**/*.kt, shared/src/iosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-arc-cross-runtime-cycle-isolation" --- # Kotlin Multiplatform Swift-ARC Cross-Runtime Memory Cycle Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bypassing weak reference semantics across the Swift/KMP bridge creating cross-runtime zombie retain cycles ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Apple ARC interop. Enforce strict isolation boundaries between Kotlin/Native's mark-and-sweep garbage collector and Swift's ARC. Prevent cross-runtime reference cycle deadlocks by mandating explicit unsubscription tokens, weak proxy adapters, and closure decoupling across foreign function boundaries. ## Strict Guidelines - Engineers MUST ALWAYS capture `[weak self]` inside any Swift closure or callback supplied to an exported Kotlin component, Flow, or suspend function wrapper. - Engineers MUST NEVER allow an exported Kotlin class to retain a strong reference to a Swift protocol implementer; delegate properties in Kotlin targeting iOS consumers MUST use a weak holder or explicit unbind lifecycle pattern. - Code SHOULD enforce deterministic cancellation via `Closeable` or `Cancellable` subscription tokens that Swift clients invoke in `deinit` or UI lifecycle teardown (`viewDidDisappear`). - Services MUST NOT store Swift callback lambdas in long-lived Kotlin singletons, global scopes, or static companion objects without exposing explicit release mechanisms. - Components NEVER bridge bidirectional observer relationships without breaking the ARC-to-GC edge; either the Swift observer holds a weak handle or the Kotlin source releases its observer table upon client disposal. ## Bad vs Good Implementations ### Swift-KMP Flow Subscription Cycle Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Kotlin `SharedUserManager` maintains a strong reference to the Objective-C/Swift bridge block. The block captures `self` strongly, while `self` strongly retains `userManager`. The Kotlin Native GC and Swift ARC cannot cross-collect this circular dependency, leaking both the native Swift view model and the Kotlin coroutine hierarchy. ```swift class ProfileViewModel { private let userManager: SharedUserManager // Kotlin class retained by Swift ARC private var observationTask: Task<Void, Never>? init(userManager: SharedUserManager) { self.userManager = userManager // ANTI-PATTERN: Strong capture of self in Swift closure passed to Kotlin Flow collection // The Kotlin Flow wrapper retains the closure, which retains self, while self retains userManager self.userManager.observeUserState { state in self.updateUi(state: state) } } func updateUi(state: UserState) { // State updates } } ``` #### Production Standard (Correct) > **Standard**: Capturing `[weak self]` prevents the Objective-C callback block from holding an owning ARC retain count on `ProfileViewModel`. Returning an explicit `CloseableHandle` allows `deinit` to notify the Kotlin/Native GC to release its listener reference, cleanly reclaiming memory in both runtimes. ```swift class ProfileViewModel { private let userManager: SharedUserManager private var cancellableToken: CloseableHandle? init(userManager: SharedUserManager) { self.userManager = userManager // Explicit weak capture and cancellation handle registration self.cancellableToken = self.userManager.observeUserState( onState: { [weak self] state in guard let self = self else { return } self.updateUi(state: state) } ) } func updateUi(state: UserState) { // State updates } deinit { // Break cross-runtime bridge connection deterministically cancellableToken?.close() cancellableToken = nil } } ``` ### Kotlin Listener Interface Bridging with Weak Proxying #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When Swift implements `NetworkListener` on an object that also retains `NetworkMonitor`, a cross-runtime cycle forms. The Kotlin GC root references the Swift delegate through the Objective-C proxy, preventing ARC from releasing the Swift instance, and Swift retains the Kotlin monitor. ```kotlin // shared/src/iosMain/kotlin/NetworkMonitor.kt interface NetworkListener { fun onNetworkChanged(isAvailable: Boolean) } class NetworkMonitor { // ANTI-PATTERN: Strong reference to Swift-implemented interface private val listeners = mutableListOf<NetworkListener>() fun addListener(listener: NetworkListener) { listeners.add(listener) } fun notify(available: Boolean) { listeners.forEach { it.onNetworkChanged(available) } } } ``` #### Production Standard (Correct) > **Standard**: Wrapping the Swift-implemented `NetworkListener` inside Kotlin's `WeakReference` prevents the Kotlin runtime from creating an artificial strong retain root on the Objective-C object proxy, enabling ARC to deallocate the Swift listener naturally when its owning scope exits. ```kotlin // shared/src/iosMain/kotlin/NetworkMonitor.kt import kotlin.native.ref.WeakReference interface NetworkListener { fun onNetworkChanged(isAvailable: Boolean) } class NetworkMonitor { private val listeners = mutableListOf<WeakReference<NetworkListener>>() fun addListener(listener: NetworkListener) { listeners.add(WeakReference(listener)) } fun notify(available: Boolean) { val iterator = listeners.iterator() while (iterator.hasNext()) { val listener = iterator.next().get() if (listener != null) { listener.onNetworkChanged(available) } else { iterator.remove() // Purge collected references } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift-ARC Cross-Runtime Memory Cycle Isolation

Kotlin Multiplatform Swift-ARC Cross-Runtime Memory Cycle Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic memory boundaries across the Kotlin/Native Garbage Collector and Apple Automatic Reference Counting (ARC) runtime bridge. Eliminates dual-runtime retain cycles where Swift objects retain Kotlin objects that indirectly retain Swift callbacks or delegates via Objective-C bridge wrappers, leading to catastrophic native memory leaks and frozen uncollected roots. 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: Bypassing weak reference semantics across the Swift/KMP bridge creating cross-runtime zombie retain cycles 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	Bypassing weak reference semantics across the Swift/KMP bridge creating cross-runtime zombie retain cycles	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 capture `[weak self]` inside any Swift closure or callback supplied to an exported Kotlin component, Flow, or suspend function wrapper.

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.