React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard

--- description: React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard - Enforces strict memory safety and thread isolation for concurrent C++ JSI TurboModules under React Native Bridgeless Mode. Prevents fatal runtime SIGSEGV crashes and UI thread hitching caused by accessing raw jsi::Value or jsi::Object instances across asynchronous threads without CallInvoker marshalling. globs: src/**/*.{ts,tsx}, tm/**/*.{h,cpp}, android/src/main/jni/**/*.{h,cpp}, ios/**/*.{h,mm,cpp} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-concurrent-jsi-isolation-standard" --- # React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Accessing Unpinned JSI Objects on Background C++ Worker Threads or Blocking Main CallInvoker with Heavy Native Computations ## System Constraints You are a Principal Mobile Architect enforcing the React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard. In Bridgeless Mode, the legacy asynchronous batched bridge is absent; JSI calls execute synchronously on the JavaScript thread. You must strictly forbid any cross-thread retention of unpinned `facebook::jsi::Value` or `facebook::jsi::Object` references. You must mandate offloading CPU-intensive workloads to dedicated C++ worker threads while requiring all callbacks into the JS runtime to be dispatched exclusively through `facebook::react::CallInvoker` with RAII-managed host objects or promises. Never block the main JavaScript thread or access JSI APIs without acquiring the runtime context via CallInvoker. ## Strict Guidelines - Engineers MUST ALWAYS capture `jsi::Value` parameters by value or convert them to plain C++ primitives/structs (e.g., `std::string`, `double`) before dispatching execution to background C++ worker threads. - Engineers MUST NEVER access, dereference, or allocate any `facebook::jsi::Value`, `jsi::Object`, or `jsi::Runtime` instance on arbitrary background threads without a valid `react::CallInvoker::invokeAsync` callback frame bound to that runtime. - Engineers MUST wrap asynchronous JavaScript responses in `facebook::jsi::Value` promises managed via `std::shared_ptr<facebook::react::Promise>` or dispatch callbacks solely through the runtime's dedicated `jsInvoker_` queue. - Native TurboModule methods MUST NOT execute blocking synchronous I/O, large image/buffer decodes, or cryptographic operations directly on the calling JSI JavaScript thread. - TypeScript interfaces MUST declare TurboModule specifications with explicit async Promise signatures or synchronous accessors that are provably sub-millisecond and deterministic. ## Bad vs Good Implementations ### Unsafe Cross-Thread JSI Dereferencing vs. CallInvoker Safe Thread Marshalling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: JSI instances (jsi::Object, jsi::Function, jsi::Runtime) are thread-affine and strictly bound to the JS VM thread. Capturing and invoking jsi::Function directly inside an uncoordinated std::thread bypasses JS runtime thread locks, causing concurrent memory corruption and hard SIGSEGV crashes. ```cpp #include <jsi/jsi.h> #include <thread> using namespace facebook; // ANTI-PATTERN: Capturing jsi::Object/Value by reference and accessing on a std::thread jsi::Value processDataUnsafe(jsi::Runtime& rt, const jsi::Value& input, const jsi::Value* args, size_t count) { // Bad: Capturing raw jsi::Function across thread boundaries causes SIGSEGV auto jsCallback = args[0].asObject(rt).asFunction(rt); std::string payload = args[1].asString(rt).utf8(rt); std::thread([jsCallback = std::move(jsCallback), payload, &rt]() mutable { // FATAL: rt and jsCallback accessed on background thread without CallInvoker synchronization std::string result = heavyNativeWork(payload); jsCallback.call(rt, jsi::String::createFromUtf8(rt, result)); }).detach(); return jsi::Value::undefined(); } ``` #### Production Standard (Correct) > **Standard**: Decouples the background execution from JSI objects by extracting native primitives (std::string) prior to threading. CallInvoker guarantees the callback only re-executes when the JS thread is idle and safely owned by Bridgeless Mode, preventing crashes and main-thread hitching. ```cpp #include <jsi/jsi.h> #include <ReactCommon/CallInvoker.h> #include <thread> #include <memory> using namespace facebook; // PRODUCTION FIX: Marshall native primitives and dispatch back via CallInvoker jsi::Value processDataSafe( jsi::Runtime& rt, std::shared_ptr<react::CallInvoker> jsInvoker, const jsi::Value& thisVal, const jsi::Value* args, size_t count) { // 1. Extract raw JSI values into plain C++ data structures on JS thread std::string payload = args[0].asString(rt).utf8(rt); auto callbackHost = std::make_shared<jsi::Value>(rt, args[1]); // 2. Offload work to background thread, capturing NO JSI objects or raw runtime pointers std::thread([payload, jsInvoker, callbackHost]() { std::string nativeResult = heavyNativeWork(payload); // 3. Re-enter the JS runtime thread safely using CallInvoker jsInvoker->invokeAsync([nativeResult, callbackHost](jsi::Runtime& runtime) { if (callbackHost->isObject() && callbackHost->asObject(runtime).isFunction(runtime)) { auto fn = callbackHost->asObject(runtime).asFunction(runtime); fn.call(runtime, jsi::String::createFromUtf8(runtime, nativeResult)); } }); }).detach(); return jsi::Value::undefined(); } ``` ### TurboModule TypeScript Specification Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring CPU-intensive TurboModule functions as synchronous blocks the JavaScript engine thread during Bridgeless execution, directly dropping UI animation and touch event frames. ```typescript import type { TurboModule } from 'react-native'; import { TurboModuleRegistry } from 'react-native'; // ANTI-PATTERN: Synchronous heavy calls that block the UI render pipeline export interface Spec extends TurboModule { // Blocks Hermes/V8 JS thread synchronously during native processing computeHeavyTransformSync(dataPayload: string): string; } export default TurboModuleRegistry.getEnforcing<Spec>('DataProcessor'); ``` #### Production Standard (Correct) > **Standard**: Exposing the operation as an asynchronous Promise enforces non-blocking JSI semantics across the TypeScript-C++ boundary, preserving a stable 120fps UI render thread. ```typescript import type { TurboModule } from 'react-native'; import { TurboModuleRegistry } from 'react-native'; // PRODUCTION FIX: Async Promise contract allowing non-blocking native isolation export interface Spec extends TurboModule { computeHeavyTransformAsync(dataPayload: string): Promise<string>; } export default TurboModuleRegistry.getEnforcing<Spec>('DataProcessor'); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard

React Native Bridgeless Concurrent C++ JSI TurboModule Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict memory safety and thread isolation for concurrent C++ JSI TurboModules under React Native Bridgeless Mode. Prevents fatal runtime SIGSEGV crashes and UI thread hitching caused by accessing raw jsi::Value or jsi::Object instances across asynchronous threads without CallInvoker marshalling. 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: Accessing Unpinned JSI Objects on Background C++ Worker Threads or Blocking Main CallInvoker with Heavy Native Computations 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	Accessing Unpinned JSI Objects on Background C++ Worker Threads or Blocking Main CallInvoker with Heavy Native Computations	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 capture `jsi

Engineers MUST ALWAYS capture `jsi::Value` parameters by value or convert them to plain C++ primitives/structs (e.g., `std::string`, `double`) before dispatching execution to background C++ worker 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.