React Native 0.78 Bridgeless TurboModule Thread Confinement & JSI Isolation

--- description: React Native 0.78 Bridgeless TurboModule Thread Confinement & JSI Isolation - Enforces strict thread confinement for JSI HostObjects and native TurboModule invocations under React Native 0.78 Bridgeless mode. Prohibits background threads from directly allocating, capturing, or dereferencing JS thread-bound jsi::Runtime structures, completely mitigating main-thread priority inversions, deadlocks, and memory corruption. globs: src/**/*.{ts,tsx}, specs/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-turbomodule-thread-confinement" --- # React Native 0.78 Bridgeless TurboModule Thread Confinement & JSI Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining Raw JSI HostObjects or Capturing jsi::Runtime State Inside Background Queues ## System Constraints You are a Principal Software Architect enforcing React Native 0.78 Bridgeless TurboModule invariants. In React Native 0.78, the legacy bridge is disabled by default, and TurboModules execute direct JSI transitions. You must mandate strict thread confinement: native asynchronous work must never capture `jsi::Runtime&` or directly allocate `jsi::Value` / `jsi::HostObject` instances off the JavaScript thread. All data crossing thread boundaries must be pure C++ PODs or deserialized plain data structures, and thread return transitions must strictly route through `react::CallInvoker::invokeAsync` to prevent main-thread priority inversions and hard runtime crashes. ## Strict Guidelines - Engineers MUST ALWAYS define TurboModule specifications using strictly serializable Codegen-compatible primitives and Promisified methods for off-thread operations. - Engineers MUST NOT allow native TurboModule bridges to capture raw `jsi::Runtime` pointers or JSI HostObject instances into asynchronous background thread blocks or dispatch queues. - Native implementations MUST unpack JSI payloads into native C++ structs (Plain Old Data) on the JS thread BEFORE dispatching background processing. - Background worker threads MUST NEVER allocate `jsi::String`, `jsi::Object`, or `jsi::ArrayBuffer` directly; all JSI object allocations MUST occur inside `CallInvoker::invokeAsync` on the target JS thread. - Components NEVER synchronously wait on worker threads via JSI synchronous getters (`get` HostObject hooks) when doing non-trivial native allocations, preventing UI thread priority inversion. ## Bad vs Good Implementations ### Bridgeless TurboModule Async Contract Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Synchronous HostObject access in Bridgeless React Native binds the C++ JSI instance to the JS thread while underlying background tasks contend for locks. This blocks the main thread scheduler, leading to priority inversion, thread starving, and fatal runtime crashes if JSI objects are dereferenced concurrently. ```typescript import { TurboModule, TurboModuleRegistry } from 'react-native'; // ANTI-PATTERN: Exposing synchronous JSI HostObject handles for heavy off-thread operations. // In Bridgeless RN 0.78, synchronous HostObject access forces the JS runtime // to wait on native locks, causing UI/JS thread priority inversion and JSI race conditions. export interface Spec extends TurboModule { // Bad: Synchronous accessor returning a stateful C++ HostObject reference getDirectNativeHandle(): { processChunkSync(data: string): string; }; // Bad: Raw synchronous execution across thread boundaries executeHeavyNativeTask(payload: string): string; } export const NativeDataPipeline = TurboModuleRegistry.get<Spec>('DataPipelineModule'); export function processDataUnsafe(rawContent: string): string | null { if (!NativeDataPipeline) return null; // Invariant Violation: Invoking sync method that locks worker threads from JS thread const handle = NativeDataPipeline.getDirectNativeHandle(); return handle.processChunkSync(rawContent); } ``` #### Production Standard (Correct) > **Standard**: The good pattern enforces strict async decoupling at the Codegen boundary. Native C++ implementations unbox the string payload into standard std::string values before spawning background thread work, allocating JSI responses solely when CallInvoker yields back to the JS thread. ```typescript import { TurboModule, TurboModuleRegistry } from 'react-native'; // PRODUCTION INVARIANT: Asynchronous, decoupled TurboModule Spec with pure serializable payloads. // In native C++, the module extracts strings/structs on the JS thread, moves raw values to std::thread, // and returns results strictly via Promise utilizing react::CallInvoker::invokeAsync. export interface Spec extends TurboModule { executeAsyncPipeline(payload: string): Promise<readonly string[]>; } export const NativeDataPipeline = TurboModuleRegistry.getEnforcing<Spec>( 'DataPipelineModule' ); export async function processDataSafe( rawContent: string ): Promise<readonly string[]> { if (!rawContent || rawContent.length === 0) { return []; } // Safe: Fully decoupled asynchronous invocation adhering to CallInvoker thread boundary try { return await NativeDataPipeline.executeAsyncPipeline(rawContent); } catch (error) { throw new Error( `[DataPipeline] Execution failed under Bridgeless isolation: ${ error instanceof Error ? error.message : String(error) }` ); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.78 Bridgeless TurboModule Thread Confinement & JSI Isolation

React Native 0.78 Bridgeless TurboModule Thread Confinement & JSI Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread confinement for JSI HostObjects and native TurboModule invocations under React Native 0.78 Bridgeless mode. Prohibits background threads from directly allocating, capturing, or dereferencing JS thread-bound jsi::Runtime structures, completely mitigating main-thread priority inversions, deadlocks, and memory 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: Retaining Raw JSI HostObjects or Capturing jsi::Runtime State Inside Background Queues 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 Raw JSI HostObjects or Capturing jsi::Runtime State Inside Background Queues	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 define TurboModule specifications using strictly serializable Codegen-compatible primitives and Promisified methods for off-thread operations.

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.