React Native 0.76+ Bridgeless Fabric JSI Concurrency Invariant

--- description: React Native 0.76+ Bridgeless Fabric JSI Concurrency Invariant - In React Native 0.76+ Bridgeless Mode with Fabric and the New Architecture, synchronous C++ JSI host object methods and TurboModule invocations bound to the JS Runtime must never be executed on background worker threads without runtime isolation. Violating this invariant causes fatal UI thread deadlocks, SIGSEGV crashes from non-thread-safe JSI pointer dereferencing, and engine heap corruption. globs: src/**/*.{ts,tsx,cpp,h,mm} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-fabric-jsi-concurrency-guardrail" --- # React Native 0.76+ Bridgeless Fabric JSI Concurrency Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Calling synchronous JSI Host Objects or TurboModules directly from background web workers or secondary thread runtimes ## System Constraints You are a Principal Mobile Architect specializing in React Native's New Architecture (0.76+ Bridgeless, Fabric, Hermes, and C++ JSI). Enforce strict thread affinity and concurrency invariants: synchronous JSI host objects and TurboModule APIs bound to the primary JS runtime must never be accessed synchronously from secondary threads or Web Workers. Demand asynchronous message-passing boundaries, thread-safe call invokers, or isolated worker runtimes to prevent UI deadlocks and fatal memory corruptions. ## Strict Guidelines - Engineers MUST ALWAYS dispatch tasks requiring main JSI host-object state to the primary JS thread via runOnJS, async message passing, or CallInvoker. - Engineers MUST NOT invoke synchronous TurboModule functions (e.g., synchronous MMKV, direct crypto bindings, or global host objects) directly inside background threads or secondary worker runtimes. - C++ Native Modules MUST wrap thread interactions with `jsInvoker_->invokeAsync(...)` rather than holding raw `jsi::Runtime&` or `jsi::Value` references across foreign threads. - Services interacting with background task runners (such as react-native-worklets-core or secondary Hermes runtimes) MUST exchange pure, serializable payloads across runtime boundaries. - Components NEVER trigger synchronous native JSI access inside off-thread microtasks or Fabric concurrent rendering loops that lock the UI thread. ## Bad vs Good Implementations ### Invoking Synchronous Native JSI Host Objects from Background Worklets #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: JSI host objects and Hermes runtime pointers are not thread-safe. Dereferencing a primary-thread JSI host object from a background worker thread violates runtime thread affinity, causing immediate heap corruption or deadlock when Fabric commits frames. ```typescript import { runOnWorker } from 'react-native-worklets-core'; // Host object registered globally on the primary Hermes JSI Runtime declare const nativeStorageHostObject: { getSync(key: string): string }; export function readPreferencesAsync(key: string): Promise<string> { return new Promise((resolve) => { runOnWorker(() => { 'worklet'; // CRITICAL CRASH: Accessing primary runtime JSI Host Object directly // from a secondary background worker thread causes SIGSEGV or UI thread deadlocks. const value = nativeStorageHostObject.getSync(key); resolve(value); }); }); } ``` #### Production Standard (Correct) > **Standard**: By reading the JSI host object strictly on the main thread and copying the serializable string value across the boundary, thread affinity is preserved and JSI memory corruption is eliminated. ```typescript import { runOnWorker, runOnJS } from 'react-native-worklets-core'; declare const nativeStorageHostObject: { getSync(key: string): string }; function readStorageOnMainThread(key: string): string { // Must execute strictly on the main JS runtime thread return nativeStorageHostObject.getSync(key); } export function processDataInWorker(key: string, onComplete: (result: string) => void): void { // 1. Resolve host-object data synchronously on the main JS thread first const rawData = readStorageOnMainThread(key); // 2. Pass pure, serializable primitives across the thread boundary runOnWorker(() => { 'worklet'; const computed = rawData.toUpperCase(); // Intensive background transformation // 3. Dispatch back to the JS thread cleanly runOnJS(onComplete)(computed); }); } ``` ### C++ JSI Native Bridge Host Object Concurrency with CallInvoker #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Holding a reference to jsi::Runtime or executing jsi::Function::call on an arbitrary C++ thread without acquiring the runtime lock or scheduling through CallInvoker causes data races and crashes Bridgeless Fabric pipelines. ```cpp // Native TurboModule / C++ JSI binding #include <jsi/jsi.h> #include <thread> void computeOnBackground(facebook::jsi::Runtime& rt, facebook::jsi::Function callback) { std::thread([&rt, callback = std::move(callback)]() mutable { // FATAL: Mutating or invoking jsi::Function on a foreign thread without CallInvoker // violates Hermes and React Native Bridgeless thread isolation. rt.global().setProperty(rt, "__bgResult", 42); callback.call(rt, 42); }).detach(); } ``` #### Production Standard (Correct) > **Standard**: Offloads the work to an OS thread and marshals the result back through CallInvoker::invokeAsync, ensuring that the jsi::Runtime is accessed exclusively on the designated JS thread. ```cpp // Native TurboModule / C++ JSI binding #include <jsi/jsi.h> #include <ReactCommon/CallInvoker.h> #include <memory> #include <thread> void computeOnBackgroundSafe( std::shared_ptr<facebook::react::CallInvoker> jsInvoker, std::shared_ptr<facebook::jsi::Value> sharedCallbackHolder) { std::thread([jsInvoker, sharedCallbackHolder]() { // Background heavy computation int result = 42; // Safely re-enter the JS thread using CallInvoker jsInvoker->invokeAsync([result, sharedCallbackHolder](facebook::jsi::Runtime& rt) { if (sharedCallbackHolder->isObject() && sharedCallbackHolder->getObject(rt).isFunction(rt)) { auto fn = sharedCallbackHolder->getObject(rt).getFunction(rt); fn.call(rt, facebook::jsi::Value(result)); } }); }).detach(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76+ Bridgeless Fabric JSI Concurrency Invariant

React Native 0.76+ Bridgeless Fabric JSI Concurrency Invariant defines an industrial-grade behavioral standard for mobile engineering. In React Native 0.76+ Bridgeless Mode with Fabric and the New Architecture, synchronous C++ JSI host object methods and TurboModule invocations bound to the JS Runtime must never be executed on background worker threads without runtime isolation. Violating this invariant causes fatal UI thread deadlocks, SIGSEGV crashes from non-thread-safe JSI pointer dereferencing, and engine heap corruption. 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: Calling synchronous JSI Host Objects or TurboModules directly from background web workers or secondary thread runtimes 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	Calling synchronous JSI Host Objects or TurboModules directly from background web workers or secondary thread runtimes	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 dispatch tasks requiring main JSI host-object state to the primary JS thread via runOnJS, async message passing, or CallInvoker.

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.