React Native Fabric/JSI Synchronous TurboModule Reentrancy and Threading Guardrail

--- description: "React Native Fabric/JSI Synchronous TurboModule Reentrancy and Threading Guardrail - Eliminates thread deadlocks, priority inversions, and lock contention occurring when concurrent JavaScript operations synchronously invoke native C++ TurboModules across Fabric UI rendering threads and JS threads. Enforces asynchronous bridging or non-blocking lockless state reads for any native state accessed during synchronous layout or render phases." globs: "src/**/*.{ts,tsx}, ios/**/*.{h,m,mm,cpp}, android/app/src/main/**/*.{java,kt,cpp}" alwaysApply: true license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-turbomodule-sync-reentrancy-guardrail" --- # React Native Fabric/JSI Synchronous TurboModule Reentrancy and Threading Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronously blocking C++ TurboModule invocations during layout calculation or cross-thread state resolution causing main-thread deadlock ## System Constraints You are a Principal Mobile Architect specializing in the React Native New Architecture (Fabric, TurboModules, and JSI). Mandate strict isolation between synchronous native TurboModule JSI methods and concurrent execution paths. Ensure synchronous JSI calls never acquire mutex locks held across UI thread mutations, preventing reentrancy deadlocks between the JS thread and Fabric background commit pipelines. ## Strict Guidelines - Engineers MUST NEVER execute synchronous TurboModule methods (`TurboModule.syncMethod()`) inside Fabric layout measures, render hooks, or synchronous component lifecycles without strict lockless read semantics. - Engineers MUST NOT acquire blocking mutexes (e.g., `std::mutex::lock`) inside JSI synchronous hooks if those same locks are acquired during Fabric shadow-tree mutations on the UI/render thread. - Native TurboModules exposing synchronous JSI getters MUST maintain atomic, copy-on-write, or read-copy-update (RCU) snapshots to guarantee zero wait-time execution across concurrent threads. - High-throughput native mutations MUST dispatch asynchronously to dedicated worker queues rather than preempting synchronous host function execution. - Components NEVER trigger synchronous native updates inside event callbacks that execute concurrently with layout recalculations (e.g., `onLayout`, custom Fabric shadow measurement). ## Bad vs Good Implementations ### Eliminating Synchronous Mutex Lock Inversion via Atomic Snapshots in TurboModules #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking a synchronous TurboModule method inside active component rendering locks the JS thread while waiting for native synchronization primitives. If the native implementation attempts to sync with the main or UI thread simultaneously, a fatal deadlock occurs. ```typescript import { TurboModuleRegistry } from 'react-native'; interface DeviceSyncMetricsModule { getSynchronousMetrics(): { frameDropCount: number; memoryPressure: string }; recordEvent(eventName: string): void; } const MetricsModule = TurboModuleRegistry.getEnforcing<DeviceSyncMetricsModule>('DeviceSyncMetrics'); // ANTI-PATTERN: Calling synchronous native modules inside render or measure // When native side holds a mutex to mutate state on UI thread while JS thread waits // on getSynchronousMetrics(), Fabric deadlocks. export function useRenderTracking(componentId: string) { const metrics = MetricsModule.getSynchronousMetrics(); // Native mutex lock contention MetricsModule.recordEvent(`render_${componentId}`); return metrics; } ``` #### Production Standard (Correct) > **Standard**: Accesses a lockless atomic native snapshot via non-blocking JSI operations, and defers mutating events to an asynchronous dispatch pipeline decoupled from Fabric's synchronous render-and-commit loop. ```typescript import { TurboModuleRegistry } from 'react-native'; import { useEffect, useRef } from 'react'; interface DeviceSyncMetricsModule { getAtomicMetricsSnapshot(): { frameDropCount: number; memoryPressure: string }; queueEventAsync(eventName: string): void; } const MetricsModule = TurboModuleRegistry.getEnforcing<DeviceSyncMetricsModule>('DeviceSyncMetrics'); // PRODUCTION FIX: Use atomic lock-free reads and decouple event queuing from render pass export function useRenderTracking(componentId: string) { const metricsRef = useRef<{ frameDropCount: number; memoryPressure: string } | null>(null); // Guaranteed lockless atomic read if (metricsRef.current === null) { metricsRef.current = MetricsModule.getAtomicMetricsSnapshot(); } useEffect(() => { // Native state updates run strictly asynchronous to UI and JS thread render cycles MetricsModule.queueEventAsync(`render_${componentId}`); }, [componentId]); return metricsRef.current; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native Fabric/JSI Synchronous TurboModule Reentrancy and Threading Guardrail

React Native Fabric/JSI Synchronous TurboModule Reentrancy and Threading Guardrail defines an industrial-grade behavioral standard for mobile engineering. Eliminates thread deadlocks, priority inversions, and lock contention occurring when concurrent JavaScript operations synchronously invoke native C++ TurboModules across Fabric UI rendering threads and JS threads. Enforces asynchronous bridging or non-blocking lockless state reads for any native state accessed during synchronous layout or render phases. 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: Synchronously blocking C++ TurboModule invocations during layout calculation or cross-thread state resolution causing main-thread deadlock 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	Synchronously blocking C++ TurboModule invocations during layout calculation or cross-thread state resolution causing main-thread deadlock	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 execute synchronous TurboModule methods (`TurboModule.syncMethod()`) inside Fabric layout measures, render hooks, or synchronous component lifecycles without strict lockless read semantics.

Engineers MUST NEVER execute synchronous TurboModule methods (`TurboModule.syncMethod()`) inside Fabric layout measures, render hooks, or synchronous component lifecycles without strict lockless read semantics.

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.