React Native 0.76 Bridgeless C++ JSI Memory Boundary & Smart Pointer Lifecycle Standard

--- description: React Native 0.76 Bridgeless C++ JSI Memory Boundary & Smart Pointer Lifecycle Standard - Enforces strict C++ smart pointer lifecycles and thread-isolation boundaries when authoring React Native 0.76 Bridgeless TurboModules. Prevents undefined behavior, heap corruption, and Use-After-Free crashes caused by escaping jsi::Value references across threads without CallInvoker synchronization. globs: ios/**/*.{h,mm,cpp}, android/**/*.{h,cpp}, cpp/**/*.{h,cpp,hpp}, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-jsi-memory-boundary" --- # React Native 0.76 Bridgeless C++ JSI Memory Boundary & Smart Pointer Lifecycle Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Escaping Raw JSI References and Pointer State Across Asynchronous Thread Boundaries ## System Constraints You are a Principal Software Architect enforcing React Native 0.76 Bridgeless TurboModule C++ JSI Memory Boundary Standards. Enforce absolute thread confinement for jsi::Runtime, zero serialization overhead via native buffers/HostObjects, and deterministic std::shared_ptr/std::unique_ptr lifecycles. ## Strict Guidelines - Engineers MUST NEVER pass raw jsi::Value, jsi::Object, jsi::String, or jsi::Runtime& references into foreign or background threads. - Engineers MUST copy or convert all incoming JSI parameters into plain C++ types (e.g., std::string, std::vector, int64_t) synchronously on the JS thread before scheduling background work. - Engineers MUST capture facebook::react::CallInvoker via std::shared_ptr to schedule JavaScript thread callbacks when native asynchronous work finishes. - Engineers MUST NEVER block the JavaScript thread using std::mutex::lock, std::condition_variable::wait, or std::future::get while waiting on native background threads. - Code MUST expose long-lived native handles to JavaScript via jsi::HostObject subclasses wrapped strictly in std::shared_ptr<T>. - Services MUST transfer large binary payloads using jsi::ArrayBuffer or facebook::jsi::MutableBuffer rather than serializing payloads through JSON strings or jsi::Array primitives. ## Bad vs Good Implementations ### C++ JSI Asynchronous Execution Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Capturing jsi::Runtime reference and jsi::Value across a thread boundary violates JSI thread confinement. The JavaScript runtime is single-threaded; invoking callback.asObject(rt) from std::thread races with the Hermes/V8 garbage collector and leads to fatal native memory crashes. ```cpp #include <jsi/jsi.h> #include <thread> using namespace facebook; // ANTI-PATTERN: Capturing jsi::Runtime and jsi::Value in background thread jsi::Value processDataAsync( jsi::Runtime &rt, const jsi::Value &thisVal, const jsi::Value *args, size_t count) { const jsi::Value &callback = args[0]; // Capturing raw JSI value std::thread([&rt, &callback]() { // FATAL: Accessing jsi::Runtime from background thread triggers SIGSEGV / UAF std::string result = "processed_payload"; callback.asObject(rt).asFunction(rt).call( rt, jsi::String::createFromUtf8(rt, result) ); }).detach(); return jsi::Value::undefined(); } ``` #### Production Standard (Correct) > **Standard**: Parameters are safely unmarshalled into native std::string types on the JS thread. Re-entry into JavaScript is mediated by facebook::react::CallInvoker::invokeAsync, ensuring JSI value creation and function execution occur strictly within the thread context owned by jsi::Runtime. ```cpp #include <jsi/jsi.h> #include <ReactCommon/CallInvoker.h> #include <memory> #include <string> #include <thread> using namespace facebook; // CORRECT: Synchronous parameter conversion and safe CallInvoker bounce-back jsi::Value processDataAsync( jsi::Runtime &rt, const std::shared_ptr<react::CallInvoker> &jsInvoker, const jsi::Value *args, size_t count) { // 1. Synchronously unbox primitive input on JS thread std::string inputParam = args[0].asString(rt).utf8(rt); auto jsCallback = std::make_shared<jsi::Value>(rt, args[1]); // 2. Offload to background worker using isolated C++ standard types std::thread([inputParam, jsCallback, jsInvoker]() mutable { std::string computedResult = inputParam + "_processed"; // 3. Re-enter JS thread safely via CallInvoker before touching JSI jsInvoker->invokeAsync([computedResult = std::move(computedResult), jsCallback = std::move(jsCallback)](jsi::Runtime &rt) { if (!jsCallback->isObject() || !jsCallback->getObject(rt).isFunction(rt)) { return; } jsCallback->getObject(rt).getFunction(rt).call( rt, jsi::String::createFromUtf8(rt, computedResult) ); }); }).detach(); return jsi::Value::undefined(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76 Bridgeless C++ JSI Memory Boundary & Smart Pointer Lifecycle Standard

React Native 0.76 Bridgeless C++ JSI Memory Boundary & Smart Pointer Lifecycle Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict C++ smart pointer lifecycles and thread-isolation boundaries when authoring React Native 0.76 Bridgeless TurboModules. Prevents undefined behavior, heap corruption, and Use-After-Free crashes caused by escaping jsi::Value references across threads without CallInvoker synchronization. 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 JSI References and Pointer State Across Asynchronous Thread 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 JSI References and Pointer State Across Asynchronous Thread 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 NEVER pass raw jsi

Engineers MUST NEVER pass raw jsi::Value, jsi::Object, jsi::String, or jsi::Runtime& references into foreign or background threads.

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.