@livestore/common 0.3.0-dev.9 → 0.3.1-dev.0

package/src/sync/syncstate.ts

@@ -1,223 +1,314 @@
-import { shouldNeverHappen } from '@livestore/utils'
-import { ReadonlyArray, Schema } from '@livestore/utils/effect'
+import { casesHandled, LS_DEV, shouldNeverHappen } from '@livestore/utils'
+import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
-import * as EventId from '../schema/EventId.js'
-import * as MutationEvent from '../schema/MutationEvent.js'
+import { UnexpectedError } from '../adapter-types.js'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber.js'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
 
 /**
  * SyncState represents the current sync state of a sync node relative to an upstream node.
  * Events flow from local to upstream, with each state maintaining its own event head.
  *
- * Event Chain Structure:
+ * Example:
  * ```
- *                 +-------------------------+------------------------+
- *                 |      ROLLBACK TAIL      |     PENDING EVENTS     |
- *                 +-------------------------+------------------------+
- *                                         ▼                       ▼
- *                                  Upstream Head             Local Head
- *   Example:              (0,0), (0,1), (1,0)     (1,1), (1,2), (2,0)
+ *                 +------------------------+
+ *                 |     PENDING EVENTS     |
+ *                 +------------------------+
+ *               ▼                       ▼
+ *        Upstream Head             Local Head
+ *             (1,0)     (1,1), (1,2), (2,0)
  * ```
  *
- * State:
- * - **Pending Events**: Events awaiting acknowledgment from the upstream.
- *   - Can be confirmed or rejected by the upstream.
- *   - Subject to rebase if rejected.
- * - **Rollback Tail**: Events that are kept around temporarily for potential rollback until confirmed by upstream.
+ * **Pending Events**: Events awaiting acknowledgment from the upstream.
+ * - Can be confirmed or rejected by the upstream.
+ * - Subject to rebase if rejected.
  *
  * Payloads:
  * - `PayloadUpstreamRebase`: Upstream has performed a rebase, so downstream must roll back to the specified event
  *    and rebase the pending events on top of the new events.
  * - `PayloadUpstreamAdvance`: Upstream has advanced, so downstream must rebase the pending events on top of the new events.
- * - `PayloadUpstreamTrimRollbackTail`: Upstream has advanced, so downstream can trim the rollback tail.
  * - `PayloadLocalPush`: Local push payload
  *
  * Invariants:
  * 1. **Chain Continuity**: Each event must reference its immediate parent.
  * 2. **Head Ordering**: Upstream Head ≤ Local Head.
- * 3. **ID Sequence**: Must follow the pattern (1,0)→(1,1)→(1,2)→(2,0).
+ * 3. **Event number sequence**: Must follow the pattern (1,0)→(1,1)→(1,2)→(2,0).
  *
- * The `updateSyncState` function processes updates to the sync state based on incoming payloads,
- * handling cases such as upstream rebase, advance, local push, and rollback tail trimming.
+ * A few further notes to help form an intuition:
+ * - The goal is to keep the pending events as small as possible (i.e. to have synced with the next upstream node)
+ * - There are 2 cases for rebasing:
+ *   - The conflicting event only conflicts with the pending events -> only (some of) the pending events need to be rolled back
+ *
+ * The `merge` function processes updates to the sync state based on incoming payloads,
+ * handling cases such as upstream rebase, advance and local push.
  */
 export class SyncState extends Schema.Class<SyncState>('SyncState')({
-  pending: Schema.Array(MutationEvent.EncodedWithMeta),
-  rollbackTail: Schema.Array(MutationEvent.EncodedWithMeta),
-  upstreamHead: EventId.EventId,
-  localHead: EventId.EventId,
+  pending: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  /** What this node expects the next upstream node to have as its own local head */
+  upstreamHead: EventSequenceNumber.EventSequenceNumber,
+  /** Equivalent to `pending.at(-1)?.id` if there are pending events */
+  localHead: EventSequenceNumber.EventSequenceNumber,
 }) {
-  toJSON = (): any => {
-    return {
-      pending: this.pending.map((e) => e.toJSON()),
-      rollbackTail: this.rollbackTail.map((e) => e.toJSON()),
-      upstreamHead: `(${this.upstreamHead.global},${this.upstreamHead.local})`,
-      localHead: `(${this.localHead.global},${this.localHead.local})`,
-    }
-  }
+  toJSON = (): any => ({
+    pending: this.pending.map((e) => e.toJSON()),
+    upstreamHead: EventSequenceNumber.toString(this.upstreamHead),
+    localHead: EventSequenceNumber.toString(this.localHead),
+  })
 }
 
+/**
+ * This payload propagates a rebase from the upstream node
+ */
 export class PayloadUpstreamRebase extends Schema.TaggedStruct('upstream-rebase', {
-  /** Rollback until this event in the rollback tail (inclusive). Starting from the end of the rollback tail. */
-  rollbackUntil: EventId.EventId,
-  newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
-  /** Trim rollback tail up to this event (inclusive). */
-  trimRollbackUntil: Schema.optional(EventId.EventId),
+  /** Events which need to be rolled back */
+  rollbackEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  /** Events which need to be applied after the rollback (already rebased by the upstream node) */
+  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
 }) {}
 
 export class PayloadUpstreamAdvance extends Schema.TaggedStruct('upstream-advance', {
-  newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
-  /** Trim rollback tail up to this event (inclusive). */
-  trimRollbackUntil: Schema.optional(EventId.EventId),
+  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
 }) {}
 
 export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
-  newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
 }) {}
 
 export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {}
 
-export const PayloadUpstream = Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance)
+export class PayloadUpstream extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance) {}
 
-export type PayloadUpstream = typeof PayloadUpstream.Type
+/** Only used for debugging purposes */
+export class MergeContext extends Schema.Class<MergeContext>('MergeContext')({
+  payload: Payload,
+  syncState: SyncState,
+}) {
+  toJSON = (): any => {
+    const payload = Match.value(this.payload).pipe(
+      Match.tag('local-push', () => ({
+        _tag: 'local-push',
+        newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+      })),
+      Match.tag('upstream-advance', () => ({
+        _tag: 'upstream-advance',
+        newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+      })),
+      Match.tag('upstream-rebase', (payload) => ({
+        _tag: 'upstream-rebase',
+        newEvents: payload.newEvents.map((e) => e.toJSON()),
+        rollbackEvents: payload.rollbackEvents.map((e) => e.toJSON()),
+      })),
+      Match.exhaustive,
+    )
+    return {
+      payload,
+      syncState: this.syncState.toJSON(),
+    }
+  }
+}
 
-export type UpdateResultAdvance = {
-  _tag: 'advance'
-  newSyncState: SyncState
-  previousSyncState: SyncState
-  /** Events which weren't pending before the update */
-  newEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>
+export class MergeResultAdvance extends Schema.Class<MergeResultAdvance>('MergeResultAdvance')({
+  _tag: Schema.Literal('advance'),
+  newSyncState: SyncState,
+  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  /** Events which were previously pending but are now confirmed */
+  confirmedEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  mergeContext: MergeContext,
+}) {
+  toJSON = (): any => {
+    return {
+      _tag: this._tag,
+      newSyncState: this.newSyncState.toJSON(),
+      newEvents: this.newEvents.map((e) => e.toJSON()),
+      confirmedEvents: this.confirmedEvents.map((e) => e.toJSON()),
+      mergeContext: this.mergeContext.toJSON(),
+    }
+  }
 }
 
-export type UpdateResultRebase = {
-  _tag: 'rebase'
-  newSyncState: SyncState
-  previousSyncState: SyncState
-  /** Events which weren't pending before the update */
-  newEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>
-  eventsToRollback: ReadonlyArray<MutationEvent.EncodedWithMeta>
+export class MergeResultRebase extends Schema.Class<MergeResultRebase>('MergeResultRebase')({
+  _tag: Schema.Literal('rebase'),
+  newSyncState: SyncState,
+  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  /** Events which need to be rolled back */
+  rollbackEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  mergeContext: MergeContext,
+}) {
+  toJSON = (): any => {
+    return {
+      _tag: this._tag,
+      newSyncState: this.newSyncState.toJSON(),
+      newEvents: this.newEvents.map((e) => e.toJSON()),
+      rollbackEvents: this.rollbackEvents.map((e) => e.toJSON()),
+      mergeContext: this.mergeContext.toJSON(),
+    }
+  }
 }
 
-export type UpdateResultReject = {
-  _tag: 'reject'
-  previousSyncState: SyncState
+export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeResultReject')({
+  _tag: Schema.Literal('reject'),
   /** The minimum id that the new events must have */
-  expectedMinimumId: EventId.EventId
+  expectedMinimumId: EventSequenceNumber.EventSequenceNumber,
+  mergeContext: MergeContext,
+}) {
+  toJSON = (): any => {
+    return {
+      _tag: this._tag,
+      expectedMinimumId: EventSequenceNumber.toString(this.expectedMinimumId),
+      mergeContext: this.mergeContext.toJSON(),
+    }
+  }
 }
 
-export type UpdateResult = UpdateResultAdvance | UpdateResultRebase | UpdateResultReject
+export class MergeResultUnexpectedError extends Schema.Class<MergeResultUnexpectedError>('MergeResultUnexpectedError')({
+  _tag: Schema.Literal('unexpected-error'),
+  cause: UnexpectedError,
+}) {}
+
+export class MergeResult extends Schema.Union(
+  MergeResultAdvance,
+  MergeResultRebase,
+  MergeResultReject,
+  MergeResultUnexpectedError,
+) {}
+
+const unexpectedError = (cause: unknown): MergeResultUnexpectedError => {
+  if (LS_DEV) {
+    debugger
+  }
+
+  return MergeResultUnexpectedError.make({
+    _tag: 'unexpected-error',
+    cause: new UnexpectedError({ cause }),
+  })
+}
 
-export const updateSyncState = ({
+// TODO Idea: call merge recursively through hierarchy levels
+/*
+Idea: have a map that maps from `globalEventSequenceNumber` to Array<ClientEvents>
+The same applies to even further hierarchy levels
+
+TODO: possibly even keep the client events in a separate table in the client leader
+*/
+export const merge = ({
   syncState,
   payload,
-  isLocalEvent,
+  isClientEvent,
   isEqualEvent,
-  ignoreLocalEvents = false,
+  ignoreClientEvents = false,
 }: {
   syncState: SyncState
   payload: typeof Payload.Type
-  isLocalEvent: (event: MutationEvent.EncodedWithMeta) => boolean
-  isEqualEvent: (a: MutationEvent.EncodedWithMeta, b: MutationEvent.EncodedWithMeta) => boolean
-  /** This is used in the leader which should ignore local events when receiving an upstream-advance payload */
-  ignoreLocalEvents?: boolean
-}): UpdateResult => {
-  const trimRollbackTail = (
-    rollbackTail: ReadonlyArray<MutationEvent.EncodedWithMeta>,
-  ): ReadonlyArray<MutationEvent.EncodedWithMeta> => {
-    const trimRollbackUntil = payload._tag === 'local-push' ? undefined : payload.trimRollbackUntil
-    if (trimRollbackUntil === undefined) return rollbackTail
-    const index = rollbackTail.findIndex((event) => EventId.isEqual(event.id, trimRollbackUntil))
-    if (index === -1) return []
-    return rollbackTail.slice(index + 1)
-  }
+  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
+  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
+  /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
+  ignoreClientEvents?: boolean
+}): typeof MergeResult.Type => {
+  validateSyncState(syncState)
+  validatePayload(payload)
+
+  const mergeContext = MergeContext.make({ payload, syncState })
 
   switch (payload._tag) {
     case 'upstream-rebase': {
-      // Find the index of the rollback event in the rollback tail
-      const rollbackIndex = syncState.rollbackTail.findIndex((event) =>
-        EventId.isEqual(event.id, payload.rollbackUntil),
-      )
-      if (rollbackIndex === -1) {
-        return shouldNeverHappen(
-          `Rollback event not found in rollback tail. Rollback until: [${payload.rollbackUntil.global},${payload.rollbackUntil.local}]. Rollback tail: [${syncState.rollbackTail.map((e) => e.toString()).join(', ')}]`,
-        )
-      }
-
-      const eventsToRollback = [...syncState.rollbackTail.slice(rollbackIndex), ...syncState.pending]
+      const rollbackEvents = [...payload.rollbackEvents, ...syncState.pending]
 
       // Get the last new event's ID as the new upstream head
-      const newUpstreamHead = payload.newEvents.at(-1)?.id ?? syncState.upstreamHead
+      const newUpstreamHead = payload.newEvents.at(-1)?.seqNum ?? syncState.upstreamHead
 
       // Rebase pending events on top of the new events
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
-        baseEventId: newUpstreamHead,
-        isLocalEvent,
+        baseEventSequenceNumber: newUpstreamHead,
+        isClientEvent,
       })
 
-      return {
-        _tag: 'rebase',
-        newSyncState: new SyncState({
-          pending: rebasedPending,
-          rollbackTail: trimRollbackTail([...syncState.rollbackTail.slice(0, rollbackIndex), ...payload.newEvents]),
-          upstreamHead: newUpstreamHead,
-          localHead: rebasedPending.at(-1)?.id ?? newUpstreamHead,
+      return validateMergeResult(
+        MergeResultRebase.make({
+          _tag: 'rebase',
+          newSyncState: new SyncState({
+            pending: rebasedPending,
+            upstreamHead: newUpstreamHead,
+            localHead: rebasedPending.at(-1)?.seqNum ?? newUpstreamHead,
+          }),
+          newEvents: [...payload.newEvents, ...rebasedPending],
+          rollbackEvents,
+          mergeContext,
         }),
-        previousSyncState: syncState,
-        newEvents: payload.newEvents,
-        eventsToRollback,
-      }
+      )
     }
 
+    // #region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
-        return {
-          _tag: 'advance',
-          newSyncState: new SyncState({
-            pending: syncState.pending,
-            rollbackTail: trimRollbackTail(syncState.rollbackTail),
-            upstreamHead: syncState.upstreamHead,
-            localHead: syncState.localHead,
+        return validateMergeResult(
+          MergeResultAdvance.make({
+            _tag: 'advance',
+            newSyncState: new SyncState({
+              pending: syncState.pending,
+              upstreamHead: syncState.upstreamHead,
+              localHead: syncState.localHead,
+            }),
+            newEvents: [],
+            confirmedEvents: [],
+            mergeContext: mergeContext,
           }),
-          previousSyncState: syncState,
-          newEvents: [],
-        }
+        )
       }
 
-      // Validate that newEvents are sorted in ascending order by eventId
+      // Validate that newEvents are sorted in ascending order by eventNum
       for (let i = 1; i < payload.newEvents.length; i++) {
-        if (EventId.isGreaterThan(payload.newEvents[i - 1]!.id, payload.newEvents[i]!.id)) {
-          return shouldNeverHappen('Events must be sorted in ascending order by eventId')
+        if (EventSequenceNumber.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
+          return unexpectedError(
+            `Events must be sorted in ascending order by event number. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+          )
         }
       }
 
-      const newUpstreamHead = payload.newEvents.at(-1)!.id
+      // Validate that incoming events are larger than upstream head
+      if (
+        EventSequenceNumber.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) ||
+        EventSequenceNumber.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum)
+      ) {
+        return unexpectedError(
+          `Incoming events must be greater than upstream head. Expected greater than: ${EventSequenceNumber.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+        )
+      }
+
+      const newUpstreamHead = payload.newEvents.at(-1)!.seqNum
 
       const divergentPendingIndex = findDivergencePoint({
         existingEvents: syncState.pending,
         incomingEvents: payload.newEvents,
         isEqualEvent,
-        isLocalEvent,
-        ignoreLocalEvents,
+        isClientEvent,
+        ignoreClientEvents,
       })
 
+      // No divergent pending events, thus we can just advance (some of) the pending events
       if (divergentPendingIndex === -1) {
-        const pendingEventIds = new Set(syncState.pending.map((e) => `${e.id.global},${e.id.local}`))
-        const newEvents = payload.newEvents.filter((e) => !pendingEventIds.has(`${e.id.global},${e.id.local}`))
+        const pendingEventSequenceNumbers = new Set(
+          syncState.pending.map((e) => `${e.seqNum.global},${e.seqNum.client}`),
+        )
+        const newEvents = payload.newEvents.filter(
+          (e) => !pendingEventSequenceNumbers.has(`${e.seqNum.global},${e.seqNum.client}`),
+        )
 
         // In the case where the incoming events are a subset of the pending events,
         // we need to split the pending events into two groups:
         // - pendingMatching: The pending events up to point where they match the incoming events
         // - pendingRemaining: The pending events after the point where they match the incoming events
-        // The `localIndexOffset` is used to account for the local events that are being ignored
-        let localIndexOffset = 0
+        // The `clientIndexOffset` is used to account for the client events that are being ignored
+        let clientIndexOffset = 0
         const [pendingMatching, pendingRemaining] = ReadonlyArray.splitWhere(
           syncState.pending,
           (pendingEvent, index) => {
-            if (ignoreLocalEvents && isLocalEvent(pendingEvent)) {
-              localIndexOffset++
+            if (ignoreClientEvents && isClientEvent(pendingEvent)) {
+              clientIndexOffset++
               return false
             }
 
-            const newEvent = payload.newEvents.at(index - localIndexOffset)
+            const newEvent = payload.newEvents.at(index - clientIndexOffset)
             if (!newEvent) {
               return true
             }
@@ -225,105 +316,100 @@ export const updateSyncState = ({
           },
         )
 
-        const seenEventIds = new Set<string>()
-        const pendingAndNewEvents = [...pendingMatching, ...payload.newEvents].filter((event) => {
-          const eventIdStr = `${event.id.global},${event.id.local}`
-          if (seenEventIds.has(eventIdStr)) {
-            return false
-          }
-          seenEventIds.add(eventIdStr)
-          return true
-        })
-
-        return {
-          _tag: 'advance',
-          newSyncState: new SyncState({
-            pending: pendingRemaining,
-            rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...pendingAndNewEvents]),
-            upstreamHead: newUpstreamHead,
-            localHead: pendingRemaining.at(-1)?.id ?? newUpstreamHead,
+        return validateMergeResult(
+          MergeResultAdvance.make({
+            _tag: 'advance',
+            newSyncState: new SyncState({
+              pending: pendingRemaining,
+              upstreamHead: newUpstreamHead,
+              localHead:
+                pendingRemaining.at(-1)?.seqNum ?? EventSequenceNumber.max(syncState.localHead, newUpstreamHead),
+            }),
+            newEvents,
+            confirmedEvents: pendingMatching,
+            mergeContext: mergeContext,
           }),
-          previousSyncState: syncState,
-          newEvents,
-        }
+        )
       } else {
         const divergentPending = syncState.pending.slice(divergentPendingIndex)
         const rebasedPending = rebaseEvents({
           events: divergentPending,
-          baseEventId: newUpstreamHead,
-          isLocalEvent,
+          baseEventSequenceNumber: newUpstreamHead,
+          isClientEvent,
         })
 
         const divergentNewEventsIndex = findDivergencePoint({
           existingEvents: payload.newEvents,
           incomingEvents: syncState.pending,
           isEqualEvent,
-          isLocalEvent,
-          ignoreLocalEvents,
+          isClientEvent,
+          ignoreClientEvents,
         })
 
-        return {
-          _tag: 'rebase',
-          newSyncState: new SyncState({
-            pending: rebasedPending,
-            rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...payload.newEvents]),
-            upstreamHead: newUpstreamHead,
-            localHead: rebasedPending.at(-1)!.id,
+        return validateMergeResult(
+          MergeResultRebase.make({
+            _tag: 'rebase',
+            newSyncState: new SyncState({
+              pending: rebasedPending,
+              upstreamHead: newUpstreamHead,
+              localHead: rebasedPending.at(-1)!.seqNum,
+            }),
+            newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
+            rollbackEvents: divergentPending,
+            mergeContext,
           }),
-          previousSyncState: syncState,
-          newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
-          eventsToRollback: [...syncState.rollbackTail, ...divergentPending],
-        }
+        )
       }
     }
+    // #endregion
 
+    // This is the same as what's running in the sync backend
     case 'local-push': {
       if (payload.newEvents.length === 0) {
-        return { _tag: 'advance', newSyncState: syncState, previousSyncState: syncState, newEvents: [] }
+        return validateMergeResult(
+          MergeResultAdvance.make({
+            _tag: 'advance',
+            newSyncState: syncState,
+            newEvents: [],
+            confirmedEvents: [],
+            mergeContext: mergeContext,
+          }),
+        )
       }
 
       const newEventsFirst = payload.newEvents.at(0)!
-      const invalidEventId = EventId.isGreaterThan(newEventsFirst.id, syncState.localHead) === false
-
-      if (invalidEventId) {
-        const expectedMinimumId = EventId.nextPair(syncState.localHead, true).id
-        return { _tag: 'reject', previousSyncState: syncState, expectedMinimumId }
+      const invalidEventSequenceNumber =
+        EventSequenceNumber.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
+
+      if (invalidEventSequenceNumber) {
+        const expectedMinimumId = EventSequenceNumber.nextPair(syncState.localHead, true).seqNum
+        return validateMergeResult(
+          MergeResultReject.make({
+            _tag: 'reject',
+            expectedMinimumId,
+            mergeContext,
+          }),
+        )
       } else {
-        return {
-          _tag: 'advance',
-          newSyncState: new SyncState({
-            pending: [...syncState.pending, ...payload.newEvents],
-            rollbackTail: syncState.rollbackTail,
-            upstreamHead: syncState.upstreamHead,
-            localHead: payload.newEvents.at(-1)!.id,
+        return validateMergeResult(
+          MergeResultAdvance.make({
+            _tag: 'advance',
+            newSyncState: new SyncState({
+              pending: [...syncState.pending, ...payload.newEvents],
+              upstreamHead: syncState.upstreamHead,
+              localHead: payload.newEvents.at(-1)!.seqNum,
+            }),
+            newEvents: payload.newEvents,
+            confirmedEvents: [],
+            mergeContext: mergeContext,
           }),
-          previousSyncState: syncState,
-          newEvents: payload.newEvents,
-        }
+        )
       }
     }
 
-    // case 'upstream-trim-rollback-tail': {
-    //   // Find the index of the new rollback start in the rollback tail
-    //   const startIndex = syncState.rollbackTail.findIndex((event) => eventIdsEqual(event.id, payload.trimRollbackUntil))
-    //   if (startIndex === -1) {
-    //     return shouldNeverHappen('New rollback start event not found in rollback tail')
-    //   }
-
-    //   // Keep only the events from the start index onwards
-    //   const newRollbackTail = syncState.rollbackTail.slice(startIndex)
-
-    //   return {
-    //     _tag: 'advance',
-    //     syncState: {
-    //       pending: syncState.pending,
-    //       rollbackTail: newRollbackTail,
-    //       upstreamHead: syncState.upstreamHead,
-    //       localHead: syncState.localHead,
-    //     },
-    //     newEvents: [],
-    //   }
-    // }
+    default: {
+      casesHandled(payload)
+    }
   }
 }
 
@@ -331,34 +417,36 @@ export const updateSyncState = ({
  * Gets the index relative to `existingEvents` where the divergence point is
  * by comparing each event in `existingEvents` to the corresponding event in `incomingEvents`
  */
-const findDivergencePoint = ({
+export const findDivergencePoint = ({
   existingEvents,
   incomingEvents,
   isEqualEvent,
-  isLocalEvent,
-  ignoreLocalEvents,
+  isClientEvent,
+  ignoreClientEvents,
 }: {
-  existingEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>
-  incomingEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>
-  isEqualEvent: (a: MutationEvent.EncodedWithMeta, b: MutationEvent.EncodedWithMeta) => boolean
-  isLocalEvent: (event: MutationEvent.EncodedWithMeta) => boolean
-  ignoreLocalEvents: boolean
+  existingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
+  incomingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
+  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
+  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
+  ignoreClientEvents: boolean
 }): number => {
-  if (ignoreLocalEvents) {
-    const filteredExistingEvents = existingEvents.filter((event) => !isLocalEvent(event))
-    const divergencePointWithoutLocalEvents = findDivergencePoint({
+  if (ignoreClientEvents) {
+    const filteredExistingEvents = existingEvents.filter((event) => !isClientEvent(event))
+    const divergencePointWithoutClientEvents = findDivergencePoint({
       existingEvents: filteredExistingEvents,
       incomingEvents,
       isEqualEvent,
-      isLocalEvent,
-      ignoreLocalEvents: false,
+      isClientEvent,
+      ignoreClientEvents: false,
     })
 
-    if (divergencePointWithoutLocalEvents === -1) return -1
+    if (divergencePointWithoutClientEvents === -1) return -1
 
-    const divergencePointEventId = existingEvents[divergencePointWithoutLocalEvents]!.id
+    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientEvents]!.seqNum
     // Now find the divergence point in the original array
-    return existingEvents.findIndex((event) => EventId.isEqual(event.id, divergencePointEventId))
+    return existingEvents.findIndex((event) =>
+      EventSequenceNumber.isEqual(event.seqNum, divergencePointEventSequenceNumber),
+    )
   }
 
   return existingEvents.findIndex((existingEvent, index) => {
@@ -370,18 +458,120 @@ const findDivergencePoint = ({
 
 const rebaseEvents = ({
   events,
-  baseEventId,
-  isLocalEvent,
+  baseEventSequenceNumber,
+  isClientEvent,
 }: {
-  events: ReadonlyArray<MutationEvent.EncodedWithMeta>
-  baseEventId: EventId.EventId
-  isLocalEvent: (event: MutationEvent.EncodedWithMeta) => boolean
-}): ReadonlyArray<MutationEvent.EncodedWithMeta> => {
-  let prevEventId = baseEventId
+  events: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
+  baseEventSequenceNumber: EventSequenceNumber.EventSequenceNumber
+  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
+}): ReadonlyArray<LiveStoreEvent.EncodedWithMeta> => {
+  let prevEventSequenceNumber = baseEventSequenceNumber
   return events.map((event) => {
-    const isLocal = isLocalEvent(event)
-    const newEvent = event.rebase(prevEventId, isLocal)
-    prevEventId = newEvent.id
+    const isLocal = isClientEvent(event)
+    const newEvent = event.rebase(prevEventSequenceNumber, isLocal)
+    prevEventSequenceNumber = newEvent.seqNum
     return newEvent
   })
 }
+
+/**
+ * TODO: Implement this
+ *
+ * In certain scenarios e.g. when the client session has a queue of upstream update results,
+ * it could make sense to "flatten" update results into a single update result which the client session
+ * can process more efficiently which avoids push-threshing
+ */
+const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
+
+const validatePayload = (payload: typeof Payload.Type) => {
+  for (let i = 1; i < payload.newEvents.length; i++) {
+    if (EventSequenceNumber.isGreaterThanOrEqual(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
+      return unexpectedError(
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+      )
+    }
+  }
+}
+
+const validateSyncState = (syncState: SyncState) => {
+  for (let i = 0; i < syncState.pending.length; i++) {
+    const event = syncState.pending[i]!
+    const nextEvent = syncState.pending[i + 1]
+    if (nextEvent === undefined) break // Reached end of chain
+
+    if (EventSequenceNumber.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum)) {
+      shouldNeverHappen(
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+        {
+          event,
+          nextEvent,
+        },
+      )
+    }
+
+    // If the global id has increased, then the client id must be 0
+    const globalIdHasIncreased = nextEvent.seqNum.global > event.seqNum.global
+    if (globalIdHasIncreased) {
+      if (nextEvent.seqNum.client !== 0) {
+        shouldNeverHappen(
+          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.toString(nextEvent.seqNum)})`,
+          syncState.pending,
+          {
+            event,
+            nextEvent,
+          },
+        )
+      }
+    } else {
+      // Otherwise, the parentSeqNum must be the same as the previous event's id
+      if (EventSequenceNumber.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
+        shouldNeverHappen('Events must be linked in a continuous chain via the parentSeqNum', syncState.pending, {
+          event,
+          nextEvent,
+        })
+      }
+    }
+  }
+}
+
+const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
+  if (mergeResult._tag === 'unexpected-error' || mergeResult._tag === 'reject') return mergeResult
+
+  validateSyncState(mergeResult.newSyncState)
+
+  // Ensure local head is always greater than or equal to upstream head
+  if (EventSequenceNumber.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)) {
+    shouldNeverHappen('Local head must be greater than or equal to upstream head', {
+      localHead: mergeResult.newSyncState.localHead,
+      upstreamHead: mergeResult.newSyncState.upstreamHead,
+    })
+  }
+
+  // Ensure new local head is greater than or equal to the previous local head
+  if (
+    EventSequenceNumber.isGreaterThanOrEqual(
+      mergeResult.newSyncState.localHead,
+      mergeResult.mergeContext.syncState.localHead,
+    ) === false
+  ) {
+    shouldNeverHappen('New local head must be greater than or equal to the previous local head', {
+      localHead: mergeResult.newSyncState.localHead,
+      previousLocalHead: mergeResult.mergeContext.syncState.localHead,
+    })
+  }
+
+  // Ensure new upstream head is greater than or equal to the previous upstream head
+  if (
+    EventSequenceNumber.isGreaterThanOrEqual(
+      mergeResult.newSyncState.upstreamHead,
+      mergeResult.mergeContext.syncState.upstreamHead,
+    ) === false
+  ) {
+    shouldNeverHappen('New upstream head must be greater than or equal to the previous upstream head', {
+      upstreamHead: mergeResult.newSyncState.upstreamHead,
+      previousUpstreamHead: mergeResult.mergeContext.syncState.upstreamHead,
+    })
+  }
+
+  return mergeResult
+}