Kotlin Native Concurrent GC Frame Budget and Safepoint Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Uncontrolled Ephemeral Allocations in Real-Time Callbacks Triggering Unscheduled K/N GC Safepoint Stalls) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Kotlin Native Concurrent GC Frame Budget and Safepoint Standard

--- description: Kotlin Native Concurrent GC Frame Budget and Safepoint Standard - Enforces strict zero-allocation pathways in real-time execution loops and explicit garbage collector scheduling controls for Kotlin Multiplatform Native. Guarantees that thread-state safepoints and concurrent cycle-collector reconciliation passes stay strictly within bounded time windows (<= 3ms), preventing audio buffer underruns and 60fps/120fps UI hitching. globs: **/*.kt, **/build.gradle.kts, **/*.def alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-native-concurrent-gc-frame-budget-standard" --- # Kotlin Native Concurrent GC Frame Budget and Safepoint Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Uncontrolled Ephemeral Allocations in Real-Time Callbacks Triggering Unscheduled K/N GC Safepoint Stalls ## System Constraints You are a Principal Software Architect enforcing KMP Native Concurrent Garbage Collector Frame Budget Standards. You must ensure that Kotlin/Native multiplatform code never allows dynamic heap allocations, reference graph sweeps, or thread-state polling safepoint stalls inside real-time paths such as CoreAudio/Oboe callbacks, high-frequency sensor streaming, or frame rendering phases (DisplayLink/Choreographer). Mandate explicit GC tuning, pre-allocated memory pools, Arena-based native memory structures, and non-blocking idle-time GC scheduling. ## Strict Guidelines - Engineers MUST ALWAYS isolate real-time native audio and display-rendering pipelines from Kotlin heap allocations using pre-allocated native memory pools or Arena buffers. - Engineers MUST NOT create ephemeral objects, closures, coroutine scopes, or cyclic graph instances inside high-frequency native-to-Kotlin callbacks (>= 60 Hz). - Services MUST explicitly schedule Kotlin/Native garbage collector passes using `kotlin.native.internal.GC.schedule()` during known frame idle periods or background lifecycle boundaries rather than letting the runtime invoke unconstrained mark-sweep safepoints. - Code SHOULD configure `-Xallocator=mimalloc` and `-Xgc=cms` in Gradle build scripts to ensure concurrent mark-and-sweep operation with minimal stop-the-world safepoint duration. - Components NEVER bridge foreign C/Objective-C callbacks directly into standard suspend functions without passing through a lock-free, zero-allocating circular ring buffer. ## Bad vs Good Implementations ### Audio Callback Real-Time Heap Allocation vs. Pre-Allocated Native Arena Buffer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocating boxed Float instances, intermediate collections, and Coroutine jobs inside a real-time native audio callback floods the Kotlin/Native CMS GC. The concurrent collector is forced to trigger safepoints on background threads, causing stop-the-world polling synchronization that blows past the 5ms audio buffer deadline, yielding audible glitching and underrun clicks. ```kotlin import kotlinx.cinterop.* import kotlinx.coroutines.* // ANTI-PATTERN: Heap allocations and coroutine launches inside high-frequency native audio callback @OptIn(ExperimentalForeignApi::class) class AudioStreamReceiver { private val scope = CoroutineScope(Dispatchers.Default) fun onAudioBufferReceived(nativeSamples: CPointer<FloatVar>, frameCount: Int) { // Generates ephemeral Kotlin objects and auto-boxing per audio quantum (every ~5-10ms) val sampleList = (0 until frameCount).map { idx -> nativeSamples[idx] } // Asynchronous context dispatch forces safepoint polling and thread-state transitions scope.launch { processSamples(sampleList) } } private fun processSamples(samples: List<Float>) { // Dynamic graph analysis triggering GC safepoints } } ``` #### Production Standard (Correct) > **Standard**: Eliminates all Kotlin heap allocations in the audio processing thread by utilizing `Arena.allocArray` and direct pointer manipulation. Because zero Kotlin managed objects are materialized, the concurrent garbage collector is never forced to pause or reconcile thread states, ensuring strict adherence to the audio underrun budget. ```kotlin import kotlinx.cinterop.* // PRODUCTION FIX: Zero-allocation native buffer processing with pinned pre-allocated storage @OptIn(ExperimentalForeignApi::class) class AudioStreamReceiver(private val maxFrameCapacity: Int) { private val nativeArena = Arena() private val ringBuffer: CPointer<FloatVar> = nativeArena.allocArray(maxFrameCapacity) fun onAudioBufferReceived(nativeSamples: CPointer<FloatVar>, frameCount: Int) { // Invariant: Direct pointer indexing, no auto-boxing, zero Kotlin heap allocations if (frameCount > maxFrameCapacity) return var i = 0 while (i < frameCount) { ringBuffer[i] = nativeSamples[i] i++ } // Native-to-native lock-free computation; stays safely within the sub-millisecond frame budget processDirect(ringBuffer, frameCount) } private fun processDirect(samples: CPointer<FloatVar>, count: Int) { // In-place processing without triggering Kotlin/Native thread safepoints } fun dispose() { nativeArena.clear() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Native Concurrent GC Frame Budget and Safepoint Standard

Kotlin Native Concurrent GC Frame Budget and Safepoint Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict zero-allocation pathways in real-time execution loops and explicit garbage collector scheduling controls for Kotlin Multiplatform Native. Guarantees that thread-state safepoints and concurrent cycle-collector reconciliation passes stay strictly within bounded time windows (<= 3ms), preventing audio buffer underruns and 60fps/120fps UI hitching. 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: Uncontrolled Ephemeral Allocations in Real-Time Callbacks Triggering Unscheduled K/N GC Safepoint Stalls 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	Uncontrolled Ephemeral Allocations in Real-Time Callbacks Triggering Unscheduled K/N GC Safepoint Stalls	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 isolate real-time native audio and display-rendering pipelines from Kotlin heap allocations using pre-allocated native memory pools or Arena buffers.

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.