@tanstack/db 0.5.11 → 0.5.13

package/src/collection/state.ts

@@ -1,16 +1,17 @@
-import { deepEquals } from "../utils"
-import { SortedMap } from "../SortedMap"
-import type { Transaction } from "../transactions"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { deepEquals } from '../utils'
+import { SortedMap } from '../SortedMap'
+import type { Transaction } from '../transactions'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type {
   ChangeMessage,
   CollectionConfig,
   OptimisticChangeMessage,
-} from "../types"
-import type { CollectionImpl } from "./index.js"
-import type { CollectionLifecycleManager } from "./lifecycle"
-import type { CollectionChangesManager } from "./changes"
-import type { CollectionIndexesManager } from "./indexes"
+} from '../types'
+import type { CollectionImpl } from './index.js'
+import type { CollectionLifecycleManager } from './lifecycle'
+import type { CollectionChangesManager } from './changes'
+import type { CollectionIndexesManager } from './indexes'
+import type { CollectionEventsManager } from './events'
 
 interface PendingSyncedTransaction<
   T extends object = Record<string, unknown>,
@@ -37,13 +38,14 @@ export class CollectionStateManager<
   public lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
   public changes!: CollectionChangesManager<TOutput, TKey, TSchema, TInput>
   public indexes!: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>
+  private _events!: CollectionEventsManager
 
   // Core state - make public for testing
   public transactions: SortedMap<string, Transaction<any>>
   public pendingSyncedTransactions: Array<
     PendingSyncedTransaction<TOutput, TKey>
   > = []
-  public syncedData: Map<TKey, TOutput> | SortedMap<TKey, TOutput>
+  public syncedData: SortedMap<TKey, TOutput>
   public syncedMetadata = new Map<TKey, unknown>()
 
   // Optimistic state tracking - make public for testing
@@ -66,15 +68,12 @@ export class CollectionStateManager<
   constructor(config: CollectionConfig<TOutput, TKey, TSchema>) {
     this.config = config
     this.transactions = new SortedMap<string, Transaction<any>>((a, b) =>
-      a.compareCreatedAt(b)
+      a.compareCreatedAt(b),
     )
 
-    // Set up data storage with optional comparison function
-    if (config.compare) {
-      this.syncedData = new SortedMap<TKey, TOutput>(config.compare)
-    } else {
-      this.syncedData = new Map<TKey, TOutput>()
-    }
+    // Set up data storage - always use SortedMap for deterministic iteration.
+    // If a custom compare function is provided, use it; otherwise entries are sorted by key only.
+    this.syncedData = new SortedMap<TKey, TOutput>(config.compare)
   }
 
   setDeps(deps: {
@@ -82,11 +81,13 @@ export class CollectionStateManager<
     lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
     changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>
     indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>
+    events: CollectionEventsManager
   }) {
     this.collection = deps.collection
     this.lifecycle = deps.lifecycle
     this.changes = deps.changes
     this.indexes = deps.indexes
+    this._events = deps.events
   }
 
   /**
@@ -185,7 +186,7 @@ export class CollectionStateManager<
    * Execute a callback for each entry in the collection
    */
   public forEach(
-    callbackfn: (value: TOutput, key: TKey, index: number) => void
+    callbackfn: (value: TOutput, key: TKey, index: number) => void,
   ): void {
     let index = 0
     for (const [key, value] of this.entries()) {
@@ -197,7 +198,7 @@ export class CollectionStateManager<
    * Create a new array with the results of calling a function for each entry in the collection
    */
   public map<U>(
-    callbackfn: (value: TOutput, key: TKey, index: number) => U
+    callbackfn: (value: TOutput, key: TKey, index: number) => U,
   ): Array<U> {
     const result: Array<U> = []
     let index = 0
@@ -213,7 +214,7 @@ export class CollectionStateManager<
    * @returns True if the given collection is this collection, false otherwise
    */
   private isThisCollection(
-    collection: CollectionImpl<any, any, any, any, any>
+    collection: CollectionImpl<any, any, any, any, any>,
   ): boolean {
     return collection === this.collection
   }
@@ -222,7 +223,7 @@ export class CollectionStateManager<
    * Recompute optimistic state from active transactions
    */
   public recomputeOptimisticState(
-    triggeredByUserAction: boolean = false
+    triggeredByUserAction: boolean = false,
   ): void {
     // Skip redundant recalculations when we're in the middle of committing sync transactions
     // While the sync pipeline is replaying a large batch we still want to honour
@@ -257,7 +258,7 @@ export class CollectionStateManager<
             case `update`:
               this.optimisticUpserts.set(
                 mutation.key,
-                mutation.modified as TOutput
+                mutation.modified as TOutput,
               )
               this.optimisticDeletes.delete(mutation.key)
               break
@@ -316,8 +317,8 @@ export class CollectionStateManager<
           // We can infer this by checking if we have no remaining optimistic mutations for this key
           const hasActiveOptimisticMutation = activeTransactions.some((tx) =>
             tx.mutations.some(
-              (m) => this.isThisCollection(m.collection) && m.key === event.key
-            )
+              (m) => this.isThisCollection(m.collection) && m.key === event.key,
+            ),
           )
 
           if (!hasActiveOptimisticMutation) {
@@ -348,10 +349,10 @@ export class CollectionStateManager<
   private calculateSize(): number {
     const syncedSize = this.syncedData.size
     const deletesFromSynced = Array.from(this.optimisticDeletes).filter(
-      (key) => this.syncedData.has(key) && !this.optimisticUpserts.has(key)
+      (key) => this.syncedData.has(key) && !this.optimisticUpserts.has(key),
     ).length
     const upsertsNotInSynced = Array.from(this.optimisticUpserts.keys()).filter(
-      (key) => !this.syncedData.has(key)
+      (key) => !this.syncedData.has(key),
     ).length
 
     return syncedSize - deletesFromSynced + upsertsNotInSynced
@@ -363,7 +364,7 @@ export class CollectionStateManager<
   private collectOptimisticChanges(
     previousUpserts: Map<TKey, TOutput>,
     previousDeletes: Set<TKey>,
-    events: Array<ChangeMessage<TOutput, TKey>>
+    events: Array<ChangeMessage<TOutput, TKey>>,
   ): void {
     const allKeys = new Set([
       ...previousUpserts.keys(),
@@ -377,7 +378,7 @@ export class CollectionStateManager<
       const previousValue = this.getPreviousValue(
         key,
         previousUpserts,
-        previousDeletes
+        previousDeletes,
       )
 
       if (previousValue !== undefined && currentValue === undefined) {
@@ -405,7 +406,7 @@ export class CollectionStateManager<
   private getPreviousValue(
     key: TKey,
     previousUpserts: Map<TKey, TOutput>,
-    previousDeletes: Set<TKey>
+    previousDeletes: Set<TKey>,
   ): TOutput | undefined {
     if (previousDeletes.has(key)) {
       return undefined
@@ -456,7 +457,7 @@ export class CollectionStateManager<
           PendingSyncedTransaction<TOutput, TKey>
         >,
         hasTruncateSync: false,
-      }
+      },
     )
 
     if (!hasPersistingTransaction || hasTruncateSync) {
@@ -528,6 +529,12 @@ export class CollectionStateManager<
           for (const key of changedKeys) {
             currentVisibleState.delete(key)
           }
+
+          // 4) Emit truncate event so subscriptions can reset their cursor tracking state
+          this._events.emit(`truncate`, {
+            type: `truncate`,
+            collection: this.collection,
+          })
         }
 
         for (const operation of transaction.operations) {
@@ -545,8 +552,8 @@ export class CollectionStateManager<
                 Object.assign(
                   {},
                   this.syncedMetadata.get(key),
-                  operation.metadata
-                )
+                  operation.metadata,
+                ),
               )
               break
             case `delete`:
@@ -564,7 +571,7 @@ export class CollectionStateManager<
                 const updatedValue = Object.assign(
                   {},
                   this.syncedData.get(key),
-                  operation.value
+                  operation.value,
                 )
                 this.syncedData.set(key, updatedValue)
               } else {
@@ -597,10 +604,10 @@ export class CollectionStateManager<
         // Build re-apply sets from the snapshot taken at the start of this function.
         // This prevents losing optimistic state if transactions complete during truncate processing.
         const reapplyUpserts = new Map<TKey, TOutput>(
-          truncateOptimisticSnapshot!.upserts
+          truncateOptimisticSnapshot!.upserts,
         )
         const reapplyDeletes = new Set<TKey>(
-          truncateOptimisticSnapshot!.deletes
+          truncateOptimisticSnapshot!.deletes,
         )
 
         // Emit inserts for re-applied upserts, skipping any keys that have an optimistic delete.
@@ -679,7 +686,7 @@ export class CollectionStateManager<
                 case `update`:
                   this.optimisticUpserts.set(
                     mutation.key,
-                    mutation.modified as TOutput
+                    mutation.modified as TOutput,
                   )
                   this.optimisticDeletes.delete(mutation.key)
                   break

package/src/collection/subscription.ts

@@ -1,13 +1,14 @@
-import { ensureIndexForExpression } from "../indexes/auto-index.js"
-import { and, eq, gt, gte, lt } from "../query/builder/functions.js"
-import { Value } from "../query/ir.js"
-import { EventEmitter } from "../event-emitter.js"
+import { ensureIndexForExpression } from '../indexes/auto-index.js'
+import { and, eq, gte, lt } from '../query/builder/functions.js'
+import { Value } from '../query/ir.js'
+import { EventEmitter } from '../event-emitter.js'
+import { buildCursor } from '../utils/cursor.js'
 import {
   createFilterFunctionFromExpression,
   createFilteredCallback,
-} from "./change-events.js"
-import type { BasicExpression, OrderBy } from "../query/ir.js"
-import type { IndexInterface } from "../indexes/base-index.js"
+} from './change-events.js'
+import type { BasicExpression, OrderBy } from '../query/ir.js'
+import type { IndexInterface } from '../indexes/base-index.js'
 import type {
   ChangeMessage,
   LoadSubsetOptions,
@@ -15,19 +16,26 @@ import type {
   SubscriptionEvents,
   SubscriptionStatus,
   SubscriptionUnsubscribedEvent,
-} from "../types.js"
-import type { CollectionImpl } from "./index.js"
+} from '../types.js'
+import type { CollectionImpl } from './index.js'
 
 type RequestSnapshotOptions = {
   where?: BasicExpression<boolean>
   optimizedOnly?: boolean
   trackLoadSubsetPromise?: boolean
+  /** Optional orderBy to pass to loadSubset for backend optimization */
+  orderBy?: OrderBy
+  /** Optional limit to pass to loadSubset for backend optimization */
+  limit?: number
 }
 
 type RequestLimitedSnapshotOptions = {
   orderBy: OrderBy
   limit: number
-  minValue?: any
+  /** All column values for cursor (first value used for local index, all values for sync layer) */
+  minValues?: Array<unknown>
+  /** Row offset for offset-based pagination (passed to sync layer) */
+  offset?: number
 }
 
 type CollectionSubscriptionOptions = {
@@ -44,6 +52,11 @@ export class CollectionSubscription
 {
   private loadedInitialState = false
 
+  // Flag to skip filtering in filterAndFlipChanges.
+  // This is separate from loadedInitialState because we want to allow
+  // requestSnapshot to still work even when filtering is skipped.
+  private skipFiltering = false
+
   // Flag to indicate that we have sent at least 1 snapshot.
   // While `snapshotSent` is false we filter out all changes from subscription to the collection.
   private snapshotSent = false
@@ -57,6 +70,12 @@ export class CollectionSubscription
   // Keep track of the keys we've sent (needed for join and orderBy optimizations)
   private sentKeys = new Set<string | number>()
 
+  // Track the count of rows sent via requestLimitedSnapshot for offset-based pagination
+  private limitedSnapshotRowCount = 0
+
+  // Track the last key sent via requestLimitedSnapshot for cursor-based pagination
+  private lastSentKey: string | number | undefined
+
   private filteredCallback: (changes: Array<ChangeMessage<any, any>>) => void
 
   private orderByIndex: IndexInterface<string | number> | undefined
@@ -72,7 +91,7 @@ export class CollectionSubscription
   constructor(
     private collection: CollectionImpl<any, any, any, any, any>,
     private callback: (changes: Array<ChangeMessage<any, any>>) => void,
-    private options: CollectionSubscriptionOptions
+    private options: CollectionSubscriptionOptions,
   ) {
     super()
     if (options.onUnsubscribe) {
@@ -85,7 +104,7 @@ export class CollectionSubscription
     }
 
     const callbackWithSentKeysTracking = (
-      changes: Array<ChangeMessage<any, any>>
+      changes: Array<ChangeMessage<any, any>>,
     ) => {
       callback(changes)
       this.trackSentKeys(changes)
@@ -203,6 +222,9 @@ export class CollectionSubscription
     const loadOptions: LoadSubsetOptions = {
       where: stateOpts.where,
       subscription: this,
+      // Include orderBy and limit if provided so sync layer can optimize the query
+      orderBy: opts?.orderBy,
+      limit: opts?.limit,
     }
     const syncResult = this.collection._sync.loadSubset(loadOptions)
 
@@ -224,35 +246,53 @@ export class CollectionSubscription
 
     // Only send changes that have not been sent yet
     const filteredSnapshot = snapshot.filter(
-      (change) => !this.sentKeys.has(change.key)
+      (change) => !this.sentKeys.has(change.key),
     )
 
+    // Add keys to sentKeys BEFORE calling callback to prevent race condition.
+    // If a change event arrives while the callback is executing, it will see
+    // the keys already in sentKeys and filter out duplicates correctly.
+    for (const change of filteredSnapshot) {
+      this.sentKeys.add(change.key)
+    }
+
     this.snapshotSent = true
     this.callback(filteredSnapshot)
     return true
   }
 
   /**
-   * Sends a snapshot that fulfills the `where` clause and all rows are bigger or equal to `minValue`.
+   * Sends a snapshot that fulfills the `where` clause and all rows are bigger or equal to the cursor.
    * Requires a range index to be set with `setOrderByIndex` prior to calling this method.
    * It uses that range index to load the items in the order of the index.
-   * Note 1: it may load more rows than the provided LIMIT because it loads all values equal to `minValue` + limit values greater than `minValue`.
+   *
+   * For multi-column orderBy:
+   * - Uses first value from `minValues` for LOCAL index operations (wide bounds, ensures no missed rows)
+   * - Uses all `minValues` to build a precise composite cursor for SYNC layer loadSubset
+   *
+   * Note 1: it may load more rows than the provided LIMIT because it loads all values equal to the first cursor value + limit values greater.
    *         This is needed to ensure that it does not accidentally skip duplicate values when the limit falls in the middle of some duplicated values.
    * Note 2: it does not send keys that have already been sent before.
    */
   requestLimitedSnapshot({
     orderBy,
     limit,
-    minValue,
+    minValues,
+    offset,
   }: RequestLimitedSnapshotOptions) {
     if (!limit) throw new Error(`limit is required`)
 
     if (!this.orderByIndex) {
       throw new Error(
-        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`
+        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`,
       )
     }
 
+    // Derive first column value from minValues (used for local index operations)
+    const minValue = minValues?.[0]
+    // Cast for index operations (index expects string | number)
+    const minValueForIndex = minValue as string | number | undefined
+
     const index = this.orderByIndex
     const where = this.options.whereExpression
     const whereFilterFn = where
@@ -272,7 +312,7 @@ export class CollectionSubscription
       return whereFilterFn?.(value) ?? true
     }
 
-    let biggestObservedValue = minValue
+    let biggestObservedValue = minValueForIndex
     const changes: Array<ChangeMessage<any, string | number>> = []
 
     // If we have a minValue we need to handle the case
@@ -281,12 +321,16 @@ export class CollectionSubscription
     // so if minValue is 3 then the previous snapshot may not have included all 3s
     // e.g. if it was offset 0 and limit 3 it would only have loaded the first 3
     //      so we load all rows equal to minValue first, to be sure we don't skip any duplicate values
+    //
+    // For multi-column orderBy, we use the first column value for index operations (wide bounds)
+    // This may load some duplicates but ensures we never miss any rows.
     let keys: Array<string | number> = []
-    if (minValue !== undefined) {
-      // First, get all items with the same value as minValue
+    if (minValueForIndex !== undefined) {
+      // First, get all items with the same FIRST COLUMN value as minValue
+      // This provides wide bounds for the local index
       const { expression } = orderBy[0]!
       const allRowsWithMinValue = this.collection.currentStateAsChanges({
-        where: eq(expression, new Value(minValue)),
+        where: eq(expression, new Value(minValueForIndex)),
       })
 
       if (allRowsWithMinValue) {
@@ -300,15 +344,15 @@ export class CollectionSubscription
         // Then get items greater than minValue
         const keysGreaterThanMin = index.take(
           limit - keys.length,
-          minValue,
-          filterFn
+          minValueForIndex,
+          filterFn,
         )
         keys.push(...keysGreaterThanMin)
       } else {
-        keys = index.take(limit, minValue, filterFn)
+        keys = index.take(limit, minValueForIndex, filterFn)
       }
     } else {
-      keys = index.take(limit, minValue, filterFn)
+      keys = index.take(limit, minValueForIndex, filterFn)
     }
 
     const valuesNeeded = () => Math.max(limit - changes.length, 0)
@@ -331,76 +375,82 @@ export class CollectionSubscription
       keys = index.take(valuesNeeded(), biggestObservedValue, filterFn)
     }
 
+    // Track row count for offset-based pagination (before sending to callback)
+    // Use the current count as the offset for this load
+    const currentOffset = this.limitedSnapshotRowCount
+
+    // Add keys to sentKeys BEFORE calling callback to prevent race condition.
+    // If a change event arrives while the callback is executing, it will see
+    // the keys already in sentKeys and filter out duplicates correctly.
+    for (const change of changes) {
+      this.sentKeys.add(change.key)
+    }
+
     this.callback(changes)
 
-    let whereWithValueFilter = where
-    if (typeof minValue !== `undefined`) {
-      // Only request data that we haven't seen yet (i.e. is bigger than the minValue)
-      const { expression, compareOptions } = orderBy[0]!
-      const operator = compareOptions.direction === `asc` ? gt : lt
-      const valueFilter = operator(expression, new Value(minValue))
-      whereWithValueFilter = where ? and(where, valueFilter) : valueFilter
+    // Update the row count and last key after sending (for next call's offset/cursor)
+    this.limitedSnapshotRowCount += changes.length
+    if (changes.length > 0) {
+      this.lastSentKey = changes[changes.length - 1]!.key
+    }
+
+    // Build cursor expressions for sync layer loadSubset
+    // The cursor expressions are separate from the main where clause
+    // so the sync layer can choose cursor-based or offset-based pagination
+    let cursorExpressions:
+      | {
+          whereFrom: BasicExpression<boolean>
+          whereCurrent: BasicExpression<boolean>
+          lastKey?: string | number
+        }
+      | undefined
+
+    if (minValues !== undefined && minValues.length > 0) {
+      const whereFromCursor = buildCursor(orderBy, minValues)
+
+      if (whereFromCursor) {
+        const { expression } = orderBy[0]!
+        const minValue = minValues[0]
+
+        // Build the whereCurrent expression for the first orderBy column
+        // For Date values, we need to handle precision differences between JS (ms) and backends (μs)
+        // A JS Date represents a 1ms range, so we query for all values within that range
+        let whereCurrentCursor: BasicExpression<boolean>
+        if (minValue instanceof Date) {
+          const minValuePlus1ms = new Date(minValue.getTime() + 1)
+          whereCurrentCursor = and(
+            gte(expression, new Value(minValue)),
+            lt(expression, new Value(minValuePlus1ms)),
+          )
+        } else {
+          whereCurrentCursor = eq(expression, new Value(minValue))
+        }
+
+        cursorExpressions = {
+          whereFrom: whereFromCursor,
+          whereCurrent: whereCurrentCursor,
+          lastKey: this.lastSentKey,
+        }
+      }
     }
 
     // Request the sync layer to load more data
     // don't await it, we will load the data into the collection when it comes in
-    const loadOptions1: LoadSubsetOptions = {
-      where: whereWithValueFilter,
+    // Note: `where` does NOT include cursor expressions - they are passed separately
+    // The sync layer can choose to use cursor-based or offset-based pagination
+    const loadOptions: LoadSubsetOptions = {
+      where, // Main filter only, no cursor
       limit,
       orderBy,
+      cursor: cursorExpressions, // Cursor expressions passed separately
+      offset: offset ?? currentOffset, // Use provided offset, or auto-tracked offset
       subscription: this,
     }
-    const syncResult = this.collection._sync.loadSubset(loadOptions1)
+    const syncResult = this.collection._sync.loadSubset(loadOptions)
 
     // Track this loadSubset call
-    this.loadedSubsets.push(loadOptions1)
-
-    // Make parallel loadSubset calls for values equal to minValue and values greater than minValue
-    const promises: Array<Promise<void>> = []
-
-    // First promise: load all values equal to minValue
-    if (typeof minValue !== `undefined`) {
-      const { expression } = orderBy[0]!
-
-      // For Date values, we need to handle precision differences between JS (ms) and backends (μs)
-      // A JS Date represents a 1ms range, so we query for all values within that range
-      let exactValueFilter
-      if (minValue instanceof Date) {
-        const minValuePlus1ms = new Date(minValue.getTime() + 1)
-        exactValueFilter = and(
-          gte(expression, new Value(minValue)),
-          lt(expression, new Value(minValuePlus1ms))
-        )
-      } else {
-        exactValueFilter = eq(expression, new Value(minValue))
-      }
-
-      const loadOptions2: LoadSubsetOptions = {
-        where: exactValueFilter,
-        subscription: this,
-      }
-      const equalValueResult = this.collection._sync.loadSubset(loadOptions2)
-
-      // Track this loadSubset call
-      this.loadedSubsets.push(loadOptions2)
-
-      if (equalValueResult instanceof Promise) {
-        promises.push(equalValueResult)
-      }
-    }
-
-    // Second promise: load values greater than minValue
-    if (syncResult instanceof Promise) {
-      promises.push(syncResult)
-    }
-
-    // Track the combined promise
-    if (promises.length > 0) {
-      const combinedPromise = Promise.all(promises).then(() => {})
-      this.trackLoadSubsetPromise(combinedPromise)
-    } else {
-      this.trackLoadSubsetPromise(syncResult)
-    }
+    this.loadedSubsets.push(loadOptions)
+    this.trackLoadSubsetPromise(syncResult)
   }
 
   // TODO: also add similar test but that checks that it can also load it from the collection's loadSubset function
@@ -410,10 +460,11 @@ export class CollectionSubscription
    * Filters and flips changes for keys that have not been sent yet.
    * Deletes are filtered out for keys that have not been sent yet.
    * Updates are flipped into inserts for keys that have not been sent yet.
+   * Duplicate inserts are filtered out to prevent D2 multiplicity > 1.
    */
   private filterAndFlipChanges(changes: Array<ChangeMessage<any, any>>) {
-    if (this.loadedInitialState) {
-      // We loaded the entire initial state
+    if (this.loadedInitialState || this.skipFiltering) {
+      // We loaded the entire initial state or filtering is explicitly skipped
       // so no need to filter or flip changes
       return changes
     }
@@ -421,7 +472,9 @@ export class CollectionSubscription
     const newChanges = []
     for (const change of changes) {
       let newChange = change
-      if (!this.sentKeys.has(change.key)) {
+      const keyInSentKeys = this.sentKeys.has(change.key)
+
+      if (!keyInSentKeys) {
         if (change.type === `update`) {
           newChange = { ...change, type: `insert`, previousValue: undefined }
         } else if (change.type === `delete`) {
@@ -429,6 +482,19 @@ export class CollectionSubscription
           continue
         }
         this.sentKeys.add(change.key)
+      } else {
+        // Key was already sent - handle based on change type
+        if (change.type === `insert`) {
+          // Filter out duplicate inserts - the key was already inserted.
+          // This prevents D2 multiplicity from going above 1, which would
+          // cause deletes to not properly remove items (multiplicity would
+          // go from 2 to 1 instead of 1 to 0).
+          continue
+        } else if (change.type === `delete`) {
+          // Remove from sentKeys so future inserts for this key are allowed
+          // (e.g., after truncate + reinsert)
+          this.sentKeys.delete(change.key)
+        }
       }
       newChanges.push(newChange)
     }
@@ -436,17 +502,32 @@ export class CollectionSubscription
   }
 
   private trackSentKeys(changes: Array<ChangeMessage<any, string | number>>) {
-    if (this.loadedInitialState) {
-      // No need to track sent keys if we loaded the entire state.
-      // Since we sent everything, all keys must have been observed.
+    if (this.loadedInitialState || this.skipFiltering) {
+      // No need to track sent keys if we loaded the entire state or filtering is skipped.
+      // Since filtering won't be applied, all keys are effectively "observed".
       return
     }
 
     for (const change of changes) {
-      this.sentKeys.add(change.key)
+      if (change.type === `delete`) {
+        // Remove deleted keys from sentKeys so future re-inserts are allowed
+        this.sentKeys.delete(change.key)
+      } else {
+        // For inserts and updates, track the key as sent
+        this.sentKeys.add(change.key)
+      }
     }
   }
 
+  /**
+   * Mark that the subscription should not filter any changes.
+   * This is used when includeInitialState is explicitly set to false,
+   * meaning the caller doesn't want initial state but does want ALL future changes.
+   */
+  markAllStateAsSeen() {
+    this.skipFiltering = true
+  }
+
   unsubscribe() {
     // Unload all subsets that this subscription loaded
     // We pass the exact same LoadSubsetOptions we used for loadSubset