@livestore/common 0.3.0-dev.25 → 0.3.0-dev.27

package/src/sync/syncstate.ts

@@ -9,75 +9,65 @@ import * as MutationEvent from '../schema/MutationEvent.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.
- *   - Currently only needed for ClientSessionSyncProcessor.
- *   - Note: Confirmation of an event is stronger than acknowledgment of an event and can only be done by the
- *     absolute authority in the sync hierarchy (i.e. the sync backend in our case).
+ * **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).
  *
  * 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 conflicting event conflicts even with the rollback tail (additionally to the pending events) -> events from both need to be rolled back
  *
- * 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.
+ * 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),
   /** What this node expects the next upstream node to have as its own local head */
   upstreamHead: EventId.EventId,
+  /** Equivalent to `pending.at(-1)?.id` if there are pending events */
   localHead: EventId.EventId,
 }) {
-  toJSON = (): any => {
-    return {
-      pending: this.pending.map((e) => e.toJSON()),
-      rollbackTail: this.rollbackTail.map((e) => e.toJSON()),
-      upstreamHead: `(${this.upstreamHead.global},${this.upstreamHead.client})`,
-      localHead: `(${this.localHead.global},${this.localHead.client})`,
-    }
-  }
+  toJSON = (): any => ({
+    pending: this.pending.map((e) => e.toJSON()),
+    upstreamHead: EventId.toString(this.upstreamHead),
+    localHead: EventId.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,
+  /** Events which need to be rolled back */
+  rollbackEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+  /** Events which need to be applied after the rollback (already rebased by the upstream node) */
   newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
-  /** Trim rollback tail up to this event (inclusive). */
-  trimRollbackUntil: Schema.optional(EventId.EventId),
 }) {}
 
 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),
 }) {}
 
 export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
@@ -86,12 +76,10 @@ export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
 
 export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {}
 
-export const PayloadUpstream = Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance)
-
-export type PayloadUpstream = typeof PayloadUpstream.Type
+export class PayloadUpstream extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance) {}
 
 /** Only used for debugging purposes */
-export class UpdateContext extends Schema.Class<UpdateContext>('UpdateContext')({
+export class MergeContext extends Schema.Class<MergeContext>('MergeContext')({
   payload: Payload,
   syncState: SyncState,
 }) {
@@ -105,9 +93,10 @@ export class UpdateContext extends Schema.Class<UpdateContext>('UpdateContext')(
         _tag: 'upstream-advance',
         newEvents: this.payload.newEvents.map((e) => e.toJSON()),
       })),
-      Match.tag('upstream-rebase', () => ({
+      Match.tag('upstream-rebase', (payload) => ({
         _tag: 'upstream-rebase',
-        newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+        newEvents: payload.newEvents.map((e) => e.toJSON()),
+        rollbackEvents: payload.rollbackEvents.map((e) => e.toJSON()),
       })),
       Match.exhaustive,
     )
@@ -118,78 +107,85 @@ export class UpdateContext extends Schema.Class<UpdateContext>('UpdateContext')(
   }
 }
 
-export class UpdateResultAdvance extends Schema.Class<UpdateResultAdvance>('UpdateResultAdvance')({
+export class MergeResultAdvance extends Schema.Class<MergeResultAdvance>('MergeResultAdvance')({
   _tag: Schema.Literal('advance'),
   newSyncState: SyncState,
-  /** Events which weren't pending before the update */
   newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
-  updateContext: UpdateContext,
+  /** Events which were previously pending but are now confirmed */
+  confirmedEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+  mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
     return {
       _tag: this._tag,
       newSyncState: this.newSyncState.toJSON(),
       newEvents: this.newEvents.map((e) => e.toJSON()),
-      updateContext: this.updateContext.toJSON(),
+      confirmedEvents: this.confirmedEvents.map((e) => e.toJSON()),
+      mergeContext: this.mergeContext.toJSON(),
     }
   }
 }
 
-export class UpdateResultRebase extends Schema.Class<UpdateResultRebase>('UpdateResultRebase')({
+export class MergeResultRebase extends Schema.Class<MergeResultRebase>('MergeResultRebase')({
   _tag: Schema.Literal('rebase'),
   newSyncState: SyncState,
-  /** Events which weren't pending before the update */
   newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
-  eventsToRollback: Schema.Array(MutationEvent.EncodedWithMeta),
-  updateContext: UpdateContext,
+  /** Events which need to be rolled back */
+  rollbackEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+  mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
     return {
       _tag: this._tag,
       newSyncState: this.newSyncState.toJSON(),
       newEvents: this.newEvents.map((e) => e.toJSON()),
-      eventsToRollback: this.eventsToRollback.map((e) => e.toJSON()),
-      updateContext: this.updateContext.toJSON(),
+      rollbackEvents: this.rollbackEvents.map((e) => e.toJSON()),
+      mergeContext: this.mergeContext.toJSON(),
     }
   }
 }
 
-export class UpdateResultReject extends Schema.Class<UpdateResultReject>('UpdateResultReject')({
+export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeResultReject')({
   _tag: Schema.Literal('reject'),
   /** The minimum id that the new events must have */
   expectedMinimumId: EventId.EventId,
-  updateContext: UpdateContext,
+  mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
     return {
       _tag: this._tag,
-      expectedMinimumId: `(${this.expectedMinimumId.global},${this.expectedMinimumId.client})`,
-      updateContext: this.updateContext.toJSON(),
+      expectedMinimumId: EventId.toString(this.expectedMinimumId),
+      mergeContext: this.mergeContext.toJSON(),
     }
   }
 }
 
-export class UpdateResultUnexpectedError extends Schema.Class<UpdateResultUnexpectedError>(
-  'UpdateResultUnexpectedError',
-)({
+export class MergeResultUnexpectedError extends Schema.Class<MergeResultUnexpectedError>('MergeResultUnexpectedError')({
   _tag: Schema.Literal('unexpected-error'),
   cause: UnexpectedError,
 }) {}
 
-export class UpdateResult extends Schema.Union(
-  UpdateResultAdvance,
-  UpdateResultRebase,
-  UpdateResultReject,
-  UpdateResultUnexpectedError,
+export class MergeResult extends Schema.Union(
+  MergeResultAdvance,
+  MergeResultRebase,
+  MergeResultReject,
+  MergeResultUnexpectedError,
 ) {}
 
-const unexpectedError = (cause: unknown): UpdateResultUnexpectedError =>
-  UpdateResultUnexpectedError.make({
+const unexpectedError = (cause: unknown): MergeResultUnexpectedError =>
+  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 `globalEventId` 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,
   isClientEvent,
@@ -202,34 +198,14 @@ export const updateSyncState = ({
   isEqualEvent: (a: MutationEvent.EncodedWithMeta, b: MutationEvent.EncodedWithMeta) => boolean
   /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
   ignoreClientEvents?: boolean
-}): typeof UpdateResult.Type => {
+}): typeof MergeResult.Type => {
   validateSyncState(syncState)
 
-  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)
-  }
-
-  const updateContext = UpdateContext.make({ payload, syncState })
+  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 unexpectedError(
-          `Rollback event not found in rollback tail. Rollback until: [${payload.rollbackUntil.global},${payload.rollbackUntil.client}]. 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
@@ -241,41 +217,44 @@ export const updateSyncState = ({
         isClientEvent,
       })
 
-      return UpdateResultRebase.make({
-        _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)?.id ?? newUpstreamHead,
+          }),
+          newEvents: [...payload.newEvents, ...rebasedPending],
+          rollbackEvents,
+          mergeContext,
         }),
-        newEvents: [...payload.newEvents, ...rebasedPending],
-        eventsToRollback,
-        updateContext,
-      })
+      )
     }
 
     // #region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
-        return UpdateResultAdvance.make({
-          _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,
           }),
-          newEvents: [],
-          updateContext,
-        })
+        )
       }
 
       // Validate that newEvents are sorted in ascending order by eventId
       for (let i = 1; i < payload.newEvents.length; i++) {
         if (EventId.isGreaterThan(payload.newEvents[i - 1]!.id, payload.newEvents[i]!.id)) {
           return unexpectedError(
-            `Events must be sorted in ascending order by eventId. Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`,
+            `Events must be sorted in ascending order by eventId. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
           )
         }
       }
@@ -286,18 +265,18 @@ export const updateSyncState = ({
         EventId.isEqual(syncState.upstreamHead, payload.newEvents[0]!.id)
       ) {
         return unexpectedError(
-          `Incoming events must be greater than upstream head. Expected greater than: (${syncState.upstreamHead.global},${syncState.upstreamHead.client}). Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`,
+          `Incoming events must be greater than upstream head. Expected greater than: ${EventId.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
         )
       }
 
       // Validate that the parent id of the first incoming event is known
-      const knownEventGlobalIds = [...syncState.rollbackTail, ...syncState.pending].map((e) => e.id.global)
+      const knownEventGlobalIds = [...syncState.pending].flatMap((e) => [e.id.global, e.parentId.global])
       knownEventGlobalIds.push(syncState.upstreamHead.global)
       const firstNewEvent = payload.newEvents[0]!
       const hasUnknownParentId = knownEventGlobalIds.includes(firstNewEvent.parentId.global) === false
       if (hasUnknownParentId) {
         return unexpectedError(
-          `Incoming events must have a known parent id. Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`,
+          `Incoming events must have a known parent id. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
         )
       }
 
@@ -338,27 +317,19 @@ export const updateSyncState = ({
           },
         )
 
-        const seenEventIds = new Set<string>()
-        const pendingAndNewEvents = [...pendingMatching, ...payload.newEvents].filter((event) => {
-          const eventIdStr = `${event.id.global},${event.id.client}`
-          if (seenEventIds.has(eventIdStr)) {
-            return false
-          }
-          seenEventIds.add(eventIdStr)
-          return true
-        })
-
-        return UpdateResultAdvance.make({
-          _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)?.id ?? EventId.max(syncState.localHead, newUpstreamHead),
+            }),
+            newEvents,
+            confirmedEvents: pendingMatching,
+            mergeContext: mergeContext,
           }),
-          newEvents,
-          updateContext,
-        })
+        )
       } else {
         const divergentPending = syncState.pending.slice(divergentPendingIndex)
         const rebasedPending = rebaseEvents({
@@ -375,30 +346,35 @@ export const updateSyncState = ({
           ignoreClientEvents,
         })
 
-        return UpdateResultRebase.make({
-          _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)!.id,
+            }),
+            newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
+            rollbackEvents: divergentPending,
+            mergeContext,
           }),
-          newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
-          eventsToRollback: [...syncState.rollbackTail, ...divergentPending],
-          updateContext,
-        })
+        )
       }
     }
     // #endregion
 
+    // This is the same as what's running in the sync backend
     case 'local-push': {
       if (payload.newEvents.length === 0) {
-        return UpdateResultAdvance.make({
-          _tag: 'advance',
-          newSyncState: syncState,
-          newEvents: [],
-          updateContext,
-        })
+        return validateMergeResult(
+          MergeResultAdvance.make({
+            _tag: 'advance',
+            newSyncState: syncState,
+            newEvents: [],
+            confirmedEvents: [],
+            mergeContext: mergeContext,
+          }),
+        )
       }
 
       const newEventsFirst = payload.newEvents.at(0)!
@@ -406,23 +382,27 @@ export const updateSyncState = ({
 
       if (invalidEventId) {
         const expectedMinimumId = EventId.nextPair(syncState.localHead, true).id
-        return UpdateResultReject.make({
-          _tag: 'reject',
-          expectedMinimumId,
-          updateContext,
-        })
+        return validateMergeResult(
+          MergeResultReject.make({
+            _tag: 'reject',
+            expectedMinimumId,
+            mergeContext,
+          }),
+        )
       } else {
-        return UpdateResultAdvance.make({
-          _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)!.id,
+            }),
+            newEvents: payload.newEvents,
+            confirmedEvents: [],
+            mergeContext: mergeContext,
           }),
-          newEvents: payload.newEvents,
-          updateContext,
-        })
+        )
       }
     }
 
@@ -498,18 +478,16 @@ const rebaseEvents = ({
  * 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 _flattenUpdateResults = (_updateResults: ReadonlyArray<UpdateResult>) => {}
+const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
 
 const validateSyncState = (syncState: SyncState) => {
-  // Validate that the rollback tail and pending events together form a continuous chain of events / linked list via the parentId
-  const chain = [...syncState.rollbackTail, ...syncState.pending]
-  for (let i = 0; i < chain.length; i++) {
-    const event = chain[i]!
-    const nextEvent = chain[i + 1]
+  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 (EventId.isGreaterThan(event.id, nextEvent.id)) {
-      shouldNeverHappen('Events must be sorted in ascending order by eventId', chain, {
+      shouldNeverHappen('Events must be sorted in ascending order by eventId', {
         event,
         nextEvent,
       })
@@ -520,8 +498,8 @@ const validateSyncState = (syncState: SyncState) => {
     if (globalIdHasIncreased) {
       if (nextEvent.id.client !== 0) {
         shouldNeverHappen(
-          `New global events must point to clientId 0 in the parentId. Received: (${nextEvent.id.global},${nextEvent.id.client})`,
-          chain,
+          `New global events must point to clientId 0 in the parentId. Received: (${EventId.toString(nextEvent.id)})`,
+          syncState.pending,
           {
             event,
             nextEvent,
@@ -531,24 +509,49 @@ const validateSyncState = (syncState: SyncState) => {
     } else {
       // Otherwise, the parentId must be the same as the previous event's id
       if (EventId.isEqual(nextEvent.parentId, event.id) === false) {
-        shouldNeverHappen('Events must be linked in a continuous chain via the parentId', chain, {
+        shouldNeverHappen('Events must be linked in a continuous chain via the parentId', syncState.pending, {
           event,
           nextEvent,
         })
       }
     }
   }
+}
+
+const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
+  if (mergeResult._tag === 'unexpected-error' || mergeResult._tag === 'reject') return mergeResult
+
+  // Ensure local head is always greater than or equal to upstream head
+  if (EventId.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 (
+    EventId.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 (
+    EventId.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,
+    })
+  }
 
-  // TODO double check this
-  // const globalRollbackTail = syncState.rollbackTail.filter((event) => event.id.client === 0)
-  // // The parent of the first global rollback tail event ("oldest event") must be the upstream head (if there is a rollback tail)
-  // if (globalRollbackTail.length > 0) {
-  //   const firstRollbackTailEvent = globalRollbackTail[0]!
-  //   if (EventId.isEqual(firstRollbackTailEvent.parentId, syncState.upstreamHead) === false) {
-  //     shouldNeverHappen('The parent of the first rollback tail event must be the upstream head', chain, {
-  //       event: firstRollbackTailEvent,
-  //       upstreamHead: syncState.upstreamHead,
-  //     })
-  //   }
-  // }
+  return mergeResult
 }

package/src/version.ts

@@ -2,7 +2,7 @@
 // import packageJson from '../package.json' with { type: 'json' }
 // export const liveStoreVersion = packageJson.version
 
-export const liveStoreVersion = '0.3.0-dev.25' as const
+export const liveStoreVersion = '0.3.0-dev.27' as const
 
 /**
  * This version number is incremented whenever the internal storage format changes in a breaking way.