KMP K2 Native ARC Reference Cycle & Deterministic Unbinding Invariant

--- description: KMP K2 Native ARC Reference Cycle & Deterministic Unbinding Invariant - Establishes deterministic lifecycle unbinding and weak boundary mediation between Kotlin 2.1 Native runtimes and Apple Automatic Reference Counting (ARC). Under Kotlin Native's tracing garbage collector, retaining strong Swift/Obj-C closures that capture KMP state graphs spanning native threads creates disjoint island cycles that neither ARC nor the Kotlin GC can reclaim. This standard mandates explicit detachment contracts and WeakReference wrapping across the foreign function boundary. globs: **/*.ios.kt, **/*.apple.kt, iosApp/**/*.swift, iosApp/**/*.m alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-k2-native-arc-reference-cycle-invariant" --- # KMP K2 Native ARC Reference Cycle & Deterministic Unbinding Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining Strong Kotlin Coroutine Scope or SharedFlow Listeners inside Swift ARC ViewModels without Explicit Lifecycle Teardown ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform (K2) and Darwin runtime interop. Your mandate is to enforce strict memory lifecycle safety and zero-leak boundaries between Kotlin Native's Garbage Collector and Apple's ARC. Enforce explicit unbinding contracts, prevent closure-based circular root references, and guarantee that background coroutines and shared state adapters are deterministically released upon UI view disappearance. ## Strict Guidelines - Engineers MUST ALWAYS implement an explicit `close()` or `detach()` lifecycle protocol on Kotlin Multiplatform state holders consumed by Swift/Objective-C. - Engineers MUST NOT bridge Kotlin `StateFlow` or `SharedFlow` directly into Swift escaping closures without holding weak references to the enclosing Swift receiver. - Swift bridging adapters MUST cancel and de-reference active Kotlin coroutine `Job` instances inside `deinit` or during SwiftUI `onDisappear` / UIViewController `viewDidDisappear` phases. - Engineers MUST wrap cross-boundary delegate callbacks in Kotlin `kotlin.native.ref.WeakReference` whenever a Swift observer registers itself as a listener on a long-lived KMP singleton or repository. - Components NEVER rely on Kotlin Native GC root-tracing to sweep references retained by the Darwin ARC heap, as ARC requires reference count zero to trigger deallocation. ## Bad vs Good Implementations ### Deterministic Flow Collector Bridging Swift ARC and Kotlin Native Runtime #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin Native's runtime creates an interop root for the Swift escaping closure. Because 'self' is strongly captured inside the closure and the Kotlin repository maintains the active Job, an inter-runtime retain cycle is established. When the view dismisses, neither Swift ARC nor Kotlin GC can deallocate the objects, causing an unbounded background memory leak. ```swift // Anti-pattern: Strong closure capture of 'self' bridging to Kotlin Flow import SharedKit import SwiftUI @MainActor final class UserProfileViewModel: ObservableObject { @Published var state: ProfileState = .initial private let repository = ProfileRepository() func startObserving() { // BUG: repository holds the collector, collector holds 'self' strongly. // If SwiftUI drops UserProfileViewModel, ARC cannot collect 'self' because // Kotlin's ProfileRepository holds an active bridge job retaining the closure. repository.profileState.collect { newState in self.state = newState } } } ``` #### Production Standard (Correct) > **Standard**: The good implementation breaks the ARC cycle via `[weak self]` in the interop closure and captures the bridging handle (`FlowTask`). Upon deinitialization or explicit view teardown, the subscription is cancelled, clearing the Kotlin interop GC root. ```swift // Production Fix: Deterministic Job cancellation and Weak Capture Bridge import SharedKit import SwiftUI @MainActor final class UserProfileViewModel: ObservableObject { @Published var state: ProfileState = .initial private let repository: ProfileRepository private var observationTask: FlowTask? = nil init(repository: ProfileRepository = ProfileRepository()) { self.repository = repository } func startObserving() { observationTask?.cancel() // FIX: Weak self capture breaks ARC cycle; Kotlin FlowTask explicitly retained and cancelled observationTask = repository.profileState.collectWatch( onEach: { [weak self] newState in guard let self = self else { return } self.state = newState } ) } func stopObserving() { observationTask?.cancel() observationTask = nil } deinit { observationTask?.cancel() } } ``` ### Kotlin Native Weak Observer Registration Protocol #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing strong references to Objective-C/Swift protocol instances inside a Kotlin Native collection prevents Darwin ARC from dropping their reference count to zero. If the Swift object also references the SessionManager or its dependencies, a multi-runtime deadlock or permanent leak occurs. ```kotlin // Anti-pattern: Retaining raw Swift interface implementations across threads package com.example.shared interface SessionObserver { fun onSessionExpired() } class SessionManager { // BUG: Strong reference to an Apple ARC-managed interface implementation. // Prevents Swift objects passed to addObserver from ever reaching zero retain count. private val observers = mutableListOf<SessionObserver>() fun addObserver(observer: SessionObserver) { observers.add(observer) } fun notifyExpired() { observers.forEach { it.onSessionExpired() } } } ``` #### Production Standard (Correct) > **Standard**: By utilizing `kotlin.native.ref.WeakReference`, the Kotlin collection does not artificially increment the Objective-C/Swift ARC retain count. The Swift instance can be reclaimed normally when dismissed from the view hierarchy, and dead references are purged during notification sweeps. ```kotlin // Production Fix: Explicit WeakReference wrapping with dead-ref eviction package com.example.shared import kotlin.native.ref.WeakReference interface SessionObserver : Any class SessionManager { // FIX: Store Kotlin Native WeakReferences to prevent ARC pinning private val observers = mutableListOf<WeakReference<SessionObserver>>() fun addObserver(observer: SessionObserver) { observers.removeAll { it.get() == null } observers.add(WeakReference(observer)) } fun removeObserver(observer: SessionObserver) { observers.removeAll { it.get() == null || it.get() === observer } } fun notifyExpired() { observers.removeAll { it.get() == null } observers.mapNotNull { it.get() }.forEach { // Safe invocation on weakly held listener (it as? SessionObserverLifecycle)?.onSessionExpired() } } } interface SessionObserverLifecycle { fun onSessionExpired() } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP K2 Native ARC Reference Cycle & Deterministic Unbinding Invariant

KMP K2 Native ARC Reference Cycle & Deterministic Unbinding Invariant defines an industrial-grade behavioral standard for mobile engineering. Establishes deterministic lifecycle unbinding and weak boundary mediation between Kotlin 2.1 Native runtimes and Apple Automatic Reference Counting (ARC). Under Kotlin Native's tracing garbage collector, retaining strong Swift/Obj-C closures that capture KMP state graphs spanning native threads creates disjoint island cycles that neither ARC nor the Kotlin GC can reclaim. This standard mandates explicit detachment contracts and WeakReference wrapping across the foreign function boundary. 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 Strong Kotlin Coroutine Scope or SharedFlow Listeners inside Swift ARC ViewModels without Explicit Lifecycle Teardown 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 Strong Kotlin Coroutine Scope or SharedFlow Listeners inside Swift ARC ViewModels without Explicit Lifecycle Teardown	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 implement an explicit `close()` or `detach()` lifecycle protocol on Kotlin Multiplatform state holders consumed by Swift/Objective-C.

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.