Fix optimistic state not being replaced by server data in writeInsert

Fixes #814

When writeInsert() is called from within an onInsert handler, the
transaction is in 'persisting' state. Previously, commitPendingTransactions()
would re-apply optimistic state from all persisting transactions after syncing
server data, causing server-generated fields to be overwritten with
optimistic client-side values.

This fix prevents re-applying optimistic state from persisting transactions
for keys that were just synced, but only for non-truncate operations. Truncate
operations still preserve optimistic state as expected.

The flow now works correctly:
1. User inserts item with temporary ID -> optimistic state shows temp ID
2. Transaction commits -> onInsert handler called (state = 'persisting')
3. Handler calls writeInsert(serverItem) with real ID
4. commitPendingTransactions() syncs server data for that key
5. Optimistic state from persisting transaction is NOT re-applied for that key
6. UI now shows server data with real ID
7. Transaction completes -> optimistic state is cleared

For truncate operations, optimistic state is always preserved to ensure
transactions started after the truncate snapshot are maintained.

Author: claude

.changeset/fix-writeinsert-optimistic-state.md

@@ -0,0 +1,39 @@
+---
+"@tanstack/db": patch
+---
+
+Fix optimistic state not being replaced by server data when using writeInsert in mutation handlers
+
+Previously, when using `writeInsert()` inside an `onInsert` handler to sync server-generated data back to the collection, the optimistic client-side data would not be replaced by the actual server data. This meant that temporary client-side values (like negative IDs) would persist even after the server returned the real values.
+
+**Example of the issue:**
+
+```ts
+const todosCollection = createCollection(
+  queryCollectionOptions({
+    // ...
+    onInsert: async ({ transaction }) => {
+      const newItems = transaction.mutations.map((m) => m.modified)
+      const serverItems = await createTodos(newItems)
+
+      todosCollection.utils.writeBatch(() => {
+        serverItems.forEach((serverItem) => {
+          todosCollection.utils.writeInsert(serverItem)
+        })
+      })
+
+      return { refetch: false }
+    },
+  })
+)
+
+// User inserts with temporary ID
+todosCollection.insert({
+  id: -1234, // Temporary negative ID
+  title: "Task",
+})
+
+// Server returns real ID, but UI would still show -1234 instead of the real ID
+```
+
+This has been fixed by preventing optimistic state from `persisting` transactions from being re-applied during server data synchronization. The UI now correctly updates to show server-generated values once they are synced via `writeInsert()`.

packages/db/src/collection/state.ts

@@ -674,6 +674,17 @@ export class CollectionStateManager<
               this.isThisCollection(mutation.collection) &&
               mutation.optimistic
             ) {
+              // Skip re-applying optimistic state for persisting transactions
+              // if the mutation key was just synced (prevents overwriting fresh server data)
+              // EXCEPT during truncate operations where optimistic state should always be preserved
+              if (
+                !hasTruncateSync &&
+                transaction.state === `persisting` &&
+                changedKeys.has(mutation.key)
+              ) {
+                continue
+              }
+
               switch (mutation.type) {
                 case `insert`:
                 case `update`: