wip(firestore): phase N iOS operand coercion and stage coercion e2e

Author: mikehardy

.github/workflows/scripts/resource-monitor.sh

@@ -8,7 +8,7 @@ timestamp: 2026-06-25T12:00:00Z
 
 # Pipeline coverage and parity — work queue
 
-> **IN PROGRESS:** **N** queued — iOS stage coercion (~293 missed).
+> **IN PROGRESS:** **N** — `implementation` (**one subagent**, serial e2e only).
 > **Goal/order:** platform parity first; then TS/native coverage toward intractable limits. Links: [parity](pipeline-platform-parity.md), [SDK audit](pipeline-sdk-support-audit.md), [coverage](../../testing/coverage-design.md), [e2e](../../testing/running-e2e.md), [architecture](pipelines.md).
 
 ---
@@ -63,7 +63,7 @@ Gate prerequisites before any `:test-cover` ([host rule](../../testing/change-au
 | **K**  | TS `pipeline_runtime` + `expressions` | **✅** | Jest alias/normalization batch; expressions e2e receiver probe |
 | **L**  | Android parsed-aggregate tail         | **✅** | expression-arg `arrayAgg`/`arrayAggDistinct` e2e; parsed tail 258/408 |
 | **M**  | Android exit frames + receiver chains | **✅** | 3 e2e; NodeBuilder 75.03%; exit −29 missed |
-| **N**  | iOS stage coercion                    | queued                    | ~293 missed; operand tail *(was old L)*                                                                                                            |
+| **N**  | iOS stage coercion                    | **in progress** | `implementation`; operand tail L919–1006 |
 | **O**  | Android Executor remainder            | queued                    | sub-60% after E *(was old M)*                                                                                                                      |
 | **P**  | Jest-only TS paths                    | queued                    | validation branches *(was old N)*                                                                                                                  |
 | **Q**  | Intractability audit                  | queued                    | measured caps per file *(was old O)*                                                                                                               |
@@ -76,12 +76,13 @@ Gate prerequisites before any `:test-cover` ([host rule](../../testing/change-au
 
 ## Current snapshot
 
-**Label:** `n-queued`; **harness:** full test app (committed)
+**Label:** `n-impl-serial-single`; **harness:** HEAD (subagent applies Pattern A locally)
 
-**Next item:** **N** — iOS stage coercion (~293 missed).
+**Next item:** **N** — one subagent: prepare → macOS `:test-cover` → iOS `:test-cover` (serial).
 
 | **L** parsed-aggregate tail | `test(firestore): cover pipeline aggregate expression argument lowering on Android` | **closed** | **closed** | **closed** | — | — | — | `arrayAgg`/`arrayAggDistinct` expr args |
 | **M** exit/receiver/vector | `test(firestore): cover pipeline exit frame and receiver expression lowering on Android` | **closed** | **closed** | **closed** | — | — | — | 3 e2e; NodeBuilder 75.03%; exit 73→44 missed |
+| **N** iOS stage coercion | — | open | open | open | `implementation` | `unit-focused` | ios | WIP fix: web `pipeline_node_builder.ts` + iOS Swift operand coercion; serial re-val pending |
 
 | **J2** P-005 `integerLiteral` | `fix(firestore, android): align pipeline integerLiteral constant lowering with iOS` | **closed** | **closed** | **closed** | — | — | — | P-005 → Resolved; CFBoolean deferral accepted |
 | **J3** P-010 stage option expressions | `fix(firestore, android): align pipeline stage option expression fields with iOS` | **closed** | **closed** | **closed** | — | — | — | P-010 → Resolved |
@@ -306,7 +307,7 @@ Per [SDK audit §6](pipeline-sdk-support-audit.md): one function/commit; remove
 
 **Gate for Phase K+:** J0 complete + **J0b** committed + J1–J6 bridge commits + parity **Resolved** updated.
 
-**Current gates:** **N** queued. **L** and **M** complete.
+**Current gates:** **N** `implementation_gate` open. **L** and **M** complete.
 
 ---
 

okf-bundle/packages/firestore/pipeline-coverage-work-queue.md

@@ -3473,6 +3473,240 @@ describe('FirestorePipeline', function () {
       });
     });
 
+    describe('iOS NodeBuilder stage coercion and operand tail coverage', function () {
+      it('exercises stage option coercion for findNearest dot product and transform stages', async function () {
+        if (Platform.other) {
+          return;
+        }
+
+        const { execute, field, constant, add, countAll } = firestorePipelinesModular;
+        const { getFirestore, collection, doc, setDoc, vector } = firestoreModular;
+        const db = getFirestore(DATABASE_ID);
+        const coll = collection(
+          db,
+          `${COLLECTION}/${Utils.randString(12, '#aA')}/stage-coercion-options`,
+        );
+
+        await Promise.all([
+          setDoc(doc(coll, 'v1'), {
+            name: 'alpha',
+            region: 'EU',
+            score: 40,
+            embedding: vector([1.0, 0.0, 0.0]),
+          }),
+          setDoc(doc(coll, 'v2'), {
+            name: 'beta',
+            region: 'EU',
+            score: 70,
+            embedding: vector([0.0, 1.0, 0.0]),
+          }),
+          setDoc(doc(coll, 'v3'), {
+            name: 'gamma',
+            region: 'US',
+            score: 55,
+            embedding: vector([0.0, 0.0, 1.0]),
+          }),
+        ]);
+
+        const dotSnapshot = await execute(
+          db
+            .pipeline()
+            .collection(coll)
+            .findNearest({
+              field: 'embedding',
+              vectorValue: [1.0, 0.0, 0.0],
+              distanceMeasure: 'DOT_PRODUCT',
+              limit: 2,
+            })
+            .select('name'),
+        );
+
+        dotSnapshot.results.should.have.length(2);
+        dotSnapshot.results[0].data().name.should.equal('alpha');
+
+        const transformSnapshot = await execute(
+          db
+            .pipeline()
+            .collection(coll)
+            .where(field('region').equal('EU'))
+            .addFields(add(field('score'), constant(5)).as('scorePlusFive'))
+            .sort(field('scorePlusFive').descending(), field('name').ascending())
+            .offset(1)
+            .limit(1)
+            .select('name', 'scorePlusFive'),
+        );
+
+        transformSnapshot.results.should.have.length(1);
+        transformSnapshot.results[0].data().name.should.equal('alpha');
+        transformSnapshot.results[0].data().scorePlusFive.should.equal(45);
+
+        const groupedSnapshot = await execute(
+          db
+            .pipeline()
+            .collection(coll)
+            .aggregate({
+              accumulators: [countAll().as('rows')],
+              groups: [field('region').as('regionKey')],
+            })
+            .sort(field('regionKey').ascending()),
+        );
+
+        groupedSnapshot.results.should.have.length(2);
+        groupedSnapshot.results[0].data().regionKey.should.equal('EU');
+        groupedSnapshot.results[0].data().rows.should.equal(2);
+      });
+
+      it('covers remaining comparison and numeric operand rhs coercion tails', async function () {
+        const {
+          execute,
+          field,
+          subtract,
+          divide,
+          pow,
+          equal,
+          notEqual,
+          lessThanOrEqual,
+          greaterThanOrEqual,
+          greaterThan,
+          and,
+        } = firestorePipelinesModular;
+        const { getFirestore, collection, doc, setDoc } = firestoreModular;
+        const db = getFirestore(DATABASE_ID);
+        const docPath = `${COLLECTION}/${Utils.randString(12, '#aA')}`;
+
+        await setDoc(doc(db, docPath), {
+          base: 20,
+          divisor: 4,
+          exp: 3,
+          tag: 'alpha',
+          mirrorTag: 'alpha',
+          score: 42,
+          cap: '50',
+          status: 'active',
+        });
+
+        if (Platform.other) {
+          const macSnapshot = await execute(
+            db
+              .pipeline()
+              .documents([docPath])
+              .select(
+                subtract(field('base'), true).as('subTrue'),
+                divide(field('base'), false).as('divFalse'),
+                pow(field('exp'), true).as('powTrue'),
+                equal(field('tag'), field('mirrorTag')).as('tagsMatch'),
+                equal(field('tag'), 'alpha').as('tagStringRhs'),
+                lessThanOrEqual(field('score'), '50').as('scoreLteString'),
+              ),
+          );
+
+          macSnapshot.results.should.have.length(1);
+          const macData = macSnapshot.results[0].data();
+          macData.subTrue.should.equal(19);
+          macData.divFalse.should.equal(0);
+          macData.powTrue.should.equal(3);
+          macData.tagsMatch.should.equal(true);
+          macData.tagStringRhs.should.equal(true);
+          macData.scoreLteString.should.equal(true);
+          return;
+        }
+
+        const snapshot = await execute(
+          db
+            .pipeline()
+            .documents([docPath])
+            .select(
+              subtract(field('base'), true).as('subTrue'),
+              subtract(field('base'), '5').as('subString'),
+              divide(field('base'), field('divisor')).as('divField'),
+              pow(field('exp'), true).as('powTrue'),
+              equal(field('tag'), field('mirrorTag')).as('tagsMatch'),
+              equal(field('tag'), 'alpha').as('tagStringRhs'),
+              notEqual(field('status'), 'inactive').as('statusActive'),
+              lessThanOrEqual(field('score'), '50').as('scoreLteString'),
+              greaterThanOrEqual(field('base'), false).as('baseGteFalse'),
+            ),
+        );
+
+        snapshot.results.should.have.length(1);
+        const data = snapshot.results[0].data();
+        data.subTrue.should.equal(19);
+        data.subString.should.equal(15);
+        data.divField.should.equal(5);
+        data.powTrue.should.equal(3);
+        data.tagsMatch.should.equal(true);
+        data.tagStringRhs.should.equal(true);
+        data.statusActive.should.equal(true);
+        data.scoreLteString.should.equal(true);
+        data.baseGteFalse.should.equal(true);
+
+        const coll = collection(
+          db,
+          `${COLLECTION}/${Utils.randString(12, '#aA')}/operand-tail-raw-where`,
+        );
+
+        await Promise.all([
+          setDoc(doc(coll, 'match'), {
+            tag: 'alpha',
+            score: 42,
+            bump: true,
+            status: 'active',
+          }),
+          setDoc(doc(coll, 'skip-tag'), {
+            tag: 'beta',
+            score: 42,
+            bump: true,
+            status: 'active',
+          }),
+          setDoc(doc(coll, 'skip-score'), {
+            tag: 'alpha',
+            score: 10,
+            bump: true,
+            status: 'active',
+          }),
+        ]);
+
+        const filtered = await execute(
+          db
+            .pipeline()
+            .collection(coll)
+            .where({
+              condition: {
+                operator: 'AND',
+                queries: [
+                  { operator: '==', fieldPath: 'tag', value: 'alpha' },
+                  { operator: '==', fieldPath: 'bump', value: true },
+                  { operator: '==', fieldPath: 'status', value: 'active' },
+                ],
+              },
+            })
+            .select('tag', 'score', 'status'),
+        );
+
+        filtered.results.should.have.length(1);
+        filtered.results[0].data().tag.should.equal('alpha');
+        filtered.results[0].data().score.should.equal(42);
+
+        const whereSnapshot = await execute(
+          db
+            .pipeline()
+            .collection(coll)
+            .where(
+              and(
+                equal(field('tag'), 'alpha'),
+                equal(field('status'), 'active'),
+                greaterThanOrEqual(field('score'), false),
+                greaterThan(field('score'), 20),
+              ),
+            )
+            .select('tag', 'score'),
+        );
+
+        whereSnapshot.results.should.have.length(1);
+        whereSnapshot.results[0].data().score.should.equal(42);
+      });
+    });
+
     describe('aggregate expression argument lowering', function () {
       it('evaluates aggregates with computed expression arguments', async function () {
         const {

packages/firestore/e2e/Pipeline.e2e.js

@@ -1595,30 +1595,35 @@ final class RNFBFirestorePipelineNodeBuilder {
           if let map = value as? [String: Any],
              let kind = (map["exprType"] as? String)?.lowercased(), kind == "constant" {
             if let boolValue = map["value"] as? Bool {
-              box.value = ConstantBridge(boolValue ? 1 : 0)
+              box.value = ConstantBridge(boolValue ? 1.0 : 0.0)
               continue
             }
-            box.value = try scalarConstantBridge(fromConstantMap: map, fieldName: currentFieldName)
+            if let number = map["value"] as? NSNumber, isBooleanNSNumber(number) {
+              box.value = ConstantBridge(number.boolValue ? 1.0 : 0.0)
+              continue
+            }
+            let constantValue = try constantExpressionValue(fromConstantMap: map, fieldName: currentFieldName)
+            box.value = try numericOperandConstantBridge(from: constantValue)
             continue
           }
           if let values = value as? [Any] {
             box.value = ConstantBridge(try resolveConstantValue(values, fieldName: currentFieldName))
             continue
           }
           if let stringValue = value as? String {
-            box.value = ConstantBridge(stringValue)
+            box.value = try numericOperandConstantBridge(from: stringValue)
             continue
           }
           if let boolValue = value as? Bool {
-            box.value = ConstantBridge(boolValue ? 1 : 0)
+            box.value = ConstantBridge(boolValue ? 1.0 : 0.0)
             continue
           }
           if let number = value as? NSNumber, isBooleanNSNumber(number) {
-            box.value = ConstantBridge(number.boolValue ? 1 : 0)
+            box.value = ConstantBridge(number.boolValue ? 1.0 : 0.0)
             continue
           }
           if isImmediateExpressionConstant(value) {
-            box.value = scalarConstantBridge(from: value)
+            box.value = try numericOperandConstantBridge(from: value)
             continue
           }
           stack.append(.enter(value, currentFieldName, .expression, box))
@@ -1726,14 +1731,20 @@ final class RNFBFirestorePipelineNodeBuilder {
               let leftFieldPath = try coerceFieldPath(fieldValue, fieldName: "\(currentField).fieldPath")
               let right = map["value"] ?? map["right"] ?? map["operand"] ?? NSNull()
               let rightBox = ExprBridgeBox()
+              let comparisonFunction = mapOperatorToFunction(normalizedOperator)
+              let normalizedComparisonFunction = canonicalizeFunctionName(comparisonFunction)
+              let rawWhereRightOperandMode: ExpressionCoercionMode =
+                orderingComparisonFunctions.contains(normalizedComparisonFunction)
+                  ? .numericOperand
+                  : .comparisonOperand
               stack.append(.binaryOperatorExit(
                 box,
-                mapOperatorToFunction(normalizedOperator),
+                comparisonFunction,
                 leftFieldPath,
                 rightBox,
                 currentField
               ))
-              stack.append(.enter(right, "\(currentField).value", .comparisonOperand, rightBox))
+              stack.append(.enter(right, "\(currentField).value", rawWhereRightOperandMode, rightBox))
               break expressionLoop
             }
 
@@ -2085,12 +2096,10 @@ final class RNFBFirestorePipelineNodeBuilder {
           }
         }
       case let .functionExit(box, name, argBoxes, currentFieldName):
-        box.value = FunctionExprBridge(
-          name: name,
-          args: try argBoxes.enumerated().map { index, argBox in
-            try requireExpressionValue(argBox, fieldName: "\(currentFieldName).args[\(index)]")
-          }
-        )
+        let args = try argBoxes.enumerated().map { index, argBox in
+          try requireExpressionValue(argBox, fieldName: "\(currentFieldName).args[\(index)]")
+        }
+        box.value = FunctionExprBridge(name: name, args: args)
         if RNFBFirestorePipelineDebug.enabled,
            name == "add" || name.contains("array") || name.contains("equal") || name.contains("greater") {
           RNFBFirestorePipelineDebug.log(
@@ -2199,6 +2208,27 @@ final class RNFBFirestorePipelineNodeBuilder {
       value is GeoPoint || value is DocumentReference || value is VectorValue
   }
 
+
+  private func numericOperandConstantBridge(from value: Any) throws -> ExprBridge {
+    if let boolValue = value as? Bool {
+      return ConstantBridge(boolValue ? 1.0 : 0.0)
+    }
+    if let number = value as? NSNumber, isBooleanNSNumber(number) {
+      return ConstantBridge(number.boolValue ? 1.0 : 0.0)
+    }
+    if let stringValue = value as? String {
+      let trimmed = stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+      if !trimmed.isEmpty, let parsed = Double(trimmed), parsed.isFinite {
+        if let intValue = wholeNumberInt(from: NSNumber(value: parsed)) {
+          return ConstantBridge(intValue)
+        }
+        return ConstantBridge(parsed)
+      }
+      return ConstantBridge(stringValue)
+    }
+    return scalarConstantBridge(from: value)
+  }
+
   private func tryIntegerLiteral(from value: Any) -> Int? {
     if let number = value as? NSNumber {
       return wholeNumberInt(from: number)