KMP Zero-Copy Direct Pinned Buffer Invariant for High-Throughput Streams

--- description: KMP Zero-Copy Direct Pinned Buffer Invariant for High-Throughput Streams - Enforces deterministic zero-copy memory transfers between native C/POSIX/Apple APIs and Kotlin Multiplatform runtimes without triggering garbage collection pressure or cross-heap allocations. Mandates scoped memory pinning using `usePinned` or direct non-managed arena buffers for high-frequency media and sensor streaming. Prohibits converting native byte buffers into intermediary managed `ByteArray` instances within tight processing loops. globs: **/src/nativeMain/**/*.kt, **/src/appleMain/**/*.kt, **/src/posixMain/**/*.kt, **/src/commonMain/**/*Native*.kt, **/cinterop/**/*.def alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-zero-copy-pinned-buffer-invariant" --- # KMP Zero-Copy Direct Pinned Buffer Invariant for High-Throughput Streams > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Intermediary Managed ByteArray Allocations in High-Frequency C-Interop Pipelines ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform (KMP) native runtimes, POSIX interop, and native memory management. Enforce strict zero-copy and pinned buffer invariants when bridging native C/Darwin platform APIs with Kotlin. Every high-throughput sensor or media processing pipeline must eliminate dynamic managed allocations in favor of direct pinned buffers (`usePinned`), direct arena allocations, or shared unmanaged buffers. ## Strict Guidelines - Engineers MUST ALWAYS scope access to managed byte arrays passed to native C functions via `ByteArray.usePinned { pinned -> ... }` to guarantee stable physical memory addresses without copying. - Engineers MUST NOT convert native pointers (`CPointer<ByteVar>`) to managed Kotlin byte arrays (`readBytes()`) in streaming, per-frame, or high-frequency sensor loops. - Engineers MUST pass direct C pointers (`pinned.addressOf(0)`) or wrap native buffers with non-allocating abstractions (such as custom zero-copy direct buffer view interfaces) when interacting with C-interop APIs. - Engineers MUST explicitly manage life-cycles of off-heap buffers using `memScoped` or unmanaged `nativeHeap.allocArray` paired with deterministic deallocation in a `try-finally` block for buffers living beyond single lexical scopes. - Components NEVER hold long-term references to `Pinned<T>` beyond the immediate execution block; unpinning MUST occur deterministically to avoid pinning down the Kotlin/Native GC compaction passes. ## Bad vs Good Implementations ### High-Throughput Native Audio/Sensor Ingestion Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `readBytes(length)` performs a heap-allocated memory copy from native memory to the Kotlin/Native GC-managed heap on every invocation. At high frame rates (e.g., 60-120 FPS camera frames or 48kHz audio buffers), this floods the native GC with transient allocations, spiking memory pressure and triggering compaction pauses. ```kotlin import kotlinx.cinterop.* // ANTI-PATTERN: Copies unmanaged C buffer to managed Kotlin heap on every frame fun processSensorFrame(nativeBuffer: CPointer<ByteVar>, length: Int) { // Allocates a brand new managed ByteArray on every incoming sample/frame! // Induces severe GC pauses and throughput degradation at 60Hz-120Hz/Audio rates. val heapArray = nativeBuffer.readBytes(length) dispatchToProcessors(heapArray) } fun dispatchToProcessors(data: ByteArray) { // Consuming data as managed array } ``` #### Production Standard (Correct) > **Standard**: Encapsulates native memory inside a direct non-copying view interface (`DirectBufferView`) allowing zero-overhead reads from the unmanaged C pointer. When writing to native sinks from managed memory, `usePinned` fixes the memory address deterministically with scoped unpinning, ensuring zero transient allocations and zero GC pressure. ```kotlin import kotlinx.cinterop.* interface DirectBufferView { val pointer: CPointer<ByteVar> val length: Int fun get(index: Int): Byte = pointer[index] } class NativeDirectBufferView( override val pointer: CPointer<ByteVar>, override val length: Int ) : DirectBufferView // PRODUCTION FIX: Zero-copy direct pointer encapsulation and scoped pinned writing fun processSensorFrame(nativeBuffer: CPointer<ByteVar>, length: Int) { // Zero-allocation: Pass direct buffer view without heap copying val bufferView = NativeDirectBufferView(nativeBuffer, length) dispatchZeroCopy(bufferView) } fun dispatchZeroCopy(view: DirectBufferView) { // Direct pointer operations without intermediate copies } // For scenarios requiring native calls from pre-allocated Kotlin ByteArrays: fun transmitSampleData(preallocatedBuffer: ByteArray, targetOffset: Int, targetLength: Int, nativeSink: CPointer<ByteVar>) { // Fix native memory address deterministically during C write without GC relocation preallocatedBuffer.usePinned { pinned -> val rawSourcePointer: CPointer<ByteVar> = pinned.addressOf(targetOffset) platform.posix.memcpy(nativeSink, rawSourcePointer, targetLength.convert()) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Zero-Copy Direct Pinned Buffer Invariant for High-Throughput Streams

KMP Zero-Copy Direct Pinned Buffer Invariant for High-Throughput Streams defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic zero-copy memory transfers between native C/POSIX/Apple APIs and Kotlin Multiplatform runtimes without triggering garbage collection pressure or cross-heap allocations. Mandates scoped memory pinning using `usePinned` or direct non-managed arena buffers for high-frequency media and sensor streaming. Prohibits converting native byte buffers into intermediary managed `ByteArray` instances within tight processing 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: Intermediary Managed ByteArray Allocations in High-Frequency C-Interop Pipelines 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	Intermediary Managed ByteArray Allocations in High-Frequency C-Interop Pipelines	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 access to managed byte arrays passed to native C functions via `ByteArray.usePinned { pinned -> ... }` to guarantee stable physical memory addresses without copying.

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.