fix(ios-prebuild): do not relocate SocketRocket headers into ReactNativeHeaders

Declaring SocketRocket in DEPS_NAMESPACES (added to satisfy the deps
set-equality guard) relocated textual copies of its headers into
ReactNativeHeaders and thus into the flattened React-Core-prebuilt/Headers,
which sits on every pod's HEADER_SEARCH_PATHS. The real SocketRocket pod still
exists in consumer graphs and vends the same headers, so the copies collide:
duplicate @interface definitions when the SocketRocket pod compiles
(rn-tester, prebuilt + USE_FRAMEWORKS=dynamic), and a poisoned module graph in
use_frameworks/explicit-modules apps that don't compile SocketRocket sources
(Expo: ReactCodegen/RCTModulesConformingToProtocolsProvider.h "file not
found"). Bisect confirmed removing the SocketRocket dir flips red->green and
the R11 shims are not implicated.

Add DEPS_NAMESPACES_NOT_RELOCATED: such namespaces count as declared for the
set-equality guard (a genuinely new dep still fails closed), the include
classifier still recognizes them, and the headers gate now asserts they stay
ABSENT from the artifact. Note: no CI lane covers prebuilt + use_frameworks
(the dynamic-frameworks lane builds from source), which is why CI stayed
green.

Author: chrfalch

packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md

@@ -356,7 +356,9 @@ These classes previously failed late (consumer CI lane) or not at all; the gate
 Proof the gate earns its keep — its FIRST run found two real shipping defects:
 the dual-identity redefinitions that became R11, and an undeclared
 `SocketRocket` namespace in the deps artifact (caught by the set-equality guard
-the moment it was added).
+the moment it was added). SocketRocket is deliberately NOT relocated
+(`DEPS_NAMESPACES_NOT_RELOCATED`): the real pod vends it, and textual copies
+collide with it under `use_frameworks` — the gate asserts its absence.
 
 ### D. Remaining silent gaps — allowlist maintenance (by design)
 

packages/react-native/scripts/ios-prebuild/headers-compose.js

@@ -20,6 +20,7 @@
 const {computeInventory} = require('./headers-inventory');
 const {
   DEPS_NAMESPACES,
+  DEPS_NAMESPACES_NOT_RELOCATED,
   planFromInventory,
   renderNamespaceModuleMap,
   renderReactModuleMap,
@@ -189,22 +190,24 @@ function buildReactNativeHeadersXcframework(
     execSync(`/bin/cp -Rc "${src}" "${path.join(stage, ns)}"`);
   }
   // Set equality with the deps artifact: a namespace dir present in the
-  // artifact but NOT declared in DEPS_NAMESPACES means a new third-party dep
-  // was added upstream and would silently not be relocated — consumers'
-  // `<newdep/...>` includes would break. Declare it once in headers-spec.js
-  // (the include classifier derives from the same list).
+  // artifact but neither declared for relocation (DEPS_NAMESPACES) nor
+  // explicitly excluded (DEPS_NAMESPACES_NOT_RELOCATED — namespaces a real
+  // consumer pod vends itself, e.g. SocketRocket) means a new third-party dep
+  // was added upstream — fail closed so a decision is made deliberately.
   const foundDepsDirs = fs
     .readdirSync(depsHeaders, {withFileTypes: true})
     .filter(e => e.isDirectory())
     .map(e => String(e.name));
   const undeclared = foundDepsDirs.filter(
-    d => !plan.depsNamespaces.includes(d),
+    d =>
+      !plan.depsNamespaces.includes(d) &&
+      !DEPS_NAMESPACES_NOT_RELOCATED.includes(d),
   );
   if (undeclared.length > 0) {
     throw new Error(
       `headers-compose: deps artifact ships undeclared namespace(s): ` +
-        `${undeclared.join(', ')}. Add them to DEPS_NAMESPACES in ` +
-        `headers-spec.js so they are relocated into ReactNativeHeaders.`,
+        `${undeclared.join(', ')}. Add them to DEPS_NAMESPACES (relocated) or ` +
+        `DEPS_NAMESPACES_NOT_RELOCATED (vended by a real pod) in headers-spec.js.`,
     );
   }
   // Hermes public headers (separate source from the deps namespaces — they

packages/react-native/scripts/ios-prebuild/headers-inventory.js

@@ -31,7 +31,10 @@
 
 const {getHeaderFilesFromPodspecs} = require('./headers');
 // headers-spec.js requires only fs/path, so this cannot cycle.
-const {DEPS_NAMESPACES} = require('./headers-spec');
+const {
+  DEPS_NAMESPACES,
+  DEPS_NAMESPACES_NOT_RELOCATED,
+} = require('./headers-spec');
 const fs = require('fs');
 const path = require('path');
 
@@ -77,7 +80,10 @@ type HeaderEntry = {
 // of truth: the spec's DEPS_NAMESPACES (the namespaces relocated into
 // ReactNativeHeaders) — a new third-party dep is declared ONCE and both the
 // include classifier and the compose step follow.
-const THIRD_PARTY_LIBS /*: Set<string> */ = new Set(DEPS_NAMESPACES);
+const THIRD_PARTY_LIBS /*: Set<string> */ = new Set([
+  ...DEPS_NAMESPACES,
+  ...DEPS_NAMESPACES_NOT_RELOCATED,
+]);
 
 // Apple SDK / platform include roots (first path segment). Includes resolving
 // here are "system": always modular or always available, never our problem.

packages/react-native/scripts/ios-prebuild/headers-spec.js

@@ -120,9 +120,20 @@ const DEPS_NAMESPACES = [
   'fmt',
   'double-conversion',
   'fast_float',
-  'SocketRocket',
 ];
 
+// Namespaces the deps artifact ships but which must NOT be relocated into
+// ReactNativeHeaders: a REAL CocoaPods pod of the same name exists in consumer
+// graphs and vends these headers itself (with its own module). Relocating
+// textual copies puts them on every pod's HEADER_SEARCH_PATHS via the
+// flattened React-Core-prebuilt/Headers and collides with the pod's own
+// headers — duplicate @interface definitions compiling the SocketRocket pod,
+// and a poisoned module graph in use_frameworks/explicit-modules apps
+// (Expo regression, 2026-07-03). The compose set-equality guard treats these
+// as declared (so only genuinely NEW namespaces fail closed), and the headers
+// gate asserts they stay ABSENT from the artifact.
+const DEPS_NAMESPACES_NOT_RELOCATED = ['SocketRocket'];
+
 // R4/R5 umbrella exclusion: C extern-inline definitions.
 const EXTERN_INLINE_RE /*: RegExp */ =
   /\b(RCT_EXTERN\s+inline|extern\s+inline)\b/;
@@ -458,6 +469,7 @@ function renderNamespaceModuleMap(
 
 module.exports = {
   planFromInventory,
+  DEPS_NAMESPACES_NOT_RELOCATED,
   renderReactModuleMap,
   renderUmbrellaHeader,
   renderNamespaceModuleMap,

packages/react-native/scripts/ios-prebuild/headers-verify.js

@@ -39,6 +39,7 @@
 
 const {computeInventory} = require('./headers-inventory');
 const {
+  DEPS_NAMESPACES_NOT_RELOCATED,
   planFromInventory,
   renderNamespaceModuleMap,
   renderReactModuleMap,
@@ -231,6 +232,16 @@ function verifyStructural(
       throw new Error(`deps namespace missing from artifact: ${ns}`);
     }
   }
+  // Excluded namespaces must stay ABSENT: relocating them collides with the
+  // real pod's own headers (SocketRocket / Expo use_frameworks regression).
+  for (const ns of DEPS_NAMESPACES_NOT_RELOCATED) {
+    if (fs.existsSync(path.join(rnhHeaders, ns))) {
+      throw new Error(
+        `excluded deps namespace '${ns}' found in the artifact — it must NOT ` +
+          `be relocated (a real pod vends it; textual copies collide).`,
+      );
+    }
+  }
   log('structural: OK (module maps + umbrellas byte-match the spec render).');
   return {reactSlice, rnhHeaders};
 }