@livestore/common 0.0.0-snapshot-f6ec49b1a18859aad769f0a0d8edf8bae231ed07 → 0.0.0-snapshot-2ef046b02334f52613d31dbe06af53487685edc0

package/src/sync/syncstate.ts

@@ -1,4 +1,4 @@
-import { casesHandled } from '@livestore/utils'
+import { casesHandled, shouldNeverHappen } from '@livestore/utils'
 import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
 import { UnexpectedError } from '../adapter-types.js'
@@ -9,65 +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.
+ * **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),
+  /** 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', {
@@ -76,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,
 }) {
@@ -95,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,
     )
@@ -108,116 +107,105 @@ 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,
-  isLocalEvent,
+  isClientEvent,
   isEqualEvent,
-  ignoreLocalEvents = false,
+  ignoreClientEvents = false,
 }: {
   syncState: SyncState
   payload: typeof Payload.Type
-  isLocalEvent: (event: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (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
-}): typeof UpdateResult.Type => {
-  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)
-  }
+  /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
+  ignoreClientEvents?: boolean
+}): typeof MergeResult.Type => {
+  validateSyncState(syncState)
 
-  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
@@ -226,35 +214,35 @@ export const updateSyncState = ({
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
         baseEventId: newUpstreamHead,
-        isLocalEvent,
+        isClientEvent,
       })
 
-      return UpdateResultRebase.make({
+      return MergeResultRebase.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,
         }),
         newEvents: [...payload.newEvents, ...rebasedPending],
-        eventsToRollback,
-        updateContext,
+        rollbackEvents,
+        mergeContext,
       })
     }
 
+    // #region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
-        return UpdateResultAdvance.make({
+        return MergeResultAdvance.make({
           _tag: 'advance',
           newSyncState: new SyncState({
             pending: syncState.pending,
-            rollbackTail: trimRollbackTail(syncState.rollbackTail),
             upstreamHead: syncState.upstreamHead,
             localHead: syncState.localHead,
           }),
           newEvents: [],
-          updateContext,
+          confirmedEvents: [],
+          mergeContext: mergeContext,
         })
       }
 
@@ -262,15 +250,29 @@ export const updateSyncState = ({
       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(', ')}]`,
           )
         }
       }
 
       // Validate that incoming events are larger than upstream head
-      if (EventId.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.id)) {
+      if (
+        EventId.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.id) ||
+        EventId.isEqual(syncState.upstreamHead, payload.newEvents[0]!.id)
+      ) {
+        return unexpectedError(
+          `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.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 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 have a known parent id. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
         )
       }
 
@@ -280,10 +282,11 @@ export const updateSyncState = ({
         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.client}`))
         const newEvents = payload.newEvents.filter((e) => !pendingEventIds.has(`${e.id.global},${e.id.client}`))
@@ -292,17 +295,17 @@ export const updateSyncState = ({
         // 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
             }
@@ -310,65 +313,57 @@ 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({
+        return MergeResultAdvance.make({
           _tag: 'advance',
           newSyncState: new SyncState({
             pending: pendingRemaining,
-            rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...pendingAndNewEvents]),
             upstreamHead: newUpstreamHead,
             localHead: pendingRemaining.at(-1)?.id ?? newUpstreamHead,
           }),
           newEvents,
-          updateContext,
+          confirmedEvents: pendingMatching,
+          mergeContext: mergeContext,
         })
       } else {
         const divergentPending = syncState.pending.slice(divergentPendingIndex)
         const rebasedPending = rebaseEvents({
           events: divergentPending,
           baseEventId: newUpstreamHead,
-          isLocalEvent,
+          isClientEvent,
         })
 
         const divergentNewEventsIndex = findDivergencePoint({
           existingEvents: payload.newEvents,
           incomingEvents: syncState.pending,
           isEqualEvent,
-          isLocalEvent,
-          ignoreLocalEvents,
+          isClientEvent,
+          ignoreClientEvents,
         })
 
-        return UpdateResultRebase.make({
+        return MergeResultRebase.make({
           _tag: 'rebase',
           newSyncState: new SyncState({
             pending: rebasedPending,
-            rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...payload.newEvents]),
             upstreamHead: newUpstreamHead,
             localHead: rebasedPending.at(-1)!.id,
           }),
           newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
-          eventsToRollback: [...syncState.rollbackTail, ...divergentPending],
-          updateContext,
+          rollbackEvents: divergentPending,
+          mergeContext,
         })
       }
     }
+    // #endregion
 
+    // This is the same as what's running in the sync backend
     case 'local-push': {
       if (payload.newEvents.length === 0) {
-        return UpdateResultAdvance.make({
+        return MergeResultAdvance.make({
           _tag: 'advance',
           newSyncState: syncState,
           newEvents: [],
-          updateContext,
+          confirmedEvents: [],
+          mergeContext: mergeContext,
         })
       }
 
@@ -377,22 +372,22 @@ export const updateSyncState = ({
 
       if (invalidEventId) {
         const expectedMinimumId = EventId.nextPair(syncState.localHead, true).id
-        return UpdateResultReject.make({
+        return MergeResultReject.make({
           _tag: 'reject',
           expectedMinimumId,
-          updateContext,
+          mergeContext,
         })
       } else {
-        return UpdateResultAdvance.make({
+        return MergeResultAdvance.make({
           _tag: 'advance',
           newSyncState: new SyncState({
             pending: [...syncState.pending, ...payload.newEvents],
-            rollbackTail: syncState.rollbackTail,
             upstreamHead: syncState.upstreamHead,
             localHead: payload.newEvents.at(-1)!.id,
           }),
           newEvents: payload.newEvents,
-          updateContext,
+          confirmedEvents: [],
+          mergeContext: mergeContext,
         })
       }
     }
@@ -407,32 +402,32 @@ 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
+  isClientEvent: (event: MutationEvent.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 divergencePointEventId = existingEvents[divergencePointWithoutClientEvents]!.id
     // Now find the divergence point in the original array
     return existingEvents.findIndex((event) => EventId.isEqual(event.id, divergencePointEventId))
   }
@@ -447,15 +442,15 @@ const findDivergencePoint = ({
 const rebaseEvents = ({
   events,
   baseEventId,
-  isLocalEvent,
+  isClientEvent,
 }: {
   events: ReadonlyArray<MutationEvent.EncodedWithMeta>
   baseEventId: EventId.EventId
-  isLocalEvent: (event: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (event: MutationEvent.EncodedWithMeta) => boolean
 }): ReadonlyArray<MutationEvent.EncodedWithMeta> => {
   let prevEventId = baseEventId
   return events.map((event) => {
-    const isLocal = isLocalEvent(event)
+    const isLocal = isClientEvent(event)
     const newEvent = event.rebase(prevEventId, isLocal)
     prevEventId = newEvent.id
     return newEvent
@@ -469,4 +464,42 @@ 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) => {
+  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', {
+        event,
+        nextEvent,
+      })
+    }
+
+    // If the global id has increased, then the client id must be 0
+    const globalIdHasIncreased = nextEvent.id.global > event.id.global
+    if (globalIdHasIncreased) {
+      if (nextEvent.id.client !== 0) {
+        shouldNeverHappen(
+          `New global events must point to clientId 0 in the parentId. Received: (${EventId.toString(nextEvent.id)})`,
+          syncState.pending,
+          {
+            event,
+            nextEvent,
+          },
+        )
+      }
+    } 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', syncState.pending, {
+          event,
+          nextEvent,
+        })
+      }
+    }
+  }
+}

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.24' as const
+export const liveStoreVersion = '0.3.0-dev.26' as const
 
 /**
  * This version number is incremented whenever the internal storage format changes in a breaking way.

package/dist/leader-thread/pull-queue-set.d.ts

@@ -1,7 +0,0 @@
-import { Effect, Queue } from '@livestore/utils/effect';
-import { LeaderThreadCtx, type PullQueueItem } from './types.js';
-export declare const makePullQueueSet: Effect.Effect<{
-    makeQueue: (since: import("../schema/EventId.js").EventId) => Effect.Effect<Queue.Queue<PullQueueItem>, import("../adapter-types.js").UnexpectedError, import("effect/Scope").Scope | LeaderThreadCtx>;
-    offer: (item: PullQueueItem) => Effect.Effect<void, import("../adapter-types.js").UnexpectedError, LeaderThreadCtx>;
-}, never, import("effect/Scope").Scope>;
-//# sourceMappingURL=pull-queue-set.d.ts.map

package/dist/leader-thread/pull-queue-set.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pull-queue-set.d.ts","sourceRoot":"","sources":["../../src/leader-thread/pull-queue-set.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAIvD,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAqB,MAAM,YAAY,CAAA;AAEnF,eAAO,MAAM,gBAAgB;kEA6D+8F,OAAQ,MAAM,CAAC,MAAM,KAAK;oCAAkG,OAAQ,MAAM;uCADpnG,CAAA"}