Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Pinning

--- description: Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Pinning - Enforces strict lifecycle management, explicit object pinning, and cycle decoupling across the Kotlin/Native and Apple Swift-Export ARC boundary in KMP 2.1+. Prevents catastrophic native heap corruption and undetectable retain cycles caused by bridge-crossing closures, strong delegate references, and implicit Kotlin StableRef handling under Swift Automatic Reference Counting. globs: shared/**/commonMain/**/*.kt, shared/**/iosMain/**/*.kt, iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-swift-export-arc-boundary-pinning" --- # Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Pinning > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Implicit Bidirectional Retain Cycles and Premature Object Deallocation across Swift-Export Boundaries ## System Constraints You are a Principal Mobile Architect enforcing absolute memory safety and deterministic lifecycle constraints on Kotlin Multiplatform 2.1+ projects utilizing Swift-Export. You must eliminate all direct bidirectional retain cycles between Swift ARC and Kotlin/Native runtime tracking. Enforce weak listener patterns, explicit unpinning protocols, and safe boundary bridging to prevent both silent memory leaks and use-after-free native segmentation faults. ## Strict Guidelines - Engineers MUST ALWAYS implement an explicit lifecycle disposal contract (e.g., `Disposable`, `Closeable`) on any Kotlin class exported to Swift that registers long-lived native callbacks or listeners. - Engineers MUST NOT capture strong Kotlin object references inside escaping Swift closures or delegate properties directly exposed through Swift-Export. - Swift code MUST ALWAYS mark delegate references to Kotlin-exported interfaces or bridging protocol conformances with `weak` or wrap them in an explicit `WeakRef` container. - Engineers MUST NEVER use raw `StableRef` pointers across public Swift-Export interfaces without wrapping them in managed RAII lifecycle constructs that guarantee single-ownership balance. - Shared Kotlin Coroutine scopes crossing the boundary via Swift-Export MUST be cancelled deterministically inside Swift view deinitializers (`deinit`) or UIViewController lifecycle dismissals to break implicit scope retaining trees. ## Bad vs Good Implementations ### Decoupling Swift ARC Observer from Kotlin Coroutine-Backed Store #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin holds a strong reference to the Swift listener implementation, while the Swift consumer holds a strong ARC reference to AppStateStore. This cross-boundary circular reference cannot be resolved by ARC (which sees only an opaque Kotlin object handle) or by Kotlin's GC (which sees an active root via the bridge), causing permanent memory leaks. ```kotlin // shared/src/iosMain/kotlin/com/platform/AppStateStore.kt package com.platform interface StateListener { fun onStateChange(state: String) } class AppStateStore { // ANTI-PATTERN: Strong reference to Swift listener retained in Kotlin heap. // When Swift observer holds strong reference to AppStateStore, // a cross-runtime cycle forms that neither ARC nor Kotlin GC can collect. private var listener: StateListener? = null fun setListener(listener: StateListener) { this.listener = listener } fun emit(state: String) { listener?.onStateChange(state) } } ``` #### Production Standard (Correct) > **Standard**: The Kotlin side preserves a `WeakReference` to the listener and returns a deterministic `Cancellable` token. The Swift consumer manages its own ARC lifecycle without being rooted by the Kotlin engine, breaking the cross-runtime circular dependency. ```kotlin // shared/src/iosMain/kotlin/com/platform/AppStateStore.kt package com.platform import kotlin.native.ref.WeakReference interface StateListener : Any interface Cancellable { fun cancel() } class AppStateStore { private var weakListener: WeakReference<StateListener>? = null fun setListener(listener: StateListener): Cancellable { this.weakListener = WeakReference(listener) return object : Cancellable { override fun cancel() { weakListener = null } } } fun emit(state: String) { // Boundary-safe resolution: Kotlin Native weak reference dereferencing val activeListener = weakListener?.get() if (activeListener is StateListenerCallback) { activeListener.onStateChange(state) } else if (weakListener?.get() == null) { weakListener = null } } } interface StateListenerCallback { fun onStateChange(state: String) } ``` ### Swift-Export Callback Handling with Explicit ARC Weak Capture #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Registering `self` directly to an exported Kotlin store without lifetime bounding pins the Swift object across the ARC boundary. If `AppStateStore` outlives the SwiftUI view hierarchy, the entire view model remains allocated in the heap. ```swift // iosApp/iOSApp/ViewModelWrapper.swift import SwiftUI import SharedExportedCore class UserProfileViewModel: ObservableObject { private let coreStore: AppStateStore init(coreStore: AppStateStore) { self.coreStore = coreStore // ANTI-PATTERN: Escaping closure strongly captures `self` across the bridge. // Swift-Export retains this closure in Kotlin memory, pinning `self` permanently. coreStore.setListener(listener: self) } } extension UserProfileViewModel: StateListenerCallback { func onStateChange(state: String) { print("Received: \(state)") } } ``` #### Production Standard (Correct) > **Standard**: Uses an intermediate `StateTrampoline` with a `weak` ARC reference back to the view model combined with deterministic `cancel()` invocation in `deinit`. This guarantees that Swift ARC retains ownership of its view model while preventing Kotlin from pinning Swift native memory. ```swift // iosApp/iOSApp/ViewModelWrapper.swift import SwiftUI import SharedExportedCore final class UserProfileViewModel: ObservableObject { private let coreStore: AppStateStore private var subscriptionToken: Cancellable? init(coreStore: AppStateStore) { self.coreStore = coreStore bind() } private func bind() { // Invariant: Trampoline wrapper or weak bridging prevents ARC pinning let trampoline = StateTrampoline(target: self) self.subscriptionToken = coreStore.setListener(listener: trampoline) } deinit { // Explicit unpinning boundary: Deterministic cleanup breaks cross-runtime pins subscriptionToken?.cancel() } } private final class StateTrampoline: StateListenerCallback { private weak var target: UserProfileViewModel? init(target: UserProfileViewModel) { self.target = target } func onStateChange(state: String) { target?.handleStateChange(state) } } extension UserProfileViewModel { fileprivate func handleStateChange(_ state: String) { // Handle state safely within ARC lifecycle } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Pinning

Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Pinning defines an industrial-grade behavioral standard for mobile engineering. Enforces strict lifecycle management, explicit object pinning, and cycle decoupling across the Kotlin/Native and Apple Swift-Export ARC boundary in KMP 2.1+. Prevents catastrophic native heap corruption and undetectable retain cycles caused by bridge-crossing closures, strong delegate references, and implicit Kotlin StableRef handling under Swift Automatic Reference Counting. 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: Implicit Bidirectional Retain Cycles and Premature Object Deallocation across Swift-Export Boundaries 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	Implicit Bidirectional Retain Cycles and Premature Object Deallocation across Swift-Export Boundaries	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 lifecycle disposal contract (e.g., `Disposable`, `Closeable`) on any Kotlin class exported to Swift that registers long-lived native callbacks or listeners.

Engineers MUST ALWAYS implement an explicit lifecycle disposal contract (e.g., `Disposable`, `Closeable`) on any Kotlin class exported to Swift that registers long-lived native callbacks or listeners.

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.