Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Memory Pinning & Deallocation Standard

--- description: Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Memory Pinning & Deallocation Standard - Enforces strict lifecycle ownership, StableRef pinning invariants, and weak delegation patterns across the Kotlin/Native and Swift Automatic Reference Counting (ARC) boundary via Direct Swift Export in KMP 2.1. Eliminates silent native memory leaks caused by bidirectional strong-reference cycles between ARC-managed Swift objects and GC-managed Kotlin runtimes, and prevents unpinned raw pointer dereferencing crashes during asynchronous dispatch. globs: shared/src/iosMain/**/*.kt, shared/src/nativeMain/**/*.kt, iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-2-1-swift-export-arc-pinning-standard" --- # Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Memory Pinning & Deallocation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bidirectional Strong-Reference Cycles Across ARC and Kotlin Runtimes Causing Permanent Memory Leaks and Dangling StableRef Deference Crashes ## System Constraints You are a Principal Mobile Systems Architect enforcing the Kotlin Multiplatform 2.1 Swift-Export ARC Memory Pinning Standard. With the introduction of Direct Swift Export in KMP 2.1, bridge code no longer defaults entirely to legacy Objective-C wrapper semantics. Strong reference cycles between Swift ARC references and Kotlin/Native GC heaps can cross boundaries undetected by isolated allocators. You must mandate strict StableRef lifecycle determinism, disallow circular strong closures passed through exported Swift types, enforce explicit disposable handles for long-lived listener bindings, and mandate weak delegate structures across the cross-language FFI boundary. ## Strict Guidelines - Engineers MUST ALWAYS pair every `StableRef.create(this)` invocation with a guaranteed `dispose()` call inside a deterministic lifecycle cleanup hook (e.g., Swift `deinit` or Kotlin `Closeable.close()`). - Engineers MUST NOT capture strong Kotlin object instances inside Swift closures or escape Swift class instances into Kotlin coroutine scopes without explicit weak bridging. - Code passing Kotlin callback interfaces to Swift classes MUST expose callbacks via weak delegation protocols or explicitly invoke an unbind/dispose method to break cross-runtime cycles. - Services exposing asynchronous Kotlin `Flow` or `suspend` functions through Swift Export MUST bind collection lifecycles to an explicitly cancellable Swift Task or a `DisposableHandle` managed within the Swift caller's scope. - Components NEVER hold unmanaged `COpaquePointer` references across async task resumptions without explicit pinning via `StableRef.asCPointer()` and verified pointer validity guards. - Swift clients consuming Swift-Exported Kotlin classes MUST declare listener and delegate properties as `weak` or assign them using unowned capture lists in Swift closures. ## Bad vs Good Implementations ### Cross-Boundary Delegate Listener Registration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kotlin holds a strong reference to SessionListener. If a Swift class holds a strong reference to SessionEngine and assigns itself as listener, ARC and Kotlin GC cannot traverse each other's retain graphs to detect the cycle, causing a permanent leak of both objects. ```kotlin // shared/src/iosMain/kotlin/com/example/engine/SessionEngine.kt package com.example.engine interface SessionListener { fun onStateChanged(state: String) } class SessionEngine { // ANTI-PATTERN: Strong reference to an exported Swift-implemented interface. // When Swift holds SessionEngine strongly and assigns self as listener, // an invisible cross-runtime cycle (Swift ARC -> Kotlin Heap -> Swift ARC) is formed. var listener: SessionListener? = null fun notify(state: String) { listener?.onStateChanged(state) } } ``` #### Production Standard (Correct) > **Standard**: Encapsulating the cross-boundary listener in a `kotlin.native.ref.WeakReference` prevents the Kotlin runtime from retaining the Swift instance, breaking the cross-heap circular reference and allowing Swift ARC to deallocate cleanly. ```kotlin // shared/src/iosMain/kotlin/com/example/engine/SessionEngine.kt package com.example.engine import kotlin.native.ref.WeakReference import kotlinx.cinterop.InternalForKotlinNative interface SessionListener : Any { fun onStateChanged(state: String) } class SessionEngine { private var weakListener: WeakReference<SessionListener>? = null var listener: SessionListener? get() = weakListener?.get() set(value) { weakListener = value?.let { WeakReference(it) } } fun clearListener() { weakListener = null } fun notify(state: String) { listener?.onStateChanged(state) } } ``` ### Direct Memory Pinning for Cross-FFI Asynchronous Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: MemScope() is transient and deallocates immediately, leaving rawPtr as a dangling reference. Furthermore, ByteArray memory is not pinned, exposing the native execution to memory corruption if relocated or reclaimed by GC. ```kotlin // shared/src/iosMain/kotlin/com/example/bridge/NativeBufferBridge.kt package com.example.bridge import kotlinx.cinterop.* class NativeBufferBridge(val payload: ByteArray) { fun processAsync(callback: (Int) -> Unit) { // ANTI-PATTERN: Passing raw pointer without pinning payload lifecycle. // Kotlin's GC can collect or relocate payload while the asynchronous work executes. val rawPtr = payload.refTo(0).getPointer(MemScope()) dispatchNativeWork(rawPtr) { result -> callback(result) } } private external fun dispatchNativeWork(ptr: CPointer<ByteVar>, onComplete: (Int) -> Unit) } ``` #### Production Standard (Correct) > **Standard**: The byte array is explicitly pinned via `pin()` and the bridge context is secured using `StableRef.create(this)`. Both pins are guaranteed to be released in the `finally` block upon native completion, preventing dangling pointer dereferences and memory leaks. ```kotlin // shared/src/iosMain/kotlin/com/example/bridge/NativeBufferBridge.kt package com.example.bridge import kotlinx.cinterop.* class NativeBufferBridge(val payload: ByteArray) { fun processAsync(callback: (Int) -> Unit) { // SAFE: Pin the memory across the boundary using StableRef val stableRef = StableRef.create(this) val rawPayload = payload.pin() dispatchNativeWork(rawPayload.addressOf(0)) { result -> try { callback(result) } finally { rawPayload.unpin() stableRef.dispose() } } } private external fun dispatchNativeWork(ptr: CPointer<ByteVar>, onComplete: (Int) -> Unit) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Memory Pinning & Deallocation Standard

Kotlin Multiplatform 2.1 Swift-Export ARC Boundary Memory Pinning & Deallocation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict lifecycle ownership, StableRef pinning invariants, and weak delegation patterns across the Kotlin/Native and Swift Automatic Reference Counting (ARC) boundary via Direct Swift Export in KMP 2.1. Eliminates silent native memory leaks caused by bidirectional strong-reference cycles between ARC-managed Swift objects and GC-managed Kotlin runtimes, and prevents unpinned raw pointer dereferencing crashes during asynchronous dispatch. 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: Bidirectional Strong-Reference Cycles Across ARC and Kotlin Runtimes Causing Permanent Memory Leaks and Dangling StableRef Deference Crashes 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	Bidirectional Strong-Reference Cycles Across ARC and Kotlin Runtimes Causing Permanent Memory Leaks and Dangling StableRef Deference Crashes	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 pair every `StableRef.create(this)` invocation with a guaranteed `dispose()` call inside a deterministic lifecycle cleanup hook (e.g., Swift `deinit` or Kotlin `Closeable.close()`).

Engineers MUST ALWAYS pair every `StableRef.create(this)` invocation with a guaranteed `dispose()` call inside a deterministic lifecycle cleanup hook (e.g., Swift `deinit` or Kotlin `Closeable.close()`).

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.