KMP Swift-ARC and Kotlin/Native GC Weak Reference Bridge Standard

--- description: KMP Swift-ARC and Kotlin/Native GC Weak Reference Bridge Standard - Prevents catastrophic cross-runtime retain cycles and memory leaks across the Swift ARC and Kotlin/Native tracing GC boundary. Enforces non-capturing closures, weak bridging wrappers, and deterministic lifecycle disposal for bidirectional delegates and flow subscriptions. globs: **/*iosMain*/**/*.kt, **/*appleMain*/**/*.kt, iosApp/**/*.swift, **/*Bridge*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-arc-gc-weak-reference-bridge" --- # KMP Swift-ARC and Kotlin/Native GC Weak Reference Bridge Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bidirectional Strong Retain Cycles Bridging Swift ARC Object Graphs to Kotlin Native GC ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Apple runtime internals. Mandate and enforce deterministic memory safety across the Kotlin/Native GC and Swift ARC interop boundary. Prevent cross-runtime retain cycles where Swift strong references prevent Kotlin GC sweeps and Kotlin GC objects keep Swift ARC instances pinned in memory indefinitely. ## Strict Guidelines - Engineers MUST ALWAYS wrap Swift-implemented interfaces and protocols stored in Kotlin/Native via `kotlin.native.ref.WeakReference` to break cross-runtime strong retain cycles. - Engineers MUST NOT pass escaping Swift closures that capture `self` strongly into Kotlin Coroutines, Kotlin Flows, or persistent Kotlin ViewModel delegates. - Swift consumers of Kotlin ViewModels or Presenters MUST store the Kotlin instance using ARC `strong` only if the Kotlin instance does not maintain an implicit or explicit reverse pointer to the Swift owner. - Services exposing Kotlin `SharedFlow` or `StateFlow` to Swift MUST mandate an explicit lifecycle subscription token or `Cancellable` that Swift callers invoke in `deinit` or UI dismiss cycles. - Components NEVER store direct strong references to iOS platform classes (`UIViewController`, `UIView`, `UIApplicationDelegate`) inside KMP singleton or shared companion objects. ## Bad vs Good Implementations ### Kotlin/Native Delegate Bridge: Strong Bridge Ref vs WeakReference Wrapper #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin/Native retains the Objective-C/Swift instance pointer strongly as a GC root, while Swift retains BridgePresenter via ARC. The Kotlin tracing GC and Swift ARC cannot traverse across runtime boundaries to break the cycle, resulting in an unrecoverable leak. ```kotlin package com.example.kmp.bridge interface NativeUiListener { fun onDataLoaded(data: String) } // ANTI-PATTERN: Holding a direct strong reference to a Swift ARC delegate. // When Swift ViewController strongly holds BridgePresenter, and // BridgePresenter holds NativeUiListener (the ViewController), both runtimes // fail to release the objects, leaking memory permanently. class BridgePresenter(private val listener: NativeUiListener) { fun loadData() { val result = "Payload" listener.onDataLoaded(result) } } ``` #### Production Standard (Correct) > **Standard**: Using `kotlin.native.ref.WeakReference` ensures Kotlin/Native GC does not pin the Swift instance in memory. When the Swift ViewController is dismissed, ARC deallocates it immediately, and `weakListener.value` safely evaluates to null. ```kotlin package com.example.kmp.bridge import kotlin.native.ref.WeakReference interface NativeUiListener { fun onDataLoaded(data: String) } // PRODUCTION FIX: Wrap Swift ARC delegate in Kotlin/Native WeakReference. // Permits Swift runtime to deallocate the ViewController, leaving the // weak reference in Kotlin to cleanly evaluate to null without leaking. class BridgePresenter(listener: NativeUiListener) { private val weakListener: WeakReference<NativeUiListener> = WeakReference(listener) fun loadData() { val result = "Payload" weakListener.value?.onDataLoaded(result) } fun clear() { // Explicit cleanup hook for Swift lifecycle deinit weakListener.clear() } } ``` ### Swift Collector Bridge: Capturing self vs Weak Capture with Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Swift closure captures `self` strongly and is passed into the Kotlin runtime. As long as the Kotlin `UserViewModel` retains the observer closure, `UserProfileViewController` cannot be deallocated by ARC upon navigation pop. ```swift import UIKit import SharedKit final class UserProfileViewController: UIViewController { private let viewModel = UserViewModel() override func viewDidLoad() { super.viewDidLoad() // ANTI-PATTERN: Escaping closure captures `self` strongly. // If ViewModel holds the closure/cancellable without lifecycle bounding, // UserProfileViewController is permanently retained by Kotlin GC. viewModel.observeState { state in self.updateUI(with: state) } } private func updateUI(with state: UserState) { // Update UI components } } ``` #### Production Standard (Correct) > **Standard**: Swift explicitly captures `[weak self]` in the closure, preventing the Kotlin runtime from owning the Swift ViewController. Retaining and cancelling the `CancellableTask` in `deinit` guarantees deterministic cleanup on both runtimes. ```swift import UIKit import SharedKit final class UserProfileViewController: UIViewController { private let viewModel = UserViewModel() private var observationTask: SharedKit.CancellableTask? override func viewDidLoad() { super.viewDidLoad() // PRODUCTION FIX: Explicit [weak self] capture + explicit cancellation handle observationTask = viewModel.observeState { [weak self] state in guard let self = self else { return } self.updateUI(with: state) } } deinit { // Break subscription cleanly on Swift deallocation observationTask?.cancel() observationTask = nil } private func updateUI(with state: UserState) { // Update UI components } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Swift-ARC and Kotlin/Native GC Weak Reference Bridge Standard

KMP Swift-ARC and Kotlin/Native GC Weak Reference Bridge Standard defines an industrial-grade behavioral standard for mobile engineering. Prevents catastrophic cross-runtime retain cycles and memory leaks across the Swift ARC and Kotlin/Native tracing GC boundary. Enforces non-capturing closures, weak bridging wrappers, and deterministic lifecycle disposal for bidirectional delegates and flow subscriptions. 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: Bidirectional Strong Retain Cycles Bridging Swift ARC Object Graphs to Kotlin Native GC 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	Bidirectional Strong Retain Cycles Bridging Swift ARC Object Graphs to Kotlin Native GC	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 wrap Swift-implemented interfaces and protocols stored in Kotlin/Native via `kotlin.native.ref.WeakReference` to break cross-runtime strong retain cycles.

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.