React Native 0.76 Bridgeless TurboModule JSI Memory Boundary & Thread Affinity Standard

--- description: React Native 0.76 Bridgeless TurboModule JSI Memory Boundary & Thread Affinity Standard - Enforces strict JSI thread-affinity constraints and deterministic heap memory boundaries in React Native 0.76+ Bridgeless TurboModules. Prevents fatal Hermes GC heap corruption, cross-thread jsi::Value dereferencing, and dangling pointer segmentation faults across native C++ and JS runtime contexts. globs: ios/**/*.{mm,cpp,h}, android/**/*.{cpp,h}, src/specs/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-turbomodule-jsi-memory-boundary" --- # React Native 0.76 Bridgeless TurboModule JSI Memory Boundary & Thread Affinity Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining bare jsi::Value references across threads without CallInvoker synchronization or thread-safe heap handles ## System Constraints You are a Principal Mobile Architect enforcing the React Native 0.76 Bridgeless TurboModule JSI Memory Boundary Guardrail. Mandate strict single-threaded runtime access, deep copy before thread marshaling, and deterministic CallInvoker asynchronous dispatching. Prevent dangling references and GC heap corruption under Hermes and V8 engines. ## Strict Guidelines - Engineers MUST ALWAYS convert jsi::Value, jsi::String, and jsi::Object instances into native C++ value types (std::string, int, double, folly::dynamic) before crossing thread boundaries. - Engineers MUST NOT pass bare jsi::Runtime references, jsi::Value references, or raw jsi::Pointer handles into background worker threads or GCD/std::async closures. - Code MUST ALWAYS use the TurboModule's CallInvoker (jsInvoker_->invokeAsync) to marshal callbacks and promise settlements back to the JavaScript thread before executing JSI functions. - Engineers MUST NOT store jsi::Value or jsi::Object as long-lived member variables on TurboModule C++ instances; use jsi::WeakObject or persistent native identifiers instead. - TurboModule specs in TypeScript MUST strictly define non-dynamic types extending TurboModuleRegistry Spec interfaces to enable deterministic Codegen validation. ## Bad vs Good Implementations ### C++ JSI Cross-Thread Value Dispatching in TurboModules #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing raw jsi::Runtime and jsi::Value across native thread boundaries violates JSI's single-thread affinity. When Hermes performs a concurrent GC sweep (Hades), accessing or mutating objects from a secondary thread causes immediate memory corruption or fatal crashes. ```cpp #include <ReactCommon/CallInvoker.h> #include <jsi/jsi.h> #include <thread> using namespace facebook; void executeHeavyTask(jsi::Runtime &rt, const jsi::Value &callback) { // Anti-pattern: Capturing raw jsi::Runtime reference and bare jsi::Value across threads // Causes Hermes/V8 heap corruption, race conditions, and SIGSEGV during GC collection. std::thread([&rt, &callback]() { int result = 42; // Heavy computation callback.asObject(rt).asFunction(rt).call(rt, jsi::Value(result)); }).detach(); } ``` #### Production Standard (Correct) > **Standard**: Offloads computational work safely by passing immutable native data, and marshals invocation back to the JS thread using CallInvoker. JSI operations occur exclusively on the thread owning jsi::Runtime, preserving Hermes memory isolation. ```cpp #include <ReactCommon/CallInvoker.h> #include <jsi/jsi.h> #include <memory> #include <thread> using namespace facebook; void executeHeavyTask( jsi::Runtime &rt, const jsi::Function &callback, std::shared_ptr<react::CallInvoker> jsInvoker) { // Invariant Fix: Transform callback into a shared thread-safe pointer and capture data by value auto sharedCallback = std::make_shared<jsi::Function>(callback.asFunction(rt)); std::thread([sharedCallback, jsInvoker]() { int computedResult = 42; // Offloaded work safely executed off-runtime // Marshal execution back onto JS runtime thread via CallInvoker jsInvoker->invokeAsync([sharedCallback, computedResult](jsi::Runtime &runtime) { sharedCallback->call(runtime, jsi::Value(computedResult)); }); }).detach(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76 Bridgeless TurboModule JSI Memory Boundary & Thread Affinity Standard

React Native 0.76 Bridgeless TurboModule JSI Memory Boundary & Thread Affinity Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict JSI thread-affinity constraints and deterministic heap memory boundaries in React Native 0.76+ Bridgeless TurboModules. Prevents fatal Hermes GC heap corruption, cross-thread jsi::Value dereferencing, and dangling pointer segmentation faults across native C++ and JS runtime contexts. 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: Retaining bare jsi::Value references across threads without CallInvoker synchronization or thread-safe heap handles 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	Retaining bare jsi::Value references across threads without CallInvoker synchronization or thread-safe heap handles	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 convert jsi

Engineers MUST ALWAYS convert jsi::Value, jsi::String, and jsi::Object instances into native C++ value types (std::string, int, double, folly::dynamic) before crossing thread boundaries.

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.