fix(OUT-3686): switch ORDERBY back to Id ASC for full stability

CreateTime DESC closed the common race (concurrent updates) but left a
narrower one open (concurrent CREATE prepending to the front of the
cursor). Id ASC closes both: Id is monotonic and immutable, so any
customer added during the walk lands at the END of the cursor where
we'll still encounter it.

Cost: newly-created customers land on the last page instead of page 1,
so drift recovery for a fresh customer in a 10k realm walks all pages
(~5s) instead of hitting on page 1 (~500ms). The perf cost is bounded
and only fires on local-DB-miss paths — full stability is the priority.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: SandipBajracharya

src/utils/intuitAPI.ts

@@ -307,19 +307,17 @@ export default class IntuitAPI {
   // CompanyName comparison uses the same `(value || undefined)` normalisation
   // as the post-filter in customer.service.ts so the two layers cannot disagree.
   //
-  // ORDERBY MetaData.CreateTime DESC pins the cursor to an immutable key while
-  // putting the newest customers on page 1. QBO's default ordering
-  // (LastUpdatedTime DESC) is unstable — an update mid-walk shifts the row and
-  // can push an unscanned customer past our STARTPOSITION cursor. CreateTime is
-  // set on insert and never changes, so concurrent updates do not move
-  // anything. Drift recovery overwhelmingly targets recently-created customers
-  // (new to us → no local mapping), so DESC by creation time also keeps the
-  // common case fast (page-1 hit, ~500ms vs full-realm walk).
+  // ORDERBY Id ASC pins the cursor to a stable, append-only key. QBO's default
+  // ordering is MetaData.LastUpdatedTime DESC — under that ordering, a customer
+  // updated mid-walk shifts to the front and can push an unscanned row past
+  // our STARTPOSITION cursor (false negative). Id is monotonic and immutable,
+  // so concurrent updates do not move rows and any customer created during the
+  // walk lands at the end of the cursor where we'll still encounter it.
   //
-  // Tradeoff: a customer CREATED in QBO during the walk would prepend to the
-  // front and slip past our cursor. This is an accepted miss class — same
-  // shape as the parallel-webhook TOCTOU we already accept elsewhere in this
-  // codebase, and bounded to a single ~5s window per drift-recovery call.
+  // Tradeoff vs. CreateTime DESC: newly-created customers land on the LAST
+  // page rather than page 1, so drift recovery for a fresh customer in a 10k
+  // realm walks all pages (~5s) instead of hitting on page 1 (~500ms). The
+  // perf cost is bounded and acceptable; full stability is the priority.
   async _getCustomerByEmail(
     email: string,
     sanitizedCompanyName: string | undefined,
@@ -336,7 +334,7 @@ export default class IntuitAPI {
     let startPosition = 1
 
     while (true) {
-      const customerQuery = `SELECT Id, SyncToken, Active, CompanyName, PrimaryEmailAddr FROM Customer WHERE Active IN (true, false) ORDERBY MetaData.CreateTime DESC STARTPOSITION ${startPosition} MAXRESULTS ${pageSize}`
+      const customerQuery = `SELECT Id, SyncToken, Active, CompanyName, PrimaryEmailAddr FROM Customer WHERE Active IN (true, false) ORDERBY Id ASC STARTPOSITION ${startPosition} MAXRESULTS ${pageSize}`
       const qbCustomers = await this.customQuery(customerQuery)
       const customers = qbCustomers?.Customer ?? []
       if (customers.length === 0) return

test/unit/utils/intuitAPI.test.ts

@@ -356,20 +356,20 @@ describe('IntuitAPI#getCustomerByEmail', () => {
     expect(query).toMatch(/Active IN \(true, false\)/)
   })
 
-  it('emits ORDERBY MetaData.CreateTime DESC so the cursor is stable across pages', async () => {
+  it('emits ORDERBY Id ASC so the cursor is stable across pages', async () => {
     // Without an explicit order, QBO sorts by MetaData.LastUpdatedTime DESC.
     // A customer updated between page fetches shifts under that ordering and
-    // can be skipped near a STARTPOSITION boundary. CreateTime is immutable,
-    // so concurrent updates do not move rows; DESC also puts the newest
-    // customers on page 1, which is where drift recovery typically targets.
+    // can be skipped near a STARTPOSITION boundary. Id is monotonic and
+    // immutable, so concurrent updates do not move rows and concurrent
+    // creates always land at the end of the cursor.
     const { api, customQuery } = makeApi([
       { Customer: [row('1', 'alice@example.com')] },
     ])
 
     await api.getCustomerByEmail('alice@example.com', undefined)
 
     const query = customQuery.mock.calls[0][0] as string
-    expect(query).toMatch(/ORDERBY MetaData\.CreateTime DESC/)
+    expect(query).toMatch(/ORDERBY Id ASC/)
   })
 
   // Company-aware matching: a Copilot client can be enrolled in multiple