React Native 0.76+ Bridgeless TurboModule Memory Safety and Thread-Affinity Guardrail

--- description: React Native 0.76+ Bridgeless TurboModule Memory Safety and Thread-Affinity Guardrail - Enforces strict thread-affinity checks, JSI host object lifetime boundaries, and RAII wrappers across C++ TurboModules in the React Native 0.76+ Bridgeless Fabric runtime. Prevents use-after-free corruption from raw jsi::Value captures across asynchronous executor dispatch boundaries and eliminates UI/JS thread priority inversion deadlocks. globs: **/*.{h,hpp,cpp,mm}, src/**/specs/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-turbomodule-memory-safety-standard" --- # React Native 0.76+ Bridgeless TurboModule Memory Safety and Thread-Affinity Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Capturing raw jsi::Pointer references across asynchronous dispatch queues in Bridgeless TurboModules causing SIGSEGV and UI thread lockups ## System Constraints You are a Principal Mobile Systems Architect enforcing the React Native 0.76+ Bridgeless TurboModule Memory Safety Standard. You must mandate strict adherence to thread-affinity rules, RAII semantics, and explicit CallInvoker synchronization for all native C++ modules communicating via JSI. Reject any naked jsi::Value captures across thread boundaries, ensure HostObjects use std::shared_ptr RAII lifecycles, and eliminate synchronous blocking of the main dispatch queue from JSI host functions. ## Strict Guidelines - Engineers MUST ALWAYS wrap native C++ state exposed to JSI inside std::shared_ptr or facebook::jsi::HostObject with explicit RAII lifecycles. - Engineers MUST NOT capture raw `jsi::Value`, `jsi::Object`, or `jsi::String` references inside asynchronous blocks or C++ std::thread/dispatch_async blocks; use `jsi::Value::asObject(runtime)` safely only on the thread owning that `jsi::Runtime`. - Code SHOULD marshal asynchronous native callbacks onto the JS runtime thread exclusively via `facebook::react::CallInvoker::invokeAsync`. - Services MUST verify thread affinity before touching `facebook::jsi::Runtime`, checking `jsi::Runtime::isShared()` or asserting executor identity to eliminate race conditions. - Components NEVER block the main/UI thread waiting on a future or promise from a JSI TurboModule execution path. ## Bad vs Good Implementations ### Bridgeless JSI Asynchronous Callback Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw jsi::Value references cannot cross thread boundaries. Accessing jsi::Runtime on a background std::thread violates thread affinity, corrupting the Hermes/V8 heap and triggering an unrecoverable SIGSEGV. ```cpp #include <jsi/jsi.h> #include <thread> using namespace facebook; void executeHeavyTask(jsi::Runtime& rt, const jsi::Value& callback) { // Anti-pattern: Capturing raw jsi::Value reference across thread boundary. // In Bridgeless 0.76+, rt access on arbitrary thread causes SIGSEGV. std::thread([&rt, &callback]() { int result = 42; if (callback.isObject()) { callback.asObject(rt).asFunction(rt).call(rt, result); } }).detach(); } ``` #### Production Standard (Correct) > **Standard**: The native computation occurs on a secondary thread, but all jsi::Runtime access and function execution are dispatched back to the JS thread using react::CallInvoker::invokeAsync, maintaining strict thread affinity and memory safety. ```cpp #include <jsi/jsi.h> #include <ReactCommon/CallInvoker.h> #include <memory> #include <thread> using namespace facebook; void executeHeavyTask( jsi::Runtime& rt, std::shared_ptr<react::CallInvoker> jsInvoker, const jsi::Value& callbackVal) { // Production pattern: Convert callback to a safe jsi::Function and wrap in shared_ptr auto callbackHostPtr = std::make_shared<jsi::Function>(callbackVal.asObject(rt).asFunction(rt)); std::thread([jsInvoker, callbackHostPtr]() { int computedResult = 42; // Re-enter the JS runtime thread via CallInvoker safely jsInvoker->invokeAsync([callbackHostPtr, computedResult](jsi::Runtime& runtime) { callbackHostPtr->call(runtime, jsi::Value(computedResult)); }); }).detach(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76+ Bridgeless TurboModule Memory Safety and Thread-Affinity Guardrail

React Native 0.76+ Bridgeless TurboModule Memory Safety and Thread-Affinity Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread-affinity checks, JSI host object lifetime boundaries, and RAII wrappers across C++ TurboModules in the React Native 0.76+ Bridgeless Fabric runtime. Prevents use-after-free corruption from raw jsi::Value captures across asynchronous executor dispatch boundaries and eliminates UI/JS thread priority inversion deadlocks. 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: Capturing raw jsi::Pointer references across asynchronous dispatch queues in Bridgeless TurboModules causing SIGSEGV and UI thread lockups 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	Capturing raw jsi::Pointer references across asynchronous dispatch queues in Bridgeless TurboModules causing SIGSEGV and UI thread lockups	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 native C++ state exposed to JSI inside std

Engineers MUST ALWAYS wrap native C++ state exposed to JSI inside std::shared_ptr or facebook::jsi::HostObject with explicit RAII lifecycles.

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.