@tanstack/db 0.5.17 → 0.5.19

package/src/query/compiler/group-by.ts

@@ -1,4 +1,10 @@
-import { filter, groupBy, groupByOperators, map } from '@tanstack/db-ivm'
+import {
+  filter,
+  groupBy,
+  groupByOperators,
+  map,
+  serializeValue,
+} from '@tanstack/db-ivm'
 import { Func, PropRef, getHavingExpression } from '../ir.js'
 import {
   AggregateFunctionNotInSelectError,
@@ -66,7 +72,7 @@ function validateAndCreateMapping(
 
 /**
  * Processes the GROUP BY clause with optional HAVING and SELECT
- * Works with the new __select_results structure from early SELECT processing
+ * Works with the new $selected structure from early SELECT processing
  */
 export function processGroupBy(
   pipeline: NamespacedAndKeyedStream,
@@ -98,11 +104,11 @@ export function processGroupBy(
       groupBy(keyExtractor, aggregates),
     ) as NamespacedAndKeyedStream
 
-    // Update __select_results to include aggregate values
+    // Update $selected to include aggregate values
     pipeline = pipeline.pipe(
       map(([, aggregatedRow]) => {
-        // Start with the existing __select_results from early SELECT processing
-        const selectResults = (aggregatedRow as any).__select_results || {}
+        // Start with the existing $selected from early SELECT processing
+        const selectResults = (aggregatedRow as any).$selected || {}
         const finalResults: Record<string, any> = { ...selectResults }
 
         if (selectClause) {
@@ -115,12 +121,12 @@ export function processGroupBy(
           }
         }
 
-        // Use a single key for the result and update __select_results
+        // Use a single key for the result and update $selected
         return [
           `single_group`,
           {
             ...aggregatedRow,
-            __select_results: finalResults,
+            $selected: finalResults,
           },
         ] as [unknown, Record<string, any>]
       }),
@@ -133,13 +139,14 @@ export function processGroupBy(
         const transformedHavingClause = replaceAggregatesByRefs(
           havingExpression,
           selectClause || {},
+          `$selected`,
         )
         const compiledHaving = compileExpression(transformedHavingClause)
 
         pipeline = pipeline.pipe(
           filter(([, row]) => {
             // Create a namespaced row structure for HAVING evaluation
-            const namespacedRow = { result: (row as any).__select_results }
+            const namespacedRow = { $selected: (row as any).$selected }
             return toBooleanPredicate(compiledHaving(namespacedRow))
           }),
         )
@@ -152,7 +159,7 @@ export function processGroupBy(
         pipeline = pipeline.pipe(
           filter(([, row]) => {
             // Create a namespaced row structure for functional HAVING evaluation
-            const namespacedRow = { result: (row as any).__select_results }
+            const namespacedRow = { $selected: (row as any).$selected }
             return toBooleanPredicate(fnHaving(namespacedRow))
           }),
         )
@@ -174,11 +181,11 @@ export function processGroupBy(
   // Create a key extractor function using simple __key_X format
   const keyExtractor = ([, row]: [
     string,
-    NamespacedRow & { __select_results?: any },
+    NamespacedRow & { $selected?: any },
   ]) => {
-    // Use the original namespaced row for GROUP BY expressions, not __select_results
+    // Use the original namespaced row for GROUP BY expressions, not $selected
     const namespacedRow = { ...row }
-    delete (namespacedRow as any).__select_results
+    delete (namespacedRow as any).$selected
 
     const key: Record<string, unknown> = {}
 
@@ -208,11 +215,11 @@ export function processGroupBy(
   // Apply the groupBy operator
   pipeline = pipeline.pipe(groupBy(keyExtractor, aggregates))
 
-  // Update __select_results to handle GROUP BY results
+  // Update $selected to handle GROUP BY results
   pipeline = pipeline.pipe(
     map(([, aggregatedRow]) => {
-      // Start with the existing __select_results from early SELECT processing
-      const selectResults = (aggregatedRow as any).__select_results || {}
+      // Start with the existing $selected from early SELECT processing
+      const selectResults = (aggregatedRow as any).$selected || {}
       const finalResults: Record<string, any> = {}
 
       if (selectClause) {
@@ -248,14 +255,14 @@ export function processGroupBy(
         for (let i = 0; i < groupByClause.length; i++) {
           keyParts.push(aggregatedRow[`__key_${i}`])
         }
-        finalKey = JSON.stringify(keyParts)
+        finalKey = serializeValue(keyParts)
       }
 
       return [
         finalKey,
         {
           ...aggregatedRow,
-          __select_results: finalResults,
+          $selected: finalResults,
         },
       ] as [unknown, Record<string, any>]
     }),
@@ -274,7 +281,7 @@ export function processGroupBy(
       pipeline = pipeline.pipe(
         filter(([, row]) => {
           // Create a namespaced row structure for HAVING evaluation
-          const namespacedRow = { result: (row as any).__select_results }
+          const namespacedRow = { $selected: (row as any).$selected }
           return compiledHaving(namespacedRow)
         }),
       )
@@ -287,7 +294,7 @@ export function processGroupBy(
       pipeline = pipeline.pipe(
         filter(([, row]) => {
           // Create a namespaced row structure for functional HAVING evaluation
-          const namespacedRow = { result: (row as any).__select_results }
+          const namespacedRow = { $selected: (row as any).$selected }
           return toBooleanPredicate(fnHaving(namespacedRow))
         }),
       )
@@ -385,12 +392,28 @@ function getAggregateFunction(aggExpr: Aggregate) {
 }
 
 /**
- * Transforms basic expressions and aggregates to replace Agg expressions with references to computed values
+ * Transforms expressions to replace aggregate functions with references to computed values.
+ *
+ * This function is used in both ORDER BY and HAVING clauses to transform expressions that reference:
+ * 1. Aggregate functions (e.g., `max()`, `count()`) - replaces with references to computed aggregates in SELECT
+ * 2. SELECT field references via $selected namespace (e.g., `$selected.latestActivity`) - validates and passes through unchanged
+ *
+ * For aggregate expressions, it finds matching aggregates in the SELECT clause and replaces them with
+ * PropRef([resultAlias, alias]) to reference the computed aggregate value.
+ *
+ * For ref expressions using the $selected namespace, it validates that the field exists in the SELECT clause
+ * and passes them through unchanged (since $selected is already the correct namespace). All other ref expressions
+ * are passed through unchanged (treating them as table column references).
+ *
+ * @param havingExpr - The expression to transform (can be aggregate, ref, func, or val)
+ * @param selectClause - The SELECT clause containing aliases and aggregate definitions
+ * @param resultAlias - The namespace alias for SELECT results (default: '$selected', used for aggregate references)
+ * @returns A transformed BasicExpression that references computed values instead of raw expressions
  */
 export function replaceAggregatesByRefs(
   havingExpr: BasicExpression | Aggregate,
   selectClause: Select,
-  resultAlias: string = `result`,
+  resultAlias: string = `$selected`,
 ): BasicExpression {
   switch (havingExpr.type) {
     case `agg`: {
@@ -417,7 +440,38 @@ export function replaceAggregatesByRefs(
     }
 
     case `ref`: {
-      // Non-aggregate refs are passed through unchanged (they reference table columns)
+      const refExpr = havingExpr
+      const path = refExpr.path
+
+      if (path.length === 0) {
+        // Empty path - pass through
+        return havingExpr as BasicExpression
+      }
+
+      // Check if this is a $selected reference
+      if (path.length > 0 && path[0] === `$selected`) {
+        // Extract the field path after $selected
+        const fieldPath = path.slice(1)
+
+        if (fieldPath.length === 0) {
+          // Just $selected without a field - pass through unchanged
+          return havingExpr as BasicExpression
+        }
+
+        // Verify the field exists in SELECT clause
+        const alias = fieldPath.join(`.`)
+        if (alias in selectClause) {
+          // Pass through unchanged - $selected is already the correct namespace
+          return havingExpr as BasicExpression
+        }
+
+        // Field doesn't exist in SELECT - this is an error, but we'll pass through for now
+        // (Could throw an error here in the future)
+        return havingExpr as BasicExpression
+      }
+
+      // Not a $selected reference - this is a table column reference, pass through unchanged
+      // SELECT fields should only be accessed via $selected namespace
       return havingExpr as BasicExpression
     }
 

package/src/query/compiler/index.ts

@@ -216,7 +216,7 @@ export function compileQuery(
     throw new DistinctRequiresSelectError()
   }
 
-  // Process the SELECT clause early - always create __select_results
+  // Process the SELECT clause early - always create $selected
   // This eliminates duplication and allows for DISTINCT implementation
   if (query.fnSelect) {
     // Handle functional select - apply the function to transform the row
@@ -227,15 +227,15 @@ export function compileQuery(
           key,
           {
             ...namespacedRow,
-            __select_results: selectResults,
+            $selected: selectResults,
           },
-        ] as [string, typeof namespacedRow & { __select_results: any }]
+        ] as [string, typeof namespacedRow & { $selected: any }]
       }),
     )
   } else if (query.select) {
     pipeline = processSelect(pipeline, query.select, allInputs)
   } else {
-    // If no SELECT clause, create __select_results with the main table data
+    // If no SELECT clause, create $selected with the main table data
     pipeline = pipeline.pipe(
       map(([key, namespacedRow]) => {
         const selectResults =
@@ -247,9 +247,9 @@ export function compileQuery(
           key,
           {
             ...namespacedRow,
-            __select_results: selectResults,
+            $selected: selectResults,
           },
-        ] as [string, typeof namespacedRow & { __select_results: any }]
+        ] as [string, typeof namespacedRow & { $selected: any }]
       }),
     )
   }
@@ -310,7 +310,7 @@ export function compileQuery(
 
   // Process the DISTINCT clause if it exists
   if (query.distinct) {
-    pipeline = pipeline.pipe(distinct(([_key, row]) => row.__select_results))
+    pipeline = pipeline.pipe(distinct(([_key, row]) => row.$selected))
   }
 
   // Process orderBy parameter if it exists
@@ -327,11 +327,11 @@ export function compileQuery(
       query.offset,
     )
 
-    // Final step: extract the __select_results and include orderBy index
+    // Final step: extract the $selected and include orderBy index
     const resultPipeline = orderedPipeline.pipe(
       map(([key, [row, orderByIndex]]) => {
-        // Extract the final results from __select_results and include orderBy index
-        const raw = (row as any).__select_results
+        // Extract the final results from $selected and include orderBy index
+        const raw = (row as any).$selected
         const finalResults = unwrapValue(raw)
         return [key, [finalResults, orderByIndex]] as [unknown, [any, string]]
       }),
@@ -354,11 +354,11 @@ export function compileQuery(
     throw new LimitOffsetRequireOrderByError()
   }
 
-  // Final step: extract the __select_results and return tuple format (no orderBy)
+  // Final step: extract the $selected and return tuple format (no orderBy)
   const resultPipeline: ResultStream = pipeline.pipe(
     map(([key, row]) => {
-      // Extract the final results from __select_results and return [key, [results, undefined]]
-      const raw = (row as any).__select_results
+      // Extract the final results from $selected and return [key, [results, undefined]]
+      const raw = (row as any).$selected
       const finalResults = unwrapValue(raw)
       return [key, [finalResults, undefined]] as [
         unknown,

package/src/query/compiler/order-by.ts

@@ -38,7 +38,7 @@ export type OrderByOptimizationInfo = {
 
 /**
  * Processes the ORDER BY clause
- * Works with the new structure that has both namespaced row data and __select_results
+ * Works with the new structure that has both namespaced row data and $selected
  * Always uses fractional indexing and adds the index as __ordering_index to the result
  */
 export function processOrderBy(
@@ -57,7 +57,7 @@ export function processOrderBy(
     const clauseWithoutAggregates = replaceAggregatesByRefs(
       clause.expression,
       selectClause,
-      `__select_results`,
+      `$selected`,
     )
 
     return {
@@ -67,12 +67,13 @@ export function processOrderBy(
   })
 
   // Create a value extractor function for the orderBy operator
-  const valueExtractor = (row: NamespacedRow & { __select_results?: any }) => {
+  const valueExtractor = (row: NamespacedRow & { $selected?: any }) => {
     // The namespaced row contains:
     // 1. Table aliases as top-level properties (e.g., row["tableName"])
-    // 2. SELECT results in __select_results (e.g., row.__select_results["aggregateAlias"])
-    // The replaceAggregatesByRefs function has already transformed any aggregate expressions
-    // that match SELECT aggregates to use the __select_results namespace.
+    // 2. SELECT results in $selected (e.g., row.$selected["aggregateAlias"])
+    // The replaceAggregatesByRefs function has already transformed:
+    // - Aggregate expressions that match SELECT aggregates to use the $selected namespace
+    // - $selected ref expressions are passed through unchanged (already using the correct namespace)
     const orderByContext = row
 
     if (orderByClause.length > 1) {

package/src/query/compiler/select.ts

@@ -100,7 +100,7 @@ function processNonMergeOp(
 function processRow(
   [key, namespacedRow]: [unknown, NamespacedRow],
   ops: Array<SelectOp>,
-): [unknown, typeof namespacedRow & { __select_results: any }] {
+): [unknown, typeof namespacedRow & { $selected: any }] {
   const selectResults: Record<string, any> = {}
 
   for (const op of ops) {
@@ -111,21 +111,18 @@ function processRow(
     }
   }
 
-  // Return the namespaced row with __select_results added
+  // Return the namespaced row with $selected added
   return [
     key,
     {
       ...namespacedRow,
-      __select_results: selectResults,
+      $selected: selectResults,
     },
-  ] as [
-    unknown,
-    typeof namespacedRow & { __select_results: typeof selectResults },
-  ]
+  ] as [unknown, typeof namespacedRow & { $selected: typeof selectResults }]
 }
 
 /**
- * Processes the SELECT clause and places results in __select_results
+ * Processes the SELECT clause and places results in $selected
  * while preserving the original namespaced row for ORDER BY access
  */
 export function processSelect(

package/src/query/live/collection-config-builder.ts

@@ -337,6 +337,10 @@ export class CollectionConfigBuilder<
       if (syncState.subscribedToAllCollections) {
         while (syncState.graph.pendingWork()) {
           syncState.graph.run()
+          // Flush accumulated changes after each graph step to commit them as one transaction.
+          // This ensures intermediate join states (like null on one side) don't cause
+          // duplicate key errors when the full join result arrives in the same step.
+          syncState.flushPendingChanges?.()
           callback?.()
         }
 
@@ -345,10 +349,14 @@ export class CollectionConfigBuilder<
         if (syncState.messagesCount === 0) {
           begin()
           commit()
-          // After initial commit, check if we should mark ready
-          // (in case all sources were already ready before we subscribed)
-          this.updateLiveQueryStatus(this.currentSyncConfig)
         }
+
+        // After graph processing completes, check if we should mark ready.
+        // This is the canonical place to transition to ready state because:
+        // 1. All data has been processed through the graph
+        // 2. All source collections have had a chance to send their initial data
+        // This prevents marking ready before data is processed (fixes isReady=true with empty data)
+        this.updateLiveQueryStatus(this.currentSyncConfig)
       }
     } finally {
       this.isGraphRunning = false
@@ -566,6 +574,21 @@ export class CollectionConfigBuilder<
       },
     )
 
+    // Listen for loadingSubset changes on the live query collection BEFORE subscribing.
+    // This ensures we don't miss the event if subset loading completes synchronously.
+    // When isLoadingSubset becomes false, we may need to mark the collection as ready
+    // (if all source collections are already ready but we were waiting for subset load to complete)
+    const loadingSubsetUnsubscribe = config.collection.on(
+      `loadingSubset:change`,
+      (event) => {
+        if (!event.isLoadingSubset) {
+          // Subset loading finished, check if we can now mark ready
+          this.updateLiveQueryStatus(config)
+        }
+      },
+    )
+    syncState.unsubscribeCallbacks.add(loadingSubsetUnsubscribe)
+
     const loadSubsetDataCallbacks = this.subscribeToAllCollections(
       config,
       fullSyncState,
@@ -672,22 +695,35 @@ export class CollectionConfigBuilder<
     const { begin, commit } = config
     const { graph, inputs, pipeline } = this.maybeCompileBasePipeline()
 
+    // Accumulator for changes across all output callbacks within a single graph run.
+    // This allows us to batch all changes from intermediate join states into a single
+    // transaction, avoiding duplicate key errors when joins produce multiple outputs
+    // for the same key (e.g., first output with null, then output with joined data).
+    let pendingChanges: Map<unknown, Changes<TResult>> = new Map()
+
     pipeline.pipe(
       output((data) => {
         const messages = data.getInner()
         syncState.messagesCount += messages.length
 
-        begin()
-        messages
-          .reduce(
-            accumulateChanges<TResult>,
-            new Map<unknown, Changes<TResult>>(),
-          )
-          .forEach(this.applyChanges.bind(this, config))
-        commit()
+        // Accumulate changes from this output callback into the pending changes map.
+        // Changes for the same key are merged (inserts/deletes are added together).
+        messages.reduce(accumulateChanges<TResult>, pendingChanges)
       }),
     )
 
+    // Flush pending changes and reset the accumulator.
+    // Called at the end of each graph run to commit all accumulated changes.
+    syncState.flushPendingChanges = () => {
+      if (pendingChanges.size === 0) {
+        return
+      }
+      begin()
+      pendingChanges.forEach(this.applyChanges.bind(this, config))
+      commit()
+      pendingChanges = new Map()
+    }
+
     graph.finalize()
 
     // Extend the sync state with the graph, inputs, and pipeline
@@ -793,8 +829,17 @@ export class CollectionConfigBuilder<
       return
     }
 
-    // Mark ready when all source collections are ready
-    if (this.allCollectionsReady()) {
+    // Mark ready when:
+    // 1. All subscriptions are set up (subscribedToAllCollections)
+    // 2. All source collections are ready
+    // 3. The live query collection is not loading subset data
+    // This prevents marking the live query ready before its data is processed
+    // (fixes issue where useLiveQuery returns isReady=true with empty data)
+    if (
+      this.currentSyncState?.subscribedToAllCollections &&
+      this.allCollectionsReady() &&
+      !this.liveQueryCollection?.isLoadingSubset
+    ) {
       markReady()
     }
   }
@@ -892,8 +937,10 @@ export class CollectionConfigBuilder<
     // (graph only runs when all collections are subscribed)
     syncState.subscribedToAllCollections = true
 
-    // Initial status check after all subscriptions are set up
-    this.updateLiveQueryStatus(config)
+    // Note: We intentionally don't call updateLiveQueryStatus() here.
+    // The graph hasn't run yet, so marking ready would be premature.
+    // The canonical place to mark ready is after the graph processes data
+    // in maybeRunGraph(), which ensures data has been processed first.
 
     return loadSubsetDataCallbacks
   }
@@ -1075,8 +1122,11 @@ function accumulateChanges<T>(
     changes.deletes += Math.abs(multiplicity)
   } else if (multiplicity > 0) {
     changes.inserts += multiplicity
+    // Update value to the latest version for this key
     changes.value = value
-    changes.orderByIndex = orderByIndex
+    if (orderByIndex !== undefined) {
+      changes.orderByIndex = orderByIndex
+    }
   }
   acc.set(key, changes)
   return acc

package/src/query/live/collection-subscriber.ts

@@ -5,7 +5,10 @@ import {
 } from '../compiler/expressions.js'
 import type { MultiSetArray, RootStreamBuilder } from '@tanstack/db-ivm'
 import type { Collection } from '../../collection/index.js'
-import type { ChangeMessage } from '../../types.js'
+import type {
+  ChangeMessage,
+  SubscriptionStatusChangeEvent,
+} from '../../types.js'
 import type { Context, GetResult } from '../builder/types.js'
 import type { BasicExpression } from '../ir.js'
 import type { OrderByOptimizationInfo } from '../compiler/order-by.js'
@@ -53,26 +56,10 @@ export class CollectionSubscriber<
   }
 
   private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {
-    let subscription: CollectionSubscription
     const orderByInfo = this.getOrderByInfo()
-    if (orderByInfo) {
-      subscription = this.subscribeToOrderedChanges(
-        whereExpression,
-        orderByInfo,
-      )
-    } else {
-      // If the source alias is lazy then we should not include the initial state
-      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(
-        this.alias,
-      )
-
-      subscription = this.subscribeToMatchingChanges(
-        whereExpression,
-        includeInitialState,
-      )
-    }
 
-    const trackLoadPromise = () => {
+    // Track load promises using subscription from the event (avoids circular dependency)
+    const trackLoadPromise = (subscription: CollectionSubscription) => {
       // Guard against duplicate transitions
       if (!this.subscriptionLoadingPromises.has(subscription)) {
         let resolve: () => void
@@ -89,16 +76,12 @@ export class CollectionSubscriber<
       }
     }
 
-    // It can be that we are not yet subscribed when the first `loadSubset` call happens (i.e. the initial query).
-    // So we also check the status here and if it's `loadingSubset` then we track the load promise
-    if (subscription.status === `loadingSubset`) {
-      trackLoadPromise()
-    }
-
-    // Subscribe to subscription status changes to propagate loading state
-    const statusUnsubscribe = subscription.on(`status:change`, (event) => {
+    // Status change handler - passed to subscribeChanges so it's registered
+    // BEFORE any snapshot is requested, preventing race conditions
+    const onStatusChange = (event: SubscriptionStatusChangeEvent) => {
+      const subscription = event.subscription as CollectionSubscription
       if (event.status === `loadingSubset`) {
-        trackLoadPromise()
+        trackLoadPromise(subscription)
       } else {
         // status is 'ready'
         const deferred = this.subscriptionLoadingPromises.get(subscription)
@@ -108,7 +91,34 @@ export class CollectionSubscriber<
           deferred.resolve()
         }
       }
-    })
+    }
+
+    // Create subscription with onStatusChange - listener is registered before any async work
+    let subscription: CollectionSubscription
+    if (orderByInfo) {
+      subscription = this.subscribeToOrderedChanges(
+        whereExpression,
+        orderByInfo,
+        onStatusChange,
+      )
+    } else {
+      // If the source alias is lazy then we should not include the initial state
+      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(
+        this.alias,
+      )
+
+      subscription = this.subscribeToMatchingChanges(
+        whereExpression,
+        includeInitialState,
+        onStatusChange,
+      )
+    }
+
+    // Check current status after subscribing - if status is 'loadingSubset', track it.
+    // The onStatusChange listener will catch the transition to 'ready'.
+    if (subscription.status === `loadingSubset`) {
+      trackLoadPromise(subscription)
+    }
 
     const unsubscribe = () => {
       // If subscription has a pending promise, resolve it before unsubscribing
@@ -119,7 +129,6 @@ export class CollectionSubscriber<
         deferred.resolve()
       }
 
-      statusUnsubscribe()
       subscription.unsubscribe()
     }
     // currentSyncState is always defined when subscribe() is called
@@ -179,22 +188,22 @@ export class CollectionSubscriber<
 
   private subscribeToMatchingChanges(
     whereExpression: BasicExpression<boolean> | undefined,
-    includeInitialState: boolean = false,
-  ) {
+    includeInitialState: boolean,
+    onStatusChange: (event: SubscriptionStatusChangeEvent) => void,
+  ): CollectionSubscription {
     const sendChanges = (
       changes: Array<ChangeMessage<any, string | number>>,
     ) => {
       this.sendChangesToPipeline(changes)
     }
 
-    // Only pass includeInitialState when true. When it's false, we leave it
-    // undefined so that user subscriptions with explicit `includeInitialState: false`
-    // can be distinguished from internal lazy-loading subscriptions.
-    // If we pass `false`, changes.ts would call markAllStateAsSeen() which
-    // disables filtering - but internal subscriptions still need filtering.
+    // Create subscription with onStatusChange - listener is registered before snapshot
+    // Note: For non-ordered queries (no limit/offset), we use trackLoadSubsetPromise: false
+    // which is the default behavior in subscribeChanges
     const subscription = this.collection.subscribeChanges(sendChanges, {
       ...(includeInitialState && { includeInitialState }),
       whereExpression,
+      onStatusChange,
     })
 
     return subscription
@@ -203,22 +212,31 @@ export class CollectionSubscriber<
   private subscribeToOrderedChanges(
     whereExpression: BasicExpression<boolean> | undefined,
     orderByInfo: OrderByOptimizationInfo,
-  ) {
+    onStatusChange: (event: SubscriptionStatusChangeEvent) => void,
+  ): CollectionSubscription {
     const { orderBy, offset, limit, index } = orderByInfo
 
+    // Use a holder to forward-reference subscription in the callback
+    const subscriptionHolder: { current?: CollectionSubscription } = {}
+
     const sendChangesInRange = (
       changes: Iterable<ChangeMessage<any, string | number>>,
     ) => {
       // Split live updates into a delete of the old value and an insert of the new value
       const splittedChanges = splitUpdates(changes)
-      this.sendChangesToPipelineWithTracking(splittedChanges, subscription)
+      this.sendChangesToPipelineWithTracking(
+        splittedChanges,
+        subscriptionHolder.current!,
+      )
     }
 
-    // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far
-    // values that are bigger don't need to be sent because they can't affect the topK
+    // Subscribe to changes with onStatusChange - listener is registered before any snapshot
+    // values bigger than what we've sent don't need to be sent because they can't affect the topK
     const subscription = this.collection.subscribeChanges(sendChangesInRange, {
       whereExpression,
+      onStatusChange,
     })
+    subscriptionHolder.current = subscription
 
     // Listen for truncate events to reset cursor tracking state and sentToD2Keys
     // This ensures that after a must-refetch/truncate, we don't use stale cursor data
@@ -236,6 +254,7 @@ export class CollectionSubscriber<
     // Normalize the orderBy clauses such that the references are relative to the collection
     const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
 
+    // Trigger the snapshot request - onStatusChange listener is already registered
     if (index) {
       // We have an index on the first orderBy column - use lazy loading optimization
       // This works for both single-column and multi-column orderBy: