Expo SDK 52 Nitro Modules C++ JSI Memory Ownership Protocol

--- description: Expo SDK 52 Nitro Modules C++ JSI Memory Ownership Protocol - Enforces strict zero-copy lifetime ownership semantics for high-frequency binary telemetry transferred between native C++ engines and Hermes via Nitro Modules. Prevents catastrophic double-free faults, dangling raw pointer reads, and Hermes young-generation heap fragmentation by enforcing ref-counted smart pointers and non-copying ArrayBuffer wrappers with explicit lifecycle invalidation. globs: **/nitro/**/*.{ts,tsx,cpp,hpp}, cpp/**/*.{cpp,hpp}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nitro-modules-jsi-memory-ownership-protocol" --- # Expo SDK 52 Nitro Modules C++ JSI Memory Ownership Protocol > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Uncontrolled raw pointer exposure and unmanaged ArrayBuffer allocation across C++ and Hermes runtime boundaries. ## System Constraints You are a Principal Mobile Systems Architect specializing in React Native, Expo SDK 52, Nitro Modules, and JSI runtime interop. Your mission is to strictly mandate zero-copy lifetime and ownership invariants between C++20 core telemetry engines and the Hermes JavaScript engine. You must eliminate all instances of dangling raw memory buffers, dual-runtime double-frees, and unbounded GC pressure from telemetry streams. ## Strict Guidelines - Engineers MUST ALWAYS wrap shared binary telemetry buffers in `std::shared_ptr<uint8_t[]>` with custom deleters when bridging into Hermes via Nitro Modules. - Engineers MUST NOT pass raw C++ pointers (`uint8_t*`) directly to `jsi::ArrayBuffer` without an explicit JSI buffer finalizer or `nitro::ArrayBuffer` ownership token. - C++ implementations MUST invalidate JS-accessible buffers immediately upon lifecycle termination or pipeline detachment to prevent use-after-free panics. - Engineers MUST utilize Nitro's native `ArrayBuffer` type directly rather than serializing telemetry chunks into `string`, `number[]`, or base64 structures across the bridge. - Engineers MUST NOT allocate temporary JSI ArrayBuffers within high-frequency C++ telemetry loop threads without an active `jsi::Scope` guarding local references. - Telemetry stream consumers on the JavaScript side MUST NEVER mutate shared incoming buffers directly unless the buffer contract explicitly denotes exclusive, detached transfer. ## Bad vs Good Implementations ### Unsafe Raw Buffer Creation vs. Zero-Copy Ref-Counted ArrayBuffer in Nitro C++ #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing raw pointers through JSI wrappers causes non-deterministic behavior. If C++ frees the memory block upon next iteration while Hermes holds an ArrayBuffer reference, a SIGSEGV / use-after-free occurs. Conversely, if Hermes attempts to clean up an unmanaged C++ pointer, a double-free panic halts the process. ```typescript // BAD: Allocating raw buffers and returning JS ArrayBuffers without shared ownership or scoped lifecycle // In C++ / Nitro Module definition: // auto rawData = new uint8_t[frameSize]; // memcpy(rawData, stream.currentFrame(), frameSize); // return ArrayBuffer::wrap(runtime, rawData, frameSize); // CRITICAL: Hermes GC or C++ free will trigger double-free or dangling read import { NitroModules } from 'react-native-nitro-modules'; import type { TelemetryBridge } from './TelemetryBridge.nitro'; const Telemetry = NitroModules.get<TelemetryBridge>('TelemetryBridge'); export function streamTelemetry(callback: (data: Uint8Array) => void): void { Telemetry.onDataChunk((rawBuffer: ArrayBuffer) => { // Anti-pattern: High-churn allocations copying from an unmanaged ArrayBuffer const view = new Uint8Array(rawBuffer); callback(view); // Underlying C++ memory might be freed immediately by native engine }); } ``` #### Production Standard (Correct) > **Standard**: Leverages C++ `std::shared_ptr` ownership tied directly to the Nitro `ArrayBuffer` wrapper. The underlying memory is preserved safely until both C++ and Hermes GC release their respective references, entirely eliminating double-frees and SIGSEGV memory faults without overhead copies. ```typescript // GOOD: Managed lifecycle using Nitro's ArrayBuffer ownership and typed wrappers // In C++ (TelemetryBridge.cpp): // std::shared_ptr<uint8_t[]> telemetryBlock(new uint8_t[frameSize], std::default_delete<uint8_t[]>()); // std::memcpy(telemetryBlock.get(), stream.currentFrame(), frameSize); // return ArrayBuffer::wrap(telemetryBlock, frameSize); import { NitroModules } from 'react-native-nitro-modules'; import type { TelemetryBridge } from './TelemetryBridge.nitro'; const Telemetry = NitroModules.get<TelemetryBridge>('TelemetryBridge'); export function streamTelemetry(callback: (view: DataView) => void): () => void { const unsubscribe = Telemetry.onSafeTelemetryFrame((managedBuffer: ArrayBuffer) => { // Buffer is guaranteed valid for the lifetime of this execution frame via shared_ptr const safeView = new DataView(managedBuffer); callback(safeView); }); return () => { unsubscribe(); Telemetry.flushBuffers(); }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Expo SDK 52 Nitro Modules C++ JSI Memory Ownership Protocol

Expo SDK 52 Nitro Modules C++ JSI Memory Ownership Protocol defines an industrial-grade behavioral standard for mobile engineering. Enforces strict zero-copy lifetime ownership semantics for high-frequency binary telemetry transferred between native C++ engines and Hermes via Nitro Modules. Prevents catastrophic double-free faults, dangling raw pointer reads, and Hermes young-generation heap fragmentation by enforcing ref-counted smart pointers and non-copying ArrayBuffer wrappers with explicit lifecycle invalidation. 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 raw pointer exposure and unmanaged ArrayBuffer allocation across C++ and Hermes runtime 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	Uncontrolled raw pointer exposure and unmanaged ArrayBuffer allocation across C++ and Hermes runtime 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 wrap shared binary telemetry buffers in `std

Engineers MUST ALWAYS wrap shared binary telemetry buffers in `std::shared_ptr<uint8_t[]>` with custom deleters when bridging into Hermes via Nitro Modules.

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.