Kotlin/Native Explicit Memory Reclamation and Autorelease Boundary Enforcement

--- description: Kotlin/Native Explicit Memory Reclamation and Autorelease Boundary Enforcement - Enforces deterministic native memory boundaries and Objective-C autorelease pool wrapping across Kotlin/Native background processing on iOS. Prevents process termination by iOS Jetsam (OOM) caused by deferred Kotlin/Native garbage collector transitions and accumulated Objective-C bridged allocations during high-throughput loops. globs: **/iosMain/**/*.kt, **/appleMain/**/*.kt, **/nativeMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-memory-deallocation-boundary-standard" --- # Kotlin/Native Explicit Memory Reclamation and Autorelease Boundary Enforcement > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Interop Allocations and Missing Autorelease Pools in KMP Background Coroutines ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Darwin native internals. You must enforce strict native memory boundaries, explicit autorelease pool scoping, and deterministic CPointer lifecycle barriers on all Kotlin/Native code targeting iOS. Reject any implementation where high-throughput background tasks generate platform objects or interop pointers without explicit drainage barriers. ## Strict Guidelines - Engineers MUST ALWAYS wrap intensive interop calls (Objective-C/Cocoa Touch/CoreGraphics) within `autoreleasepool { ... }` blocks when running inside loops or long-lived coroutines on iOS. - Engineers MUST ALWAYS confine native heap structures and C pointers (`CPointer`, `CValuesRef`) to `memScoped { ... }` blocks, ensuring automatic reclamation upon block exit. - Engineers MUST NOT rely on the Kotlin/Native concurrent garbage collector to opportunistically drain Darwin autorelease pools or release heavy foreign bridge objects. - Code executing iterative batch workloads across thread hops SHOULD chunk executions and invoke `yield()` or explicit memory reclamation triggers to avoid spiking high-water memory marks. - Services MUST explicitly call `.free()` on manual `nativeHeap.alloc` calls within `try/finally` blocks if `memScoped` lifetime does not fit the asynchronous lifecycle. - Components NEVER bridge raw Objective-C bitmaps, byte buffers, or Foundation types into unbound state variables without defining an explicit invalidation and release path. ## Bad vs Good Implementations ### Batch Image Buffer Processing on iOS #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Each iteration constructs an Objective-C NSData bridged instance. In a Kotlin coroutine worker thread without an explicit autorelease pool, these autoreleased references remain retained until the thread context resets, driving heap usage beyond the iOS foreground/background memory limit. ```kotlin import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import platform.Foundation.NSData import platform.Foundation.dataWithBytes import kotlinx.cinterop.addressOf import kotlinx.cinterop.usePinned suspend fun processImageBatches(rawFrames: List<ByteArray>): List<NSData> = withContext(Dispatchers.Default) { // ANTI-PATTERN: Native NSData allocations accumulate in the thread-local autorelease pool. // In high-frequency background coroutines, the pool is never drained, causing iOS Jetsam OOM crashes. rawFrames.map { frame -> frame.usePinned { pinned -> NSData.dataWithBytes(pinned.addressOf(0), frame.size.toULong()) } } } ``` #### Production Standard (Correct) > **Standard**: By bounding chunk processing within both `autoreleasepool` and `memScoped`, native memory allocations and bridged Foundation instances are deterministically released at the boundary of every chunk, preventing heap accumulation and eliminating Jetsam terminations. ```kotlin import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext import kotlinx.coroutines.yield import kotlinx.cinterop.autoreleasepool import kotlinx.cinterop.memScoped import kotlinx.cinterop.allocArrayOf import platform.Foundation.NSData import platform.Foundation.dataWithBytes suspend fun processImageBatches(rawFrames: List<ByteArray>): List<NSData> = withContext(Dispatchers.Default) { val results = mutableListOf<NSData>() val batchThreshold = 50 rawFrames.chunked(batchThreshold).forEach { chunk -> // PRODUCTION INVARIANT: Encapsulate chunk within explicit autoreleasepool // to force immediate native deallocation of bridged Obj-C objects. autoreleasepool { memScoped { for (frame in chunk) { val nativeBuffer = allocArrayOf(frame) val nsData = NSData.dataWithBytes(nativeBuffer, frame.size.toULong()) results.add(nsData) } } } // Yield control to allow native thread scheduler and GC cooperatively sweep yield() } results } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin/Native Explicit Memory Reclamation and Autorelease Boundary Enforcement

Kotlin/Native Explicit Memory Reclamation and Autorelease Boundary Enforcement defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic native memory boundaries and Objective-C autorelease pool wrapping across Kotlin/Native background processing on iOS. Prevents process termination by iOS Jetsam (OOM) caused by deferred Kotlin/Native garbage collector transitions and accumulated Objective-C bridged allocations during high-throughput loops. 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: Unbounded Interop Allocations and Missing Autorelease Pools in KMP Background Coroutines 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	Unbounded Interop Allocations and Missing Autorelease Pools in KMP Background Coroutines	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 intensive interop calls (Objective-C/Cocoa Touch/CoreGraphics) within `autoreleasepool { ... }` blocks when running inside loops or long-lived coroutines on iOS.

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.