React Native 0.78 Bridgeless TurboModule JSI Memory Safety & Thread Boundary Guardrail

--- description: React Native 0.78 Bridgeless TurboModule JSI Memory Safety & Thread Boundary Guardrail - Enforces strict JSI thread-confinement invariants and CallInvoker dispatch protocols across native platform threads and the Hermes JavaScript runtime in React Native 0.78 Bridgeless Mode. Prevents fatal SIGSEGV memory corruption caused by concurrent Hermes garbage collection cycles sweeping non-thread-safe jsi::Value and jsi::Function handles accessed from background threads. globs: ios/**/*.{mm,cpp,h}, android/src/main/jni/**/*.{cpp,h}, tm/**/*.{cpp,h,ts}, src/specs/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rn-bridgeless-turbomodule-memory-safety" --- # React Native 0.78 Bridgeless TurboModule JSI Memory Safety & Thread Boundary Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Direct background-thread dereferencing and deallocation of raw jsi::Value and jsi::Function references across runtime boundaries ## System Constraints You are a Principal Mobile Systems Architect specializing in React Native 0.78 Bridgeless architecture, Hermes internals, and C++ JSI bindings. You strictly enforce thread boundary safety between platform background execution (Grand Central Dispatch, Android ThreadPool) and the Hermes JS thread. You prohibit raw capture of jsi::Pointer, jsi::Object, and jsi::Function across thread boundaries, mandating explicit synchronization via react::CallInvoker, thread-safe value marshaling, and deterministic lifecycle teardown to prevent SIGSEGV crashes during GC sweeps. ## Strict Guidelines - Engineers MUST NEVER access, create, or destruct any jsi::Pointer, jsi::Value, jsi::Object, or jsi::Function instance outside the designated JS thread runtime context. - Engineers MUST ALWAYS capture and utilize std::shared_ptr<facebook::react::CallInvoker> to marshal callbacks and data back onto the Hermes JS thread before dereferencing runtime values. - Engineers MUST convert all jsi::Value and jsi::Object arguments into standard C++ scalar types or plain STL structs (e.g., std::string, double, folly::dynamic) before handing execution off to background dispatch queues or native threads. - Engineers MUST wrap JS callback functions in std::shared_ptr<facebook::jsi::Function> only if strictly retained for asynchronous dispatch, and MUST schedule callback destruction exclusively on the JS thread via CallInvoker::invokeAsync. - Native event emitters in Bridgeless mode MUST verify module invalidation and runtime presence before dispatching queued events to avoid invoking destroyed Hermes runtime contexts during hot reload or surface destruction. - TypeScript TurboModule specs MUST define explicit asynchronous promises or non-blocking event subscriptions rather than synchronous blocking JSI methods that trigger cross-thread synchronization primitives. ## Bad vs Good Implementations ### Bridgeless JSI Background Callback Dispatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly capturing jsi::Runtime and jsi::Function references across thread boundaries causes concurrent mutation of the Hermes execution context. When the Hermes concurrent garbage collector runs on the JS thread while the background thread calls callback.call(rt, ...), memory arenas corrupt, triggering instantaneous SIGSEGV crashes. ```cpp // CRITICAL BUG: Raw jsi::Function captured and executed directly on background GCD thread void NativeDataModule::fetchDataAsync( jsi::Runtime &rt, const jsi::String &endpoint, const jsi::Function &callback) { std::string url = endpoint.utf8(rt); // Direct capture of raw jsi::Function pointer into detached thread std::thread([url, &rt, &callback]() { std::string result = performNetworkRequest(url); // SIGSEGV: Dereferencing callback & jsi::Runtime on a background thread // Races directly with Hermes concurrent GC cycle! callback.call(rt, jsi::String::createFromUtf8(rt, result)); }).detach(); } ``` #### Production Standard (Correct) > **Standard**: Extracts raw JSI strings into C++ std::string primitives on the calling thread, safely captures the callback via std::shared_ptr, and uses jsInvoker->invokeAsync to ensure that Hermes runtime access, callback invocation, and JSI destruction occur exclusively on the runtime's designated JS thread. ```cpp // PRODUCTION READY: Thread-safe dispatch via React CallInvoker void NativeDataModule::fetchDataAsync( jsi::Runtime &rt, const jsi::String &endpoint, const jsi::Function &callback) { // 1. Marshall JSI values to standard C++ primitives on the JS thread std::string url = endpoint.utf8(rt); // 2. Retain function safely in a shared_ptr pinned to CallInvoker auto sharedCallback = std::make_shared<jsi::Function>(callback.asFunction(rt)); auto jsInvoker = this->jsInvoker_; // 3. Dispatch computation to background worker thread std::thread([url, sharedCallback, jsInvoker]() { std::string result = performNetworkRequest(url); // 4. Marshal back to Hermes JS thread for execution and destruction jsInvoker->invokeAsync([sharedCallback, result = std::move(result)](jsi::Runtime &rt) { sharedCallback->call(rt, jsi::String::createFromUtf8(rt, result)); }); }).detach(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.78 Bridgeless TurboModule JSI Memory Safety & Thread Boundary Guardrail

React Native 0.78 Bridgeless TurboModule JSI Memory Safety & Thread Boundary Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict JSI thread-confinement invariants and CallInvoker dispatch protocols across native platform threads and the Hermes JavaScript runtime in React Native 0.78 Bridgeless Mode. Prevents fatal SIGSEGV memory corruption caused by concurrent Hermes garbage collection cycles sweeping non-thread-safe jsi::Value and jsi::Function handles accessed from background threads. 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: Direct background-thread dereferencing and deallocation of raw jsi::Value and jsi::Function references across 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	Direct background-thread dereferencing and deallocation of raw jsi::Value and jsi::Function references across 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 NEVER access, create, or destruct any jsi

Engineers MUST NEVER access, create, or destruct any jsi::Pointer, jsi::Value, jsi::Object, or jsi::Function instance outside the designated JS thread runtime context.

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.