Kotlin Multiplatform Native StableRef and ARC Deterministic Reclamation Guardrail

--- description: Kotlin Multiplatform Native StableRef and ARC Deterministic Reclamation Guardrail - Enforces bidirectional lifecycle deterministic disposal for Kotlin/Native StableRef handles exported to Apple Swift ARC runtimes. Prevents uncollected zombie references and heap memory leaks caused by pinned GC roots escaping Objective-C/Swift ARC deallocation lifecycles. globs: **/*.native.kt, **/*.ios.kt, iosApp/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-stableref-arc-reclamation-guardrail" --- # Kotlin Multiplatform Native StableRef and ARC Deterministic Reclamation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dangling StableRef Handles Passed as Raw Unmanaged Pointers Without Swift ARC deinit Binding ## System Constraints You are a Principal Software Architect enforcing rigorous memory management standards across Kotlin Multiplatform and Apple Darwin boundaries. You MUST prohibit the untracked instantiation of `StableRef.create()` without corresponding lifecycle wrappers. Every exposed `COpaquePointer` or `StableRef` crossing the Kotlin/Native and Swift boundary must be bound deterministically to a reference-counted container or an explicit Disposable contract. You must flag any Swift bridge code that fails to call `dispose()` in `deinit`. ## Strict Guidelines - Engineers MUST ALWAYS bind every `StableRef.create()` handle to a corresponding `dispose()` call inside an explicit Swift ARC wrapper's `deinit` method. - Engineers MUST NOT leak raw `COpaquePointer` types into Swift business logic without an enclosing ARC-managed lifecycle boundary class. - Code SHOULD verify that Kotlin objects referenced by `StableRef` do not hold circular references back to the wrapping native Apple objects unless marked weak. - Services MUST provide deterministic cleanup routines (e.g., `close()`, `dispose()`) rather than relying entirely on Kotlin GC finalizers across native platform bridges. - Components NEVER store long-lived `StableRef` instances in global state or static dictionaries without explicit atomic unregister mechanics. ## Bad vs Good Implementations ### Kotlin/Native StableRef Bridge with Swift ARC Lifecycle Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a StableRef pins the Kotlin object in the GC heap. Returning a raw COpaquePointer to Apple platforms without enforcing that Swift ARC calls dispose() causes indefinite memory retention (zombie handles) even when Swift releases its references. ```kotlin // BAD: StableRef created and passed to native consumer without ownership enforcement // Kotlin Side @OptIn(kotlinx.cinterop.ExperimentalForeignApi::class) fun createSessionHandle(session: NativeSession): kotlinx.cinterop.COpaquePointer { val ref = kotlinx.cinterop.StableRef.create(session) return ref.asCPointer() // Pinned as a GC root forever if Swift forgets to call free } @OptIn(kotlinx.cinterop.ExperimentalForeignApi::class) fun executeSession(ptr: kotlinx.cinterop.COpaquePointer) { val session = ptr.asStableRef<NativeSession>().get() session.execute() // dispose() is omitted, leaking the Kotlin GC root } ``` #### Production Standard (Correct) > **Standard**: Encapsulating the StableRef inside a managed NativeSessionHandle class ensures that the native object lifecycle is tied directly to the Swift wrapper's deinit callback, deterministically disposing the StableRef root when ARC decrements the reference count to zero. ```kotlin // GOOD: Enforce managed lifecycle with an explicit Kotlin Disposable and Swift ARC wrapper // Kotlin Side @OptIn(kotlinx.cinterop.ExperimentalForeignApi::class) class NativeSessionHandle private constructor(private val ref: kotlinx.cinterop.StableRef<NativeSession>) { val session: NativeSession get() = ref.get() fun dispose() { ref.dispose() } companion object { fun allocate(session: NativeSession): NativeSessionHandle { return NativeSessionHandle(kotlinx.cinterop.StableRef.create(session)) } } } // Swift ARC Bridge Consumer: // final class SessionLifecycleOwner { // private let handle: NativeSessionHandle // init(session: NativeSession) { // self.handle = NativeSessionHandle.Companion.shared.allocate(session: session) // } // deinit { // handle.dispose() // Deterministically unpins the Kotlin GC root // } // } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Native StableRef and ARC Deterministic Reclamation Guardrail

Kotlin Multiplatform Native StableRef and ARC Deterministic Reclamation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces bidirectional lifecycle deterministic disposal for Kotlin/Native StableRef handles exported to Apple Swift ARC runtimes. Prevents uncollected zombie references and heap memory leaks caused by pinned GC roots escaping Objective-C/Swift ARC deallocation lifecycles. 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: Dangling StableRef Handles Passed as Raw Unmanaged Pointers Without Swift ARC deinit Binding 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	Dangling StableRef Handles Passed as Raw Unmanaged Pointers Without Swift ARC deinit Binding	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 bind every `StableRef.create()` handle to a corresponding `dispose()` call inside an explicit Swift ARC wrapper's `deinit` method.

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.