React Native Bridgeless JSI Thread-Safe State Synchronization & Lifecycle Guardrail

--- description: React Native Bridgeless JSI Thread-Safe State Synchronization & Lifecycle Guardrail - Enforces deterministic, thread-safe memory management and lifecycle unbinding between the Hermes JS runtime and native C++ TurboModules in Bridgeless mode. Guarantees atomic teardown of JSI HostObjects and HostFunctions to eliminate dangling raw pointers (use-after-free) and race conditions during rapid component unmount cycles across concurrent execution threads. globs: src/**/*.{ts,tsx}, ios/**/*.{h,m,mm,cpp}, android/**/*.{h,cpp}, cpp/**/*.{h,cpp} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rn-bridgeless-jsi-state-sync-standard" --- # React Native Bridgeless JSI Thread-Safe State Synchronization & Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Asynchronous or Unprotected Teardown of Native C++ JSI References in Bridgeless Runtimes ## System Constraints You are a Principal Mobile Architect enforcing React Native Bridgeless JSI Native State Synchronization Standards. Mandate atomic state invalidation, strict use of std::enable_shared_from_this with weak references for JSI HostObjects, and deterministic cleanup in React component lifecycles to prevent SEGFAULT (EXC_BAD_ACCESS/SIGSEGV) crashes during rapid screen unmount and remount sequences. ## Strict Guidelines - Engineers MUST ALWAYS invalidate C++ TurboModule listener registries and state holders using atomic boolean flags (std::atomic<bool>) before releasing memory references. - Engineers MUST capture weak references (std::weak_ptr) inside JSI HostFunction lambdas dispatched across the Hermes thread and Platform Main/UI threads. - Engineers MUST NOT retain bare, unmanaged raw C++ pointers or naked `jsi::Value` references across native asynchronous queue dispatches. - Code SHOULD enforce RAII handles on the TypeScript layer via explicit cleanup in `useEffect` or `useLayoutEffect` returns to signal native unbind before Hermes garbage collection occurs. - Components NEVER trigger synchronous JSI state mutations after an unmount signal has been queued or processed. ## Bad vs Good Implementations ### Synchronous JSI Teardown vs Unchecked Native Invocation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to explicitly unbind the native listener leaves dangling JSI callbacks inside the native C++ TurboModule. When Hermes collects the callback while the native thread pushes updates, a fatal SIGSEGV/EXC_BAD_ACCESS crash occurs. ```typescript import React, { useEffect } from 'react'; import { NativeStateModule } from './NativeStateModule'; export const DataFeedScreen: React.FC<{ feedId: string }> = ({ feedId }) => { useEffect(() => { // ANTI-PATTERN: Native registration without explicit unbind or invalidation token. // During rapid unmount/remount, Hermes destroys this callback while native C++ threads // still dispatch raw JSI invocations, triggering a fatal EXC_BAD_ACCESS. NativeStateModule.bindFeedListener(feedId, (data: unknown) => { console.log('Received data:', data); }); }, [feedId]); return null; }; ``` #### Production Standard (Correct) > **Standard**: The cleanup function deterministically releases the native listener handle via synchronous JSI execution upon unmount, preventing downstream native worker threads from dereferencing an invalid Hermes JS callback pointer. ```typescript import React, { useEffect } from 'react'; import { NativeStateModule } from './NativeStateModule'; export const DataFeedScreen: React.FC<{ feedId: string }> = ({ feedId }) => { useEffect(() => { // PRODUCTION FIX: Generate unique registration token and synchronously unbind // with RAII semantics on unmount to halt native thread dispatches immediately. const handleId = NativeStateModule.bindFeedListener(feedId, (data: unknown) => { console.log('Received data safely:', data); }); return () => { NativeStateModule.unbindFeedListener(handleId); }; }, [feedId]); return null; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native Bridgeless JSI Thread-Safe State Synchronization & Lifecycle Guardrail

React Native Bridgeless JSI Thread-Safe State Synchronization & Lifecycle Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, thread-safe memory management and lifecycle unbinding between the Hermes JS runtime and native C++ TurboModules in Bridgeless mode. Guarantees atomic teardown of JSI HostObjects and HostFunctions to eliminate dangling raw pointers (use-after-free) and race conditions during rapid component unmount cycles across concurrent execution threads. 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: Asynchronous or Unprotected Teardown of Native C++ JSI References in Bridgeless 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	Asynchronous or Unprotected Teardown of Native C++ JSI References in Bridgeless 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 invalidate C++ TurboModule listener registries and state holders using atomic boolean flags (std

Engineers MUST ALWAYS invalidate C++ TurboModule listener registries and state holders using atomic boolean flags (std::atomic<bool>) before releasing memory references.

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.