KMP Native Memory Cinterop Arena Scoping and Finalizer Guardrail

--- description: KMP Native Memory Cinterop Arena Scoping and Finalizer Guardrail - Enforces strict native memory management invariants when bridging C/Objective-C pointers into Kotlin Multiplatform code via kotlinx.cinterop. Mandates explicit Arena/AutofreeScope lifetimes, forbids unmanaged native allocations escaping into common code, and requires atomic cleaner/finalizer disposal mechanisms to avoid use-after-free or native memory leaks. globs: **/*Native*.kt, **/*Interop*.kt, **/cinterop/**/*.kt, **/nativeMain/**/*.kt, **/iosMain/**/*.kt, **/macosMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-memory-arena-scoping-guardrail" --- # KMP Native Memory Cinterop Arena Scoping and Finalizer Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Escaping Raw C Pointers and Unscoped Native Allocations Across Common Code Boundaries ## System Constraints You are a Principal Mobile Systems Architect enforcing deterministic memory management across Kotlin Native C-interop boundaries. Prevent use-after-free, double-free, and native heap leaks by strictly scoping native allocations, preventing raw pointers (CPointer/CPointed) from escaping into common platform-agnostic models, and enforcing Kotlin Cleaner (kotlin.native.internal.createCleaner or kotlin.native.ref.Cleaner) or AutoCloseable wrappers for long-lived native handles. ## Strict Guidelines - Engineers MUST ALWAYS scope short-lived native C allocations within memScoped { ... } blocks and extract raw primitive or heap-managed Kotlin types before the scope exits. - Engineers MUST NOT allow raw CPointer<T> or NativePointed instances to escape memScoped blocks or leak into commonMain sourceSets. - Engineers MUST bind long-lived native allocations (e.g., arena.alloc<T>(), nativeHeap.alloc<T>()) to an AutoCloseable, Closeable, or Cleaner-backed lifecycle wrapper to ensure deterministic deallocation via nativeHeap.free() or arena.clear(). - Services MUST NEVER invoke .pointed or dereference a native pointer without prior non-null validation or when the underlying Arena may have already been invalidated. - Components NEVER store direct CPointer references across thread boundaries without pinned stable refs (StableRef.create) and explicit paired deallocations (StableRef.dispose). ## Bad vs Good Implementations ### Scoping Transient C Structure Extraction vs Escaped CPointer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Returning a CPointer allocated within memScoped results in undefined behavior (dangling pointer) as soon as the block terminates and the scope's arena is destroyed. ```kotlin @OptIn(ExperimentalForeignApi::class) fun parseNativeBufferBad(data: ByteArray): CPointer<ByteVar> { memScoped { val nativeBuffer = allocArray<ByteVar>(data.size) data.forEachIndexed { index, byte -> nativeBuffer[index] = byte } // FATAL: Pointer escapes memScoped allocation frame; use-after-free on dereference return nativeBuffer.getPointer(this) } } ``` #### Production Standard (Correct) > **Standard**: The native buffer allocation is contained within memScoped, and only pure Kotlin managed primitives (ByteArray) cross the boundary back to callers. ```kotlin @OptIn(ExperimentalForeignApi::class) fun parseNativeBufferGood(data: ByteArray): ByteArray { return memScoped { val nativeBuffer = allocArray<ByteVar>(data.size) data.forEachIndexed { index, byte -> nativeBuffer[index] = byte } // Process natively within scope and project back into safe Kotlin managed memory val processedSize = process_c_buffer(nativeBuffer, data.size) nativeBuffer.readBytes(processedSize) } } ``` ### Long-lived Native Handle with Cleaner-Backed Deterministic Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocating from nativeHeap without lifecycle encapsulation or paired nativeHeap.free() guarantees a perpetual memory leak on iOS/macOS targets. ```kotlin @OptIn(ExperimentalForeignApi::class) class NativeSessionBad { // LEAK: Unmanaged heap allocation with no deallocation hook or cleanup tracking val sessionPtr: CPointer<SessionStruct> = nativeHeap.alloc<SessionStruct>().ptr fun execute() { sessionPtr.pointed.status = 1 } } ``` #### Production Standard (Correct) > **Standard**: Uses an Arena lifecycle wrapped inside an AutoCloseable, guarded by an atomic flag and backed by createCleaner as a safety net against finalize-time leaks. ```kotlin @OptIn(ExperimentalForeignApi::class, kotlin.experimental.ExperimentalNativeApi::class) class NativeSessionGood : AutoCloseable { private val arena = Arena() private val sessionRef: SessionStruct = arena.alloc<SessionStruct>() private val isClosed = kotlin.concurrent.AtomicBoolean(false) @Suppress("unused") private val cleaner = kotlin.native.internal.createCleaner(arena) { nativeArena -> nativeArena.clear() } fun execute() { check(!isClosed.value) { "NativeSession has already been disposed" } sessionRef.status = 1 } override fun close() { if (isClosed.compareAndSet(expected = false, new = true)) { arena.clear() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Native Memory Cinterop Arena Scoping and Finalizer Guardrail

KMP Native Memory Cinterop Arena Scoping and Finalizer Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict native memory management invariants when bridging C/Objective-C pointers into Kotlin Multiplatform code via kotlinx.cinterop. Mandates explicit Arena/AutofreeScope lifetimes, forbids unmanaged native allocations escaping into common code, and requires atomic cleaner/finalizer disposal mechanisms to avoid use-after-free or native memory leaks. 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: Escaping Raw C Pointers and Unscoped Native Allocations Across Common Code 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	Escaping Raw C Pointers and Unscoped Native Allocations Across Common Code 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 scope short-lived native C allocations within memScoped { ... } blocks and extract raw primitive or heap-managed Kotlin types before the scope exits.

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.