Kotlin Multiplatform Swift-ARC Native Memory Boundary Interop Standard

--- description: Kotlin Multiplatform Swift-ARC Native Memory Boundary Interop Standard - Establishes strict thread-confinement and reference lifecycle invariants across the Kotlin Native GC and Swift ARC bridge. Prevents silent cyclic reference memory leaks and retain cycles caused by cross-runtime listener delegation and closure capturing. Mandates weak reference wrappers, explicit cancellation tokens, and structural bridge teardown routines on iOS targets. globs: iosApp/**/*.swift, shared/src/iosMain/**/*.kt, shared/src/commonMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-arc-memory-interop-guardrail" --- # Kotlin Multiplatform Swift-ARC Native Memory Boundary Interop Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Cross-Runtime Retain Cycles Between Swift ARC and Kotlin Native Tracing Collector ## System Constraints You are a Principal Mobile Architect enforcing cross-platform memory invariants between Kotlin Multiplatform and Swift ARC. Your mandate is to prevent silent bridge memory leaks, uncollected GC roots, and cross-runtime retain cycles. Every cross-language delegation must adhere to explicit thread-confinement rules, unowned/weak closure capturing, and deterministic lifecycle unwinding. ## Strict Guidelines - Engineers MUST ALWAYS wrap Swift delegate implementations passed to Kotlin Native in a weak or unowned reference adapter. - Engineers MUST NOT allow Kotlin Native objects holding Swift closures to be referenced by those same Swift closures, forming cross-runtime cycles. - Engineers MUST ALWAYS implement an explicit `close()` or `detach()` lifecycle method on Kotlin observers/presenters exposed to Objective-C/Swift. - Code MUST explicitly cancel and nullify active Kotlin `Job` or `CoroutineScope` instances when an iOS UIViewController or SwiftUI view disappears. - Engineers MUST NEVER capture strong references to Kotlin StateFlow wrappers inside long-lived Swift async tasks or Combine pipelines without `[weak self]` guards. - Bridged callbacks MUST be dispatched on the Main thread unless explicitly isolated to an off-thread Kotlin background worker using thread-safe primitives. - Engineers MUST audit Kotlin Native exported interfaces with Xcode Instruments (Leaks / Allocations) after adding persistent event subscriptions. ## Bad vs Good Implementations ### Swift Listener Subscription to Kotlin Multiplatform ViewModel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin Native holds an Objective-C strong reference to the callback closure, which captures 'self' strongly. Since 'self' (ProfileViewController) also owns 'viewModel', neither the Kotlin GC nor Swift ARC can reclaim these instances, causing a permanent memory leak. ```swift // BAD: Strong cyclic retention across Swift ARC and Kotlin Native GC class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() override func viewDidLoad() { super.viewDidLoad() // Strongly captures self into Kotlin runtime listener list // Kotlin GC holds Swift closure -> Swift closure retains self -> self retains viewModel viewModel.observeState { state in self.updateUI(state: state) } } } ``` #### Production Standard (Correct) > **Standard**: The closure captures `[weak self]` to avoid ARC retention. Storing a DisposableHandle allows the iOS lifecycle to deterministically remove the listener from the Kotlin Native root graph, severing the bridge cycle upon dismissal. ```swift // GOOD: Weak capturing with explicit lifecycle detachment via DisposableHandle class ProfileViewController: UIViewController { private let viewModel = ProfileViewModel() private var observationHandle: DisposableHandle? override func viewDidLoad() { super.viewDidLoad() observationHandle = viewModel.observeState { [weak self] state in guard let self = self else { return } self.updateUI(state: state) } } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) if isMovingFromParent || isBeingDismissed { observationHandle?.dispose() observationHandle = nil } } } ``` ### Kotlin Native Flow Adapter for Swift Observation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The launched coroutine runs as long as the ViewModelScope is alive. Since it retains the Objective-C block provided by Swift, ARC cannot free any resources captured within the block, even if the native iOS UI component is discarded. ```kotlin // BAD: Shared flow collector leaks Swift block reference indefinitely class ProfileViewModel : ViewModel() { private val _uiState = MutableStateFlow<UiState>(UiState.Initial) val uiState: StateFlow<UiState> = _uiState.asStateFlow() fun observeState(onUpdate: (UiState) -> Unit) { // Launches on ViewModelScope without returning cancellation handle // Creates an unmanaged GC root retaining the Swift-provided lambda forever viewModelScope.launch { _uiState.collect { state -> onUpdate(state) } } } } ``` #### Production Standard (Correct) > **Standard**: Returns a DisposableHandle directly to the Swift caller. This forces structured cleanup across the FFI boundary and ensures the coroutine job is cancelled, freeing the pinned Swift closure block. ```kotlin // GOOD: Returns a DisposableHandle for deterministic cross-runtime cleanup class ProfileViewModel : ViewModel() { private val _uiState = MutableStateFlow<UiState>(UiState.Initial) val uiState: StateFlow<UiState> = _uiState.asStateFlow() fun observeState(onUpdate: (UiState) -> Unit): DisposableHandle { val job = viewModelScope.launch(Dispatchers.Main.immediate) { _uiState.collect { state -> onUpdate(state) } } return DisposableHandle { job.cancel() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Swift-ARC Native Memory Boundary Interop Standard

Kotlin Multiplatform Swift-ARC Native Memory Boundary Interop Standard defines an industrial-grade behavioral standard for mobile engineering. Establishes strict thread-confinement and reference lifecycle invariants across the Kotlin Native GC and Swift ARC bridge. Prevents silent cyclic reference memory leaks and retain cycles caused by cross-runtime listener delegation and closure capturing. Mandates weak reference wrappers, explicit cancellation tokens, and structural bridge teardown routines on iOS targets. 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 Retain Cycles Between Swift ARC and Kotlin Native Tracing Collector 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 Retain Cycles Between Swift ARC and Kotlin Native Tracing Collector	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 delegate implementations passed to Kotlin Native in a weak or unowned reference adapter.

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.