Kotlin Multiplatform 2.1 Native ARC Deterministic Memory Retention Bound

--- description: Kotlin Multiplatform 2.1 Native ARC Deterministic Memory Retention Bound - Enforces deterministic bidirectional lifecycle boundaries between Kotlin Native garbage collection and Apple ARC. Eliminates uncollectible cross-runtime cyclic references when bridging Swift closures and Kotlin Native listeners by mandating explicit unbinding and weak-capture semantics across Objective-C interop barriers. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt, **/*Bridge*.swift, **/*ViewModel*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-arc-memory-retention-bound" --- # Kotlin Multiplatform 2.1 Native ARC Deterministic Memory Retention Bound > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Runtime Zombie Objects Caused by Strong Bidirectional Closure Capture Between Swift ARC and Kotlin Native GC ## System Constraints You are a Principal Software Architect specializing in Kotlin Multiplatform and iOS low-level memory runtimes. Your task is to enforce strict memory retention boundaries between Apple ARC and Kotlin 2.1 Native GC. You must prohibit direct strong Swift closure passing into persistent Kotlin Native object properties, mandate explicit unbinding protocols (Disposable/Closeable handles), and ensure Swift consumers always employ weak capture lists alongside proactive lifecycle-based deregistration. ## Strict Guidelines - Engineers MUST ALWAYS capture `[weak self]` when passing Swift closures to exported Kotlin classes or callbacks that outlive the current call stack. - Engineers MUST NOT store raw Swift closures directly into long-lived Kotlin/Native object fields without an explicit detachment mechanism or cancellation token. - Kotlin-exported interfaces MUST provide an explicit `close()`, `cancel()`, or `detach()` method implementing `AutoCloseable` or returning a `Disposable` handle to clear callback references deterministically on the Swift caller's `deinit` or `viewDidDisappear`. - Swift wrappers MUST invoke the Kotlin unbind/cancel method inside `deinit` to force severance of the Obj-C runtime reference table before native ARC deallocation completes. - Components NEVER rely on Kotlin/Native GC sweep cycles to reclaim objects retained by Swift ARC strong references, as cycles crossing runtime barriers remain uncollectible by both ARC and Kotlin GC. ## Bad vs Good Implementations ### Bidirectional Listener Lifecycle Management in Swift Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin/Native tracing GC cannot see ARC references held by Swift closures captured inside Kotlin fields, and Swift ARC cannot collect ProfileViewController because Kotlin's root set retains the callback object. This results in permanent memory leakage for the entire view hierarchy. ```swift import Shared final class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() override func viewDidLoad() { super.viewDidLoad() // CRITICAL BUG: Strong reference cycle across runtimes. // Swift holds viewModel (ARC). Kotlin viewModel holds closure. // Closure strongly captures self. Neither ARC nor KMP GC can collect. viewModel.observeState { self.updateUI() } } private func updateUI() { // View update logic } } ``` #### Production Standard (Correct) > **Standard**: Using `[weak self]` breaks the strong ARC closure hold, and tracking a `CloseableTask` ensures that upon Swift object deallocation, the closure reference stored in Kotlin Native heap is nullified immediately without waiting for a GC sweep. ```swift import Shared final class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() private var stateObservationTask: CloseableTask? override func viewDidLoad() { super.viewDidLoad() // Enforces [weak self] and captures a deterministic unbind token stateObservationTask = viewModel.observeState { [weak self] state in guard let self = self else { return } self.updateUI(state: state) } } private func updateUI(state: ProfileState) { // View update logic } deinit { // Deterministically severs the Kotlin-to-Swift cross-boundary reference stateObservationTask?.close() stateObservationTask = nil } } ``` ### Kotlin/Native Safe Callback Dispatcher Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Kotlin class stores a native Objective-C block reference without offering a disposal contract. Swift clients have no mechanism to clear this reference, inducing permanent cross-runtime cycle retention. ```kotlin package com.example.shared class ProfileViewModel { // Anti-Pattern: Strong callback stored indefinitely without cleanup API private var callback: ((ProfileState) -> Unit)? = null fun observeState(onUpdate: (ProfileState) -> Unit) { this.callback = onUpdate } } ``` #### Production Standard (Correct) > **Standard**: The ViewModel returns a `CloseableTask` handle. When invoked by the Swift client's `deinit`, it sets the closure reference to null, immediately severing the cross-language reference. ```kotlin package com.example.shared interface CloseableTask { fun close() } class ProfileViewModel { private var callback: ((ProfileState) -> Unit)? = null fun observeState(onUpdate: (ProfileState) -> Unit): CloseableTask { this.callback = onUpdate return object : CloseableTask { override fun close() { callback = null } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 Native ARC Deterministic Memory Retention Bound

Kotlin Multiplatform 2.1 Native ARC Deterministic Memory Retention Bound defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic bidirectional lifecycle boundaries between Kotlin Native garbage collection and Apple ARC. Eliminates uncollectible cross-runtime cyclic references when bridging Swift closures and Kotlin Native listeners by mandating explicit unbinding and weak-capture semantics across Objective-C interop barriers. 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-Runtime Zombie Objects Caused by Strong Bidirectional Closure Capture Between Swift ARC and 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	Cross-Runtime Zombie Objects Caused by Strong Bidirectional Closure Capture Between Swift ARC and 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 capture `[weak self]` when passing Swift closures to exported Kotlin classes or callbacks that outlive the current call stack.

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.