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

package/src/sync/ClientSessionSyncProcessor.ts

@@ -17,6 +17,8 @@ import * as SyncState from './syncstate.js'
  * - The goal is to never block the UI, so we'll interrupt rebasing if a new mutations is pushed by the client session.
  * - We also want to avoid "backwards-jumping" in the UI, so we'll transactionally apply a read model changes during a rebase.
  * - We might need to make the rebase behaviour configurable e.g. to let users manually trigger a rebase
+ *
+ * Longer term we should evalutate whether we can unify the ClientSessionSyncProcessor with the LeaderSyncProcessor.
  */
 export const makeClientSessionSyncProcessor = ({
   schema,
@@ -64,7 +66,7 @@ export const makeClientSessionSyncProcessor = ({
   }
 
   const syncStateUpdateQueue = Queue.unbounded<SyncState.SyncState>().pipe(Effect.runSync)
-  const isLocalEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) =>
+  const isClientEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) =>
     getMutationDef(schema, mutationEventEncoded.mutation).options.clientOnly
 
   /** We're queuing push requests to reduce the number of messages sent to the leader by batching them */
@@ -91,7 +93,7 @@ export const makeClientSessionSyncProcessor = ({
     const updateResult = SyncState.updateSyncState({
       syncState: syncStateRef.current,
       payload: { _tag: 'local-push', newEvents: encodedMutationEvents },
-      isLocalEvent,
+      isClientEvent,
       isEqualEvent: MutationEvent.isEqualEncoded,
     })
 
@@ -166,7 +168,10 @@ export const makeClientSessionSyncProcessor = ({
 
     yield* FiberHandle.run(leaderPushingFiberHandle, backgroundLeaderPushing)
 
-    yield* clientSession.leaderThread.mutations.pull.pipe(
+    // NOTE We need to lazily call `.pull` as we want the cursor to be updated
+    yield* Stream.suspend(() =>
+      clientSession.leaderThread.mutations.pull({ cursor: syncStateRef.current.localHead }),
+    ).pipe(
       Stream.tap(({ payload, remaining }) =>
         Effect.gen(function* () {
           // console.log('pulled payload from leader', { payload, remaining })
@@ -177,7 +182,7 @@ export const makeClientSessionSyncProcessor = ({
           const updateResult = SyncState.updateSyncState({
             syncState: syncStateRef.current,
             payload,
-            isLocalEvent,
+            isClientEvent,
             isEqualEvent: MutationEvent.isEqualEncoded,
           })
 
@@ -259,6 +264,7 @@ export const makeClientSessionSyncProcessor = ({
       ),
       Stream.runDrain,
       Effect.forever, // NOTE Whenever the leader changes, we need to re-start the stream
+      Effect.interruptible,
       Effect.withSpan('client-session-sync-processor:pull'),
       Effect.tapCauseLogPretty,
       Effect.forkScoped,

package/src/sync/next/rebase-events.ts

@@ -51,7 +51,7 @@ export const rebaseEvents = ({
   rebaseFn: RebaseFn
   currentFactsSnapshot: MutationEventFactsSnapshot
   clientId: string
-  sessionId: string | undefined
+  sessionId: string
 }): ReadonlyArray<MutationEvent.AnyDecoded> => {
   const initialSnapshot = new Map(currentFactsSnapshot)
   applyFactGroups(

package/src/sync/sync.ts

@@ -16,13 +16,25 @@ export type MakeBackendArgs = {
 }
 
 export type SyncOptions = {
-  makeBackend?: (
-    args: MakeBackendArgs,
-  ) => Effect.Effect<SyncBackend<any>, UnexpectedError, Scope.Scope | HttpClient.HttpClient>
+  backend?: SyncBackendConstructor<any>
   /** @default { _tag: 'Skip' } */
   initialSyncOptions?: InitialSyncOptions
+  /**
+   * What to do if there is an error during sync.
+   *
+   * Options:
+   * `shutdown` will stop the sync processor and cause the app to crash.
+   * `ignore` will log the error and let the app continue running acting as if it was offline.
+   *
+   * @default 'ignore'
+   * */
+  onSyncError?: 'shutdown' | 'ignore'
 }
 
+export type SyncBackendConstructor<TSyncMetadata = Schema.JsonValue> = (
+  args: MakeBackendArgs,
+) => Effect.Effect<SyncBackend<TSyncMetadata>, UnexpectedError, Scope.Scope | HttpClient.HttpClient>
+
 export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   pull: (
     args: Option.Option<{
@@ -57,6 +69,10 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
     HttpClient.HttpClient
   >
   isConnected: SubscriptionRef.SubscriptionRef<boolean>
+  /**
+   * Metadata describing the sync backend.
+   */
+  metadata: { name: string; description: string } & Record<string, Schema.JsonValue>
 }
 
 export class IsOfflineError extends Schema.TaggedError<IsOfflineError>()('IsOfflineError', {}) {}

package/src/sync/syncstate.test.ts

@@ -19,7 +19,7 @@ class TestEvent extends MutationEvent.EncodedWithMeta {
       args: payload,
 
       clientId: 'static-local-id',
-      sessionId: undefined,
+      sessionId: 'static-session-id',
     })
   }
 
@@ -39,22 +39,23 @@ const e_0_2 = new TestEvent({ global: 0, client: 2 }, e_0_1.id, 'a', true)
 const e_0_3 = new TestEvent({ global: 0, client: 3 }, e_0_2.id, 'a', true)
 const e_1_0 = new TestEvent({ global: 1, client: 0 }, e_0_0.id, 'a', false)
 const e_1_1 = new TestEvent({ global: 1, client: 1 }, e_1_0.id, 'a', true)
+const e_2_0 = new TestEvent({ global: 2, client: 0 }, e_1_0.id, 'a', false)
 
 const isEqualEvent = MutationEvent.isEqualEncoded
 
-const isLocalEvent = (event: MutationEvent.EncodedWithMeta) => (event as TestEvent).isLocal
+const isClientEvent = (event: MutationEvent.EncodedWithMeta) => (event as TestEvent).isLocal
 
 describe('syncstate', () => {
   describe('updateSyncState', () => {
-    const run = ({
+    const update = ({
       syncState,
       payload,
-      ignoreLocalEvents = false,
+      ignoreClientEvents = false,
     }: {
       syncState: SyncState.SyncState
       payload: typeof SyncState.Payload.Type
-      ignoreLocalEvents?: boolean
-    }) => SyncState.updateSyncState({ syncState, payload, isLocalEvent, isEqualEvent, ignoreLocalEvents })
+      ignoreClientEvents?: boolean
+    }) => SyncState.updateSyncState({ syncState, payload, isClientEvent, isEqualEvent, ignoreClientEvents })
 
     describe.each([{ trimRollbackUntil: false }, { trimRollbackUntil: true }])(
       'upstream-rebase (trimRollbackUntil: $trimRollbackUntil)',
@@ -68,7 +69,7 @@ describe('syncstate', () => {
           })
           const e_0_0_e_1_0 = e_0_0.rebase_(e_1_0.id)
           const e_0_1_e_1_1 = e_0_1.rebase_(e_0_0_e_1_0.id)
-          const result = run({
+          const result = update({
             syncState,
             payload: {
               _tag: 'upstream-rebase',
@@ -99,7 +100,7 @@ describe('syncstate', () => {
             localHead: e_1_0.id,
           })
           const e_0_1_e_1_0 = e_0_1.rebase_(e_0_0.id)
-          const result = run({
+          const result = update({
             syncState,
             payload: {
               _tag: 'upstream-rebase',
@@ -129,7 +130,7 @@ describe('syncstate', () => {
             upstreamHead: EventId.ROOT,
             localHead: e_0_0.id,
           })
-          const result = run({
+          const result = update({
             syncState,
             payload: { _tag: 'upstream-rebase', rollbackUntil: e_0_0.id, newEvents: [e_1_0] },
           })
@@ -148,7 +149,7 @@ describe('syncstate', () => {
             upstreamHead: EventId.ROOT,
             localHead: e_0_0.id,
           })
-          const result = run({
+          const result = update({
             syncState,
             payload: { _tag: 'upstream-rebase', rollbackUntil: e_0_0.id, newEvents: [e_1_0] },
           })
@@ -162,7 +163,7 @@ describe('syncstate', () => {
             upstreamHead: EventId.ROOT,
             localHead: e_0_0.id,
           })
-          const result = run({
+          const result = update({
             syncState,
             payload: { _tag: 'upstream-rebase', rollbackUntil: e_0_0.id, newEvents: [] },
           })
@@ -184,7 +185,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_1, e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_1, e_0_0] } })
         expect(result).toMatchObject({ _tag: 'unexpected-error' })
       })
 
@@ -195,7 +196,40 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_1_0, e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_1_0, e_0_0] } })
+        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+      })
+
+      it('should throw error if incoming event is < expected upstream head', () => {
+        const syncState = new SyncState.SyncState({
+          pending: [],
+          rollbackTail: [],
+          upstreamHead: e_1_0.id,
+          localHead: e_1_0.id,
+        })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
+        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+      })
+
+      it('should throw error if incoming event is = expected upstream head', () => {
+        const syncState = new SyncState.SyncState({
+          pending: [],
+          rollbackTail: [],
+          upstreamHead: e_1_0.id,
+          localHead: e_1_0.id,
+        })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_1_0] } })
+        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+      })
+
+      it('should throw if the parent id of the first incoming event is unknown', () => {
+        const syncState = new SyncState.SyncState({
+          pending: [],
+          rollbackTail: [e_0_0],
+          upstreamHead: EventId.ROOT,
+          localHead: e_0_0.id,
+        })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_2_0] } })
         expect(result).toMatchObject({ _tag: 'unexpected-error' })
       })
 
@@ -206,7 +240,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
 
         expectAdvance(result)
         expectEventArraysEqual(result.newSyncState.pending, [])
@@ -223,7 +257,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_1_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
 
         expectAdvance(result)
         expectEventArraysEqual(result.newSyncState.pending, [e_1_0])
@@ -240,7 +274,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0, e_0_1] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0, e_0_1] } })
 
         expectAdvance(result)
         expectEventArraysEqual(result.newSyncState.pending, [])
@@ -257,7 +291,7 @@ describe('syncstate', () => {
           upstreamHead: e_0_0.id,
           localHead: e_0_1.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_1, e_0_2, e_0_3, e_1_0, e_1_1] },
         })
@@ -277,10 +311,10 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_0] },
-          ignoreLocalEvents: true,
+          ignoreClientEvents: true,
         })
         expectAdvance(result)
         expectEventArraysEqual(result.newSyncState.pending, [])
@@ -297,10 +331,10 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_0] },
-          ignoreLocalEvents: true,
+          ignoreClientEvents: true,
         })
         expectAdvance(result)
         expectEventArraysEqual(result.newSyncState.pending, [e_1_0])
@@ -317,10 +351,10 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_1.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_0, e_1_0] },
-          ignoreLocalEvents: true,
+          ignoreClientEvents: true,
         })
 
         expectAdvance(result)
@@ -338,7 +372,7 @@ describe('syncstate', () => {
           upstreamHead: e_1_0.id,
           localHead: e_1_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
         expect(result).toMatchObject({ _tag: 'unexpected-error' })
       })
     })
@@ -351,7 +385,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_1] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_1] } })
 
         const e_0_0_e_0_2 = e_0_0.rebase_(e_0_1.id)
 
@@ -372,7 +406,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0_b.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_0_0] } })
 
         const e_0_0_e_1_0 = e_0_0_b.rebase_(e_0_0.id)
 
@@ -393,7 +427,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_1_0_b.id,
         })
-        const result = run({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_1_0] } })
+        const result = update({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e_1_0] } })
         const e_1_0_e_2_0 = e_1_0_b.rebase_(e_1_0.id)
 
         expectRebase(result)
@@ -412,7 +446,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_1, e_0_2, e_0_3, e_1_0] },
         })
@@ -433,7 +467,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_0.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_0, e_0_2, e_0_3, e_1_0] },
         })
@@ -456,7 +490,7 @@ describe('syncstate', () => {
           upstreamHead: EventId.ROOT,
           localHead: e_0_1.id,
         })
-        const result = run({
+        const result = update({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents: [e_0_1, e_0_2, e_0_3, e_1_0] },
         })
@@ -482,7 +516,7 @@ describe('syncstate', () => {
               upstreamHead: EventId.ROOT,
               localHead: e_0_0.id,
             })
-            const result = run({ syncState, payload: { _tag: 'local-push', newEvents: [e_0_1, e_0_2, e_0_3] } })
+            const result = update({ syncState, payload: { _tag: 'local-push', newEvents: [e_0_1, e_0_2, e_0_3] } })
 
             expectAdvance(result)
             expectEventArraysEqual(result.newSyncState.pending, [e_0_0, e_0_1, e_0_2, e_0_3])
@@ -501,7 +535,7 @@ describe('syncstate', () => {
               upstreamHead: EventId.ROOT,
               localHead: e_0_1.id,
             })
-            const result = run({ syncState, payload: { _tag: 'local-push', newEvents: [e_0_1, e_0_2] } })
+            const result = update({ syncState, payload: { _tag: 'local-push', newEvents: [e_0_1, e_0_2] } })
 
             expectReject(result)
             expect(result.expectedMinimumId).toMatchObject(e_0_2.id)

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'
@@ -24,6 +24,9 @@ import * as MutationEvent from '../schema/MutationEvent.js'
  *   - 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).
  *
  * Payloads:
  * - `PayloadUpstreamRebase`: Upstream has performed a rebase, so downstream must roll back to the specified event
@@ -37,12 +40,19 @@ import * as MutationEvent from '../schema/MutationEvent.js'
  * 2. **Head Ordering**: Upstream Head ≤ Local Head.
  * 3. **ID 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.
  */
 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,
   localHead: EventId.EventId,
 }) {
@@ -182,17 +192,19 @@ const unexpectedError = (cause: unknown): UpdateResultUnexpectedError =>
 export const updateSyncState = ({
   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
+  /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
+  ignoreClientEvents?: boolean
 }): typeof UpdateResult.Type => {
+  validateSyncState(syncState)
+
   const trimRollbackTail = (
     rollbackTail: ReadonlyArray<MutationEvent.EncodedWithMeta>,
   ): ReadonlyArray<MutationEvent.EncodedWithMeta> => {
@@ -226,7 +238,7 @@ export const updateSyncState = ({
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
         baseEventId: newUpstreamHead,
-        isLocalEvent,
+        isClientEvent,
       })
 
       return UpdateResultRebase.make({
@@ -243,6 +255,7 @@ export const updateSyncState = ({
       })
     }
 
+    // #region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
         return UpdateResultAdvance.make({
@@ -268,9 +281,23 @@ export const updateSyncState = ({
       }
 
       // 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: (${syncState.upstreamHead.global},${syncState.upstreamHead.client}). Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`,
+        )
+      }
+
+      // Validate that the parent id of the first incoming event is known
+      const knownEventGlobalIds = [...syncState.rollbackTail, ...syncState.pending].map((e) => e.id.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) => `(${e.id.global},${e.id.client})`).join(', ')}]`,
         )
       }
 
@@ -280,10 +307,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 +320,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
             }
@@ -336,15 +364,15 @@ export const updateSyncState = ({
         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({
@@ -361,6 +389,7 @@ export const updateSyncState = ({
         })
       }
     }
+    // #endregion
 
     case 'local-push': {
       if (payload.newEvents.length === 0) {
@@ -407,32 +436,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 +476,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
@@ -470,3 +499,56 @@ const rebaseEvents = ({
  * can process more efficiently which avoids push-threshing
  */
 const _flattenUpdateResults = (_updateResults: ReadonlyArray<UpdateResult>) => {}
+
+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]
+    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, {
+        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: (${nextEvent.id.global},${nextEvent.id.client})`,
+          chain,
+          {
+            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', chain, {
+          event,
+          nextEvent,
+        })
+      }
+    }
+  }
+
+  // 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,
+  //     })
+  //   }
+  // }
+}