KMP 2.1 Swift Export Cross-Runtime ARC/GC Lifetime Synchronization

--- description: KMP 2.1 Swift Export Cross-Runtime ARC/GC Lifetime Synchronization - Enforces strict memory boundary management between Kotlin/Native's modern concurrent GC and Swift ARC when using KMP 2.1 Swift Export. Prohibits cross-runtime strong reference cycles caused by bidirectional delegation, long-lived observer callbacks, and unbounded native view bindings. Mandates explicit teardown protocols, unowned/weak Swift proxies, and CoroutineScope lifecycle anchoring to prevent cross-language heap leaks. globs: **/iosApp/**/*.swift, **/shared/src/iosMain/**/*.kt, **/shared/src/commonMain/**/*ViewModel.kt, **/shared/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-arc-lifetime-synchronization" --- # KMP 2.1 Swift Export Cross-Runtime ARC/GC Lifetime Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Language Retain Cycles via Strong Delegation and Unbounded Coroutine Bridge Observers ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform 2.1 Swift Export ARC Lifetime Synchronization. The target platform couples Swift's Automatic Reference Counting with Kotlin/Native's mark-and-sweep GC. Because cross-runtime reference loops cannot be collected automatically by either garbage collector alone, you must enforce explicit weak/unowned references on the Swift interface boundary, cancellation of CoroutineScopes tied to UI lifecycles, and deterministic disposable observer patterns. Reject any Swift Export interface that passes non-weak Swift closures or stateful retainers directly into long-lived Kotlin singletons or ViewModels. ## Strict Guidelines - Engineers MUST ALWAYS declare Swift callback listeners passed into Kotlin components as weak or wrap them in an intermediate WeakBox/delegate to prevent pinning Kotlin GC nodes to Swift ARC allocations. - Engineers MUST NOT capture strong instances of UIViewController, SwiftUI View state holders, or Swift reference classes inside long-lived Kotlin Coroutine flows or Job listeners. - Code SHOULD enforce deterministic lifecycle termination by requiring Swift view boundaries to call a dedicated `detach()` or `dispose()` method in `viewDidDisappear` / `onDisappear`. - Services MUST scope CoroutineScope instances to platform lifecycle boundaries (e.g., matching iOS screen presence) rather than static global singletons when interacting with Swift Export types. - Components NEVER store direct strong bi-directional links (Swift View -> Kotlin Presenter -> Swift View) without making the Kotlin-to-Swift reverse reference weakly typed or wrapped in a WeakReference abstraction. ## Bad vs Good Implementations ### Prevent Cross-Language Retain Cycle in Swift Export ViewModel Observation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin's ProfileViewModel stores the closure in its CoroutineScope or callback list. The Swift closure strongly captures ProfileViewController, while ProfileViewController strongly owns ProfileViewModel. Neither Kotlin GC nor Swift ARC can resolve this cross-runtime cycle, leaking the entire ViewController and its hierarchy. ```swift import SwiftUI import SharedKit // ANTI-PATTERN: Direct bidirectional strong reference between Swift UI and KMP ViewModel. // Kotlin hold strong reference to Swift closure; Swift view retains Kotlin ViewModel. final class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() override func viewDidLoad() { super.viewDidLoad() viewModel.observeState { [self] state in // Captures 'self' strongly across the KMP boundary self.render(state: state) } } private func render(state: ProfileState) { // UI updates } } ``` #### Production Standard (Correct) > **Standard**: The Swift observer references `self` weakly via Swift Concurrency AsyncSequence/Task. Furthermore, deterministic teardown is invoked during view dismissal (`viewModel.clear()`), cancelling ongoing Kotlin coroutines and severing any residual GC-ARC bridges. ```swift import SwiftUI import SharedKit // PRODUCTION INVARIANT: Weak capture in Swift observer, explicit lifecycle teardown final class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() private var observationTask: Task<Void, Never>? override func viewDidLoad() { super.viewDidLoad() // Bridge using explicit weak reference to prevent ARC pinning observationTask = Task { [weak self] in for await state in self?.viewModel.stateFlow ?? [] { guard let self = self else { return } self.render(state: state) } } } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) if isMovingFromParent || isBeingDismissed { observationTask?.cancel() viewModel.clear() } } private func render(state: ProfileState) { // UI updates } } ``` ### Kotlin/Native Swift Export Delegate Interface with Weak Protocol Reference #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When Swift Export projects `NavigationDelegate` into Swift, an ARC wrapper object is generated. The Kotlin property `delegate` maintains a strong GC handle to this Swift bridge instance, preventing its deallocation even if the Swift owner drops it. ```kotlin // ANTI-PATTERN: Kotlin interface retaining strong Swift implementation reference package com.example.shared interface NavigationDelegate { fun onNavigateBack() } class FlowCoordinator { // Strong reference to Swift delegate will prevent Swift ARC deallocation var delegate: NavigationDelegate? = null fun completeFlow() { delegate?.onNavigateBack() } } ``` #### Production Standard (Correct) > **Standard**: By using Kotlin/Native's `kotlin.native.ref.WeakReference`, the Kotlin object does not increase the ARC retain count on the Swift implementation wrapper. When Swift releases the conforming class, both ARC and GC cleanly release their resources without pinning. ```kotlin // PRODUCTION INVARIANT: Weak reference holder for cross-runtime Swift delegate interfaces package com.example.shared import kotlin.experimental.ExperimentalNativeApi import kotlin.native.ref.WeakReference interface NavigationDelegate : Any class FlowCoordinator { private var delegateRef: WeakReference<NavigationDelegate>? = null var delegate: NavigationDelegate? get() = delegateRef?.get() set(value) { delegateRef = value?.let { WeakReference(it) } } fun completeFlow() { delegate?.let { (it as? NavigationDelegateActions)?.onNavigateBack() } } fun clear() { delegateRef = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP 2.1 Swift Export Cross-Runtime ARC/GC Lifetime Synchronization

KMP 2.1 Swift Export Cross-Runtime ARC/GC Lifetime Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces strict memory boundary management between Kotlin/Native's modern concurrent GC and Swift ARC when using KMP 2.1 Swift Export. Prohibits cross-runtime strong reference cycles caused by bidirectional delegation, long-lived observer callbacks, and unbounded native view bindings. Mandates explicit teardown protocols, unowned/weak Swift proxies, and CoroutineScope lifecycle anchoring to prevent cross-language heap leaks. 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: Cross-Language Retain Cycles via Strong Delegation and Unbounded Coroutine Bridge Observers 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	Cross-Language Retain Cycles via Strong Delegation and Unbounded Coroutine Bridge Observers	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 declare Swift callback listeners passed into Kotlin components as weak or wrap them in an intermediate WeakBox/delegate to prevent pinning Kotlin GC nodes to Swift ARC allocations.

Engineers MUST ALWAYS declare Swift callback listeners passed into Kotlin components as weak or wrap them in an intermediate WeakBox/delegate to prevent pinning Kotlin GC nodes to Swift ARC allocations.

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.