feat(firestore)!: migrate firestore to TurboModules

BREAKING CHANGE: Firestore native bridge requires New Architecture.
Legacy NativeModules bridge removed; four Codegen TurboModule specs
(NativeRNFBTurboFirestore{,Collection,Document,Transaction}) with
committed generated artifacts, Android/iOS turbo shells, and JS wiring.

Author: mikehardy

jest.setup.ts

@@ -284,7 +284,8 @@ jest.doMock('react-native', () => {
           ),
           getServerTime: jest.fn((_appName: any, _customUrl: any) => Promise.resolve(Date.now())),
         },
-        RNFBFirestoreModule: {
+        NativeRNFBTurboFirestore: {
+          setLogLevel: jest.fn(),
           loadBundle: jest.fn(() =>
             Promise.resolve({
               taskState: 'Success',
@@ -303,9 +304,20 @@ jest.doMock('react-native', () => {
           settings: jest.fn(),
           addSnapshotsInSync: jest.fn(),
           removeSnapshotsInSync: jest.fn(),
+          persistenceCacheIndexManager: jest.fn(),
+        },
+        NativeRNFBTurboFirestoreCollection: {
           collectionOffSnapshot: jest.fn(),
           namedQueryOnSnapshot: jest.fn(),
           collectionOnSnapshot: jest.fn(),
+          namedQueryGet: jest.fn(() =>
+            Promise.resolve({
+              source: 'cache',
+              changes: [],
+              documents: [],
+              metadata: {},
+            }),
+          ),
           collectionGet: jest.fn(() =>
             Promise.resolve({
               source: 'cache',
@@ -315,6 +327,15 @@ jest.doMock('react-native', () => {
             }),
           ),
           collectionCount: jest.fn(() => Promise.resolve({ count: 0 })),
+          aggregateQuery: jest.fn(() => Promise.resolve({})),
+          pipelineExecute: jest.fn(() =>
+            Promise.resolve({
+              results: [],
+              executionTime: Date.now(),
+            }),
+          ),
+        },
+        NativeRNFBTurboFirestoreDocument: {
           documentDelete: jest.fn(() => Promise.resolve()),
           documentOffSnapshot: jest.fn(),
           documentOnSnapshot: jest.fn(),
@@ -328,11 +349,20 @@ jest.doMock('react-native', () => {
           ),
           documentSet: jest.fn(() => Promise.resolve()),
           documentUpdate: jest.fn(() => Promise.resolve()),
-          persistenceCacheIndexManager: jest.fn(),
           documentBatch: jest.fn(),
+        },
+        NativeRNFBTurboFirestoreTransaction: {
           transactionApplyBuffer: jest.fn(),
           transactionBegin: jest.fn(),
           transactionDispose: jest.fn(),
+          transactionGetDocument: jest.fn(() =>
+            Promise.resolve({
+              data: {},
+              metadata: {},
+              path: 'firestore/document',
+              exists: true,
+            }),
+          ),
         },
         RNFBFiamModule: {
           isMessagesDisplaySuppressed: false,

okf-bundle/new-architecture/architecture-decisions.md

@@ -132,7 +132,7 @@ Multiple specs/modules in one package are **merged flat** into a single resolved
 
 ## NewArch-AD-12 — One commit per package — **Accepted**
 
-Convert a whole package (all its legacy modules → all its specs) in one `implementation → independent-review → commit` loop; land it as one `feat(<pkg>): migrate <pkg> to TurboModules`. Multiple specs ≠ multiple commits — they share `codegenConfig`, generated artifacts, podspec/gradle guards, and JS wiring that only build and pass e2e together.
+Convert a whole package (all its legacy modules → all its specs) in one `implementation → independent-review → commit` loop; land it as one `feat(<pkg>)!: migrate <pkg> to TurboModules` (breaking: New Architecture required). Multiple specs ≠ multiple commits — they share `codegenConfig`, generated artifacts, podspec/gradle guards, and JS wiring that only build and pass e2e together.
 
 ---
 
@@ -263,7 +263,7 @@ Two resolution surfaces exist and must be used deliberately:
 | E5 | [`UtilsStatics.ts`](../../../packages/app/lib/utils/UtilsStatics.ts) `FilePath` getter | `NativeRNFBTurboUtils` | **Phase 0 fix** | Reads path **constants** synchronously from the utils host without a `FirebaseModule` instance (static getter on `Utils.Statics`). Raw was acceptable pre-turbo; under [NewArch-AD-15](#newarch-ad-15--constant-memoization-scope-static-only--accepted) migrate to a dedicated wrapped utils accessor (or memoized static read via resolver) so constants are not rebuilt per access. Turbo name is already correct. | Fix in Phase 0 re-implementation. |
 | E6 | [`messaging/lib/index.ts`](../../../packages/messaging/lib/index.ts) `isSupported()` | ~~`RNFBUtilsModule`~~ → `NativeRNFBTurboUtils` | **Phase 0 fix (bug)** | Cross-package read of Play Services availability. Was using **legacy module name** (returns `undefined` under turbo-only) and a **dynamic constant** (`androidPlayServices`) that can go stale. Must use turbo name + **dynamic method** `androidGetPlayServicesStatus()` per [NewArch-AD-15](#newarch-ad-15--constant-memoization-scope-static-only--accepted). | **Must-fix** in Phase 0. |
 | E7 | [`app/lib/modular.ts`](../../../packages/app/lib/modular.ts) `metaGetAll`, `jsonGetAll`, `preferences*` | `NativeRNFBTurboApp` | **Not an exception — migrate** | No policy reason for raw; these are app-module method calls with no arg-prepend skip. Should use **`getAppModule()`** (wrapped) for error mapping consistency. Listed here so gap-analysis catches them. | Migrate to `getAppModule()` in Phase 0. |
-| E8 | [`FirestoreStatics.ts`](../../../packages/firestore/lib/FirestoreStatics.ts) `setLogLevel` | `RNFBFirestoreModule` | **Deferred — Phase 1** | Cross-package static helper bypasses `FirebaseModule`/`getNativeModule`. Acceptable until firestore migrates; then switch to turbo name + wrapped surface (or firestore-owned static that uses `getNativeModule`). | Fix when `firestore` migrates. |
+| E8 | [`FirestoreStatics.ts`](../../../packages/firestore/lib/FirestoreStatics.ts) `setLogLevel` | `NativeRNFBTurboFirestore` | **Phase 1 fix** | Cross-package static helper bypasses `FirebaseModule`/`getNativeModule`. Uses turbo main host via [`getStaticFirestoreMainModule()`](../../../packages/firestore/lib/internal/staticNativeModule.ts) (NewArch-AD-18 E8). Raw access retained — no wrapped surface for static helpers. | Done — firestore Phase 1. |
 | E9 | [`DatabaseSyncTree.ts`](../../../packages/database/lib/DatabaseSyncTree.ts) `native` getter | `RNFBDatabaseQueryModule` | **Deferred — Phase 4** | Internal sync listener tree calls query module directly for low-latency sync ops, bypassing the merged multi-module surface. Acceptable until database migrates; then turbo name + evaluate whether wrapped merge surface suffices. | Fix when `database` migrates. |
 | E10 | [`phone-number-verification/lib/index.ts`](../../../packages/phone-number-verification/lib/index.ts) `getNativeModule()` | `RNFBPnvModule` | **Deferred — Phase 5** | Package bypasses `createModuleNamespace` by design ([workflow § gotchas](turbomodule-implementation-workflow.md#gotchas)). Direct resolver is intentional; update to `NativeRNFBTurboPnv` on migration. | Fix when `phone-number-verification` migrates. |
 

okf-bundle/new-architecture/migration-work-queue.md

@@ -8,7 +8,7 @@ timestamp: 2026-06-26T00:00:00Z
 
 # TurboModule migration — work queue
 
-> **IN PROGRESS (2026-06-30):** Phase **0** (`app` TurboModules) — **done**. Phase **0.1** (`app` compare:types) — **commit** pending. Decisions: [architecture-decisions.md](architecture-decisions.md).
+> **IN PROGRESS (2026-06-30):** Phase **2** easy wins — **queued**. Phases **0** / **0.1** (`app`) and Phase **1** (`firestore`) — **done**. Decisions: [architecture-decisions.md](architecture-decisions.md).
 > **Goal/order:** app foundation → hard probe → easy wins → remaining complex → sync conversion → coordinated break → cleanup (events, shared-state encapsulation). Decisions: [architecture-decisions.md](architecture-decisions.md). Links: [implementation workflow](turbomodule-implementation-workflow.md), [change authoring](../testing/change-authoring-workflow.md), [functions reference](../../../packages/functions/) ([PR #8603](https://github.com/invertase/react-native-firebase/pull/8603)).
 
 Ephemeral tracker; see [OKF policy](../documentation-policy.md).
@@ -161,8 +161,8 @@ Pick **one** of `firestore` or `auth` in Phase 1 (firestore = multi-module + pip
 | Phase | Focus | Status | Packages |
 |-------|--------|--------|----------|
 | **0** | App foundation + unified resolver | **done** | `app` |
-| **0.1** | App modular type parity (`compare:types`) | **commit pending** | `app` — [§ Phase 0.1](#phase-01-app-comparetypes) |
-| **1** | Hard probe | queued | `firestore` **or** `auth` — pick one |
+| **0.1** | App modular type parity (`compare:types`) | **done** | `app` — [§ Phase 0.1](#phase-01-app-comparetypes) |
+| **1** | Hard probe | **done** | `firestore` (multi-module + pipelines; NewArch-AD-14a composite) |
 | **2** | Easy wins | queued | `installations`, `perf`, `in-app-messaging`, `app-distribution`, `ml` |
 | **3** | Moderate | queued | `app-check`, `remote-config`, `analytics`, `crashlytics`, `storage` |
 | **4** | Remaining complex | queued | other Tier A/B + `messaging`, `database` |
@@ -267,11 +267,13 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 
 ## Current snapshot
 
-**Label:** `phase-0.1-compare-types`; **harness:** n/a (types-only)
+**Label:** `phase-2-easy-wins`; **harness:** n/a
 
-**Next item:** Phase **0.1** `app` compare:types — **commit**
+**Next item:** Phase **2** — pick first Tier D package (`installations`, `perf`, `in-app-messaging`, `app-distribution`, or `ml`)
 
-**Current gates:** Phase 0 all **closed** · Phase 0.1 `review_gate` **closed** · `commit_gate` **open**
+**Current gates:** Phase 0 / 0.1 / 1 all **closed**
+
+**Package pick (Phase 1):** `firestore` over `auth` — first multi-module package (×4 specs), exercises `pipelineExecute` + NewArch-AD-14a routing composite Proxy; defers largest single-spec (`auth` ×59) to Phase 4.
 
 **Arbiter gate:**
 
@@ -280,7 +282,8 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 |------|------|----------------------|---------------|---------------|------------------|-------------------|------------------|-------|
 | Design review | DR | n/a | n/a | n/a | done | none | none | ✅ Adversarial review complete. |
 | Phase 0 `app` TurboModules | P0 | **closed** | **closed** | **closed** | done | `full` | `feat(app): migrate app modules to TurboModules incl general migration infra` | Committed 2026-06-30. |
-| Phase 0.1 `app` compare:types | P0.1 | **closed** | **closed** | **open** | `commit` | `none` | `test(app): add app module type comparison config` | 25 deltas documented; `SDK_VERSION` typed `string`; compare:types green for `app`. |
+| Phase 0.1 `app` compare:types | P0.1 | **closed** | **closed** | **closed** | done | `none` | `test(app): add app module type comparison config` | Committed 2026-06-30. 25 deltas documented; compare:types green for `app`. |
+| Phase 1 `firestore` TurboModules | P1 | **closed** | **closed** | **closed** | done | `area-focused` | `feat(firestore)!: migrate firestore to TurboModules` | Committed 2026-06-30. 4 specs; area e2e 732 pass/7 pending iOS+Android; jest 285/285; compare:types ✓. |
 
 ---
 

okf-bundle/new-architecture/turbomodule-implementation-workflow.md

@@ -44,7 +44,7 @@ In addition to [change authoring gates](../testing/change-authoring-workflow.md#
 
 One TurboModule spec **per legacy native module** — do not consolidate the *specs* in the first pass (database ×5, firestore ×4); each legacy module keeps its own `NativeRNFBTurbo*` spec and shell.
 
-**Commit granularity: one commit per package, not per spec.** Splitting a multi-module package across several commits adds little value and is often impractical — the specs share `codegenConfig`, generated artifacts, podspec/`build.gradle` guards, and JS wiring that only compile and pass e2e together. Convert the whole package (all its legacy modules → all its specs) in a single `implementation` → `independent-review` → `commit` loop and land it as **one** `feat(<pkg>): migrate <pkg> to TurboModules` commit. Per-spec commits are only warranted if a single legacy module is genuinely independently shippable and reviewable, which is rare. Multiple specs ≠ multiple commits.
+**Commit granularity: one commit per package, not per spec.** Splitting a multi-module package across several commits adds little value and is often impractical — the specs share `codegenConfig`, generated artifacts, podspec/`build.gradle` guards, and JS wiring that only compile and pass e2e together. Convert the whole package (all its legacy modules → all its specs) in a single `implementation` → `independent-review` → `commit` loop and land it as **one** `feat(<pkg>)!: migrate <pkg> to TurboModules` commit (breaking: New Architecture required). Per-spec commits are only warranted if a single legacy module is genuinely independently shippable and reviewable, which is rare. Multiple specs ≠ multiple commits.
 
 ### Multi-spec packages (`app` precedent)
 
@@ -164,9 +164,11 @@ Per package (or per phase batch), same commit when user-facing:
 ## TurboModule `commit`
 
 ```text
-feat(<pkg>): migrate <module-or-package> to TurboModules
+feat(<pkg>)!: migrate <module-or-package> to TurboModules
 ```
 
+Breaking change (`!`): TurboModule migration requires New Architecture; legacy bridge is removed per package.
+
 **Never stage:** `tests/harness.overrides.js`, any `.only`, temporary sub-suite edits in `tests/app.js`.
 
 ## Gotchas

packages/firestore/RNFBFirestore.podspec

@@ -28,15 +28,28 @@ Pod::Spec.new do |s|
   s.macos.deployment_target = firebase_macos_target
   s.tvos.deployment_target = firebase_tvos_target
   s.swift_version       = '5.10'
-  s.source_files        = 'ios/**/*.{h,m,mm,swift}'
+  s.source_files        = 'ios/**/*.{h,m,mm,cpp,swift}'
+  s.private_header_files = [
+    'ios/RNFBFirestore/RNFBFirestoreModule.h',
+    'ios/RNFBFirestore/RNFBFirestoreCollectionModule.h',
+    'ios/RNFBFirestore/RNFBFirestoreDocumentModule.h',
+    'ios/RNFBFirestore/RNFBFirestoreTransactionModule.h',
+    'ios/generated/**/*.h',
+  ]
+  s.exclude_files       = 'ios/generated/RCTThirdPartyComponentsProvider.*', 'ios/generated/RCTAppDependencyProvider.*', 'ios/generated/RCTModuleProviders.*', 'ios/generated/RCTModulesConformingToProtocolsProvider.*', 'ios/generated/RCTUnstableModulesRequiringMainQueueSetupProvider.*'
+
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ios/generated/RNFBFirestoreTurboModules\" \"$(PODS_TARGET_SRCROOT)/ios/generated\"",
+  }
 
   s.dependency          'RNFBApp'
 
-  # React Native dependencies
-  if defined?(install_modules_dependencies()) != nil
-    install_modules_dependencies(s);
-  else
-    s.dependency "React-Core"
+  install_modules_dependencies(s);
+
+  # Fail fast for old architecture users, but safely in case the variable goes away
+  # completely in future react-native versions
+  if defined?(ENV["RCT_NEW_ARCH_ENABLED"]) != nil && (ENV["RCT_NEW_ARCH_ENABLED"] == '0')
+     raise "#{s.name} requires New Architecture. Enable New Architecture to use this module"
   end
 
   if defined?($FirebaseSDKVersion)

packages/firestore/__tests__/nativeModuleContract.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { TurboModuleRegistry } from 'react-native';
+import type { ModuleConfig } from '@react-native-firebase/app/dist/module/internal';
+import FirebaseModule from '@react-native-firebase/app/dist/module/internal/FirebaseModule';
+import { getNativeModule } from '@react-native-firebase/app/dist/module/internal/registry/nativeModule';
+import type { WrappedNativeModule } from '@react-native-firebase/app/dist/module/internal/NativeModules';
+
+const MAIN_METHODS = [
+  'setLogLevel',
+  'loadBundle',
+  'clearPersistence',
+  'waitForPendingWrites',
+  'disableNetwork',
+  'enableNetwork',
+  'useEmulator',
+  'settings',
+  'terminate',
+  'persistenceCacheIndexManager',
+  'addSnapshotsInSync',
+  'removeSnapshotsInSync',
+] as const;
+
+const COLLECTION_METHODS = [
+  'namedQueryOnSnapshot',
+  'collectionOnSnapshot',
+  'collectionOffSnapshot',
+  'namedQueryGet',
+  'collectionCount',
+  'aggregateQuery',
+  'pipelineExecute',
+  'collectionGet',
+] as const;
+
+const DOCUMENT_METHODS = [
+  'documentOnSnapshot',
+  'documentOffSnapshot',
+  'documentGet',
+  'documentDelete',
+  'documentSet',
+  'documentUpdate',
+  'documentBatch',
+] as const;
+
+const TRANSACTION_METHODS = [
+  'transactionBegin',
+  'transactionGetDocument',
+  'transactionDispose',
+  'transactionApplyBuffer',
+] as const;
+
+const ALL_SPEC_METHODS = [
+  ...MAIN_METHODS,
+  ...COLLECTION_METHODS,
+  ...DOCUMENT_METHODS,
+  ...TRANSACTION_METHODS,
+];
+
+function createTurboModuleFixture(
+  methods: Record<string, jest.Mock>,
+  constants: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const proto = Object.create(Object.prototype, {
+    getConstants: {
+      value: () => constants,
+      enumerable: true,
+    },
+  });
+
+  for (const [name, fn] of Object.entries(methods)) {
+    Object.defineProperty(proto, name, {
+      value: fn,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
+  return Object.create(proto);
+}
+
+describe('TurboModule wrapper contract (NewArch-AD-17.1)', function () {
+  it('asserts merged Firestore spec method names are unique (NewArch-AD-11)', function () {
+    expect(new Set(ALL_SPEC_METHODS).size).toBe(ALL_SPEC_METHODS.length);
+    expect(ALL_SPEC_METHODS).toHaveLength(31);
+  });
+
+  it('routes methods through a 4-host merge composite Proxy (NewArch-AD-14a)', function () {
+    const mainMethod = jest.fn(() => 'main');
+    const collectionMethod = jest.fn(() => 'collection');
+    const documentMethod = jest.fn(() => 'document');
+    const transactionMethod = jest.fn(() => 'transaction');
+
+    const hostMain = createTurboModuleFixture({ setLogLevel: mainMethod });
+    const hostCollection = createTurboModuleFixture({ collectionGet: collectionMethod });
+    const hostDocument = createTurboModuleFixture({ documentGet: documentMethod });
+    const hostTransaction = createTurboModuleFixture({ transactionBegin: transactionMethod });
+
+    jest
+      .mocked(TurboModuleRegistry.get)
+      .mockReturnValueOnce(hostMain)
+      .mockReturnValueOnce(hostCollection)
+      .mockReturnValueOnce(hostDocument)
+      .mockReturnValueOnce(hostTransaction);
+
+    const config: ModuleConfig = {
+      namespace: 'firestoreContract',
+      nativeModuleName: [
+        'NativeRNFBTurboFirestore',
+        'NativeRNFBTurboFirestoreCollection',
+        'NativeRNFBTurboFirestoreDocument',
+        'NativeRNFBTurboFirestoreTransaction',
+      ],
+      nativeEvents: false,
+      hasMultiAppSupport: true,
+      hasCustomUrlOrRegionSupport: true,
+      turboModule: true,
+    };
+
+    class MergeModule extends FirebaseModule<any> {
+      constructor() {
+        super({ name: '[DEFAULT]' } as any, config);
+      }
+    }
+
+    const wrapped = getNativeModule(new MergeModule()) as WrappedNativeModule & {
+      setLogLevel: () => string;
+      collectionGet: () => string;
+      documentGet: () => string;
+      transactionBegin: () => string;
+    };
+
+    expect(wrapped.setLogLevel()).toBe('main');
+    expect(wrapped.collectionGet()).toBe('collection');
+    expect(wrapped.documentGet()).toBe('document');
+    expect(wrapped.transactionBegin()).toBe('transaction');
+    expect(mainMethod).toHaveBeenCalledTimes(1);
+    expect(collectionMethod).toHaveBeenCalledTimes(1);
+    expect(documentMethod).toHaveBeenCalledTimes(1);
+    expect(transactionMethod).toHaveBeenCalledTimes(1);
+    expect(Object.keys(wrapped).sort()).toEqual([
+      'collectionGet',
+      'documentGet',
+      'setLogLevel',
+      'transactionBegin',
+    ]);
+  });
+});