@livestore/common 0.0.0-snapshot-2ef046b02334f52613d31dbe06af53487685edc0 → 0.0.0-snapshot-8115ad48d5a57244358c943ecc92bb0a30274b87

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -20,39 +20,36 @@ import { UnexpectedError } from '../adapter-types.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
 import {
   EventId,
-  getMutationDef,
+  getEventDef,
   LEADER_MERGE_COUNTER_TABLE,
-  MutationEvent,
+  LiveStoreEvent,
   SESSION_CHANGESET_META_TABLE,
 } from '../schema/mod.js'
 import { LeaderAheadError } from '../sync/sync.js'
 import * as SyncState from '../sync/syncstate.js'
 import { sql } from '../util.js'
-import { rollback } from './apply-mutation.js'
-import * as Mutationlog from './mutationlog.js'
+import { rollback } from './apply-event.js'
+import * as Eventlog from './eventlog.js'
 import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.js'
 import { LeaderThreadCtx } from './types.js'
 
-export const BACKEND_PUSH_BATCH_SIZE = 50
-export const LOCAL_PUSH_BATCH_SIZE = 10
-
 type LocalPushQueueItem = [
-  mutationEvent: MutationEvent.EncodedWithMeta,
+  event: LiveStoreEvent.EncodedWithMeta,
   deferred: Deferred.Deferred<void, LeaderAheadError> | undefined,
   /** Used to determine whether the batch has become invalid due to a rejected local push batch */
   generation: number,
 ]
 
 /**
- * The LeaderSyncProcessor manages synchronization of mutations between
+ * The LeaderSyncProcessor manages synchronization of events between
  * the local state and the sync backend, ensuring efficient and orderly processing.
  *
  * In the LeaderSyncProcessor, pulling always has precedence over pushing.
  *
  * Responsibilities:
- * - Queueing incoming local mutations in a localPushesQueue.
- * - Broadcasting mutations to client sessions via pull queues.
- * - Pushing mutations to the sync backend.
+ * - Queueing incoming local events in a localPushesQueue.
+ * - Broadcasting events to client sessions via pull queues.
+ * - Pushing events to the sync backend.
  *
  * Notes:
  *
@@ -60,12 +57,12 @@ type LocalPushQueueItem = [
  * - localPushesQueue:
  *   - Maintains events in ascending order.
  *   - Uses `Deferred` objects to resolve/reject events based on application success.
- * - Processes events from the queue, applying mutations in batches.
+ * - Processes events from the queue, applying events in batches.
  * - Controlled by a `Latch` to manage execution flow.
  * - The latch closes on pull receipt and re-opens post-pull completion.
  * - Processes up to `maxBatchSize` events per cycle.
  *
- * Currently we're advancing the db read model and mutation log in lockstep, but we could also decouple this in the future
+ * Currently we're advancing the db read model and eventlog in lockstep, but we could also decouple this in the future
  *
  * Tricky concurrency scenarios:
  * - Queued local push batches becoming invalid due to a prior local push item being rejected.
@@ -74,31 +71,50 @@ type LocalPushQueueItem = [
  */
 export const makeLeaderSyncProcessor = ({
   schema,
-  dbMutationLogMissing,
-  dbMutationLog,
+  dbEventlogMissing,
+  dbEventlog,
   dbReadModel,
   dbReadModelMissing,
   initialBlockingSyncContext,
   onError,
+  params,
+  testing,
 }: {
   schema: LiveStoreSchema
-  /** Only used to know whether we can safely query dbMutationLog during setup execution */
-  dbMutationLogMissing: boolean
-  dbMutationLog: SqliteDb
+  /** Only used to know whether we can safely query dbEventlog during setup execution */
+  dbEventlogMissing: boolean
+  dbEventlog: SqliteDb
   dbReadModel: SqliteDb
   /** Only used to know whether we can safely query dbReadModel during setup execution */
   dbReadModelMissing: boolean
   initialBlockingSyncContext: InitialBlockingSyncContext
   onError: 'shutdown' | 'ignore'
+  params: {
+    /**
+     * @default 10
+     */
+    localPushBatchSize?: number
+    /**
+     * @default 50
+     */
+    backendPushBatchSize?: number
+  }
+  testing: {
+    delays?: {
+      localPushProcessing?: Effect.Effect<void>
+    }
+  }
 }): Effect.Effect<LeaderSyncProcessor, UnexpectedError, Scope.Scope> =>
   Effect.gen(function* () {
-    const syncBackendPushQueue = yield* BucketQueue.make<MutationEvent.EncodedWithMeta>()
+    const syncBackendPushQueue = yield* BucketQueue.make<LiveStoreEvent.EncodedWithMeta>()
+    const localPushBatchSize = params.localPushBatchSize ?? 10
+    const backendPushBatchSize = params.backendPushBatchSize ?? 50
 
     const syncStateSref = yield* SubscriptionRef.make<SyncState.SyncState | undefined>(undefined)
 
-    const isClientEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) => {
-      const mutationDef = getMutationDef(schema, mutationEventEncoded.mutation)
-      return mutationDef.options.clientOnly
+    const isClientEvent = (eventEncoded: LiveStoreEvent.EncodedWithMeta) => {
+      const eventDef = getEventDef(schema, eventEncoded.name)
+      return eventDef.eventDef.options.clientOnly
     }
 
     const connectedClientSessionPullQueues = yield* makePullQueueSet
@@ -108,10 +124,12 @@ export const makeLeaderSyncProcessor = ({
      * If a local-push batch is rejected, all subsequent push queue items with the same generation are also rejected,
      * even if they would be valid on their own.
      */
+    // TODO get rid of this in favour of the `mergeGeneration` event id field
     const currentLocalPushGenerationRef = { current: 0 }
 
+    type MergeCounter = number
     const mergeCounterRef = { current: dbReadModelMissing ? 0 : yield* getMergeCounterFromDb(dbReadModel) }
-    const mergePayloads = new Map<number, typeof SyncState.PayloadUpstream.Type>()
+    const mergePayloads = new Map<MergeCounter, typeof SyncState.PayloadUpstream.Type>()
 
     // This context depends on data from `boot`, we should find a better implementation to avoid this ref indirection.
     const ctxRef = {
@@ -129,12 +147,29 @@ export const makeLeaderSyncProcessor = ({
     const localPushesLatch = yield* Effect.makeLatch(true)
     const pullLatch = yield* Effect.makeLatch(true)
 
+    /**
+     * Additionally to the `syncStateSref` we also need the `pushHeadRef` in order to prevent old/duplicate
+     * events from being pushed in a scenario like this:
+     * - client session A pushes e1
+     * - leader sync processor takes a bit and hasn't yet taken e1 from the localPushesQueue
+     * - client session B also pushes e1 (which should be rejected)
+     *
+     * Thus the purpoe of the pushHeadRef is the guard the integrity of the local push queue
+     */
+    const pushHeadRef = { current: EventId.ROOT }
+    const advancePushHead = (eventId: EventId.EventId) => {
+      pushHeadRef.current = EventId.max(pushHeadRef.current, eventId)
+    }
+
     // NOTE: New events are only pushed to sync backend after successful local push processing
     const push: LeaderSyncProcessor['push'] = (newEvents, options) =>
       Effect.gen(function* () {
-        // TODO validate batch
         if (newEvents.length === 0) return
 
+        yield* validatePushBatch(newEvents, pushHeadRef.current)
+
+        advancePushHead(newEvents.at(-1)!.id)
+
         const waitForProcessing = options?.waitForProcessing ?? false
         const generation = currentLocalPushGenerationRef.current
 
@@ -142,20 +177,18 @@ export const makeLeaderSyncProcessor = ({
           const deferreds = yield* Effect.forEach(newEvents, () => Deferred.make<void, LeaderAheadError>())
 
           const items = newEvents.map(
-            (mutationEventEncoded, i) => [mutationEventEncoded, deferreds[i], generation] as LocalPushQueueItem,
+            (eventEncoded, i) => [eventEncoded, deferreds[i], generation] as LocalPushQueueItem,
           )
 
           yield* BucketQueue.offerAll(localPushesQueue, items)
 
           yield* Effect.all(deferreds)
         } else {
-          const items = newEvents.map(
-            (mutationEventEncoded) => [mutationEventEncoded, undefined, generation] as LocalPushQueueItem,
-          )
+          const items = newEvents.map((eventEncoded) => [eventEncoded, undefined, generation] as LocalPushQueueItem)
           yield* BucketQueue.offerAll(localPushesQueue, items)
         }
       }).pipe(
-        Effect.withSpan('@livestore/common:LeaderSyncProcessor:local-push', {
+        Effect.withSpan('@livestore/common:LeaderSyncProcessor:push', {
           attributes: {
             batchSize: newEvents.length,
             batch: TRACE_VERBOSE ? newEvents : undefined,
@@ -164,26 +197,22 @@ export const makeLeaderSyncProcessor = ({
         }),
       )
 
-    const pushPartial: LeaderSyncProcessor['pushPartial'] = ({
-      mutationEvent: { mutation, args },
-      clientId,
-      sessionId,
-    }) =>
+    const pushPartial: LeaderSyncProcessor['pushPartial'] = ({ event: { name, args }, clientId, sessionId }) =>
       Effect.gen(function* () {
         const syncState = yield* syncStateSref
         if (syncState === undefined) return shouldNeverHappen('Not initialized')
 
-        const mutationDef = getMutationDef(schema, mutation)
+        const eventDef = getEventDef(schema, name)
 
-        const mutationEventEncoded = new MutationEvent.EncodedWithMeta({
-          mutation,
+        const eventEncoded = new LiveStoreEvent.EncodedWithMeta({
+          name,
           args,
           clientId,
           sessionId,
-          ...EventId.nextPair(syncState.localHead, mutationDef.options.clientOnly),
+          ...EventId.nextPair(syncState.localHead, eventDef.eventDef.options.clientOnly),
         })
 
-        yield* push([mutationEventEncoded])
+        yield* push([eventEncoded])
       }).pipe(Effect.catchTag('LeaderAheadError', Effect.orDie))
 
     // Starts various background loops
@@ -200,10 +229,9 @@ export const makeLeaderSyncProcessor = ({
         runtime,
       }
 
-      const initialBackendHead = dbMutationLogMissing
-        ? EventId.ROOT.global
-        : Mutationlog.getBackendHeadFromDb(dbMutationLog)
-      const initialLocalHead = dbMutationLogMissing ? EventId.ROOT : Mutationlog.getClientHeadFromDb(dbMutationLog)
+      const initialLocalHead = dbEventlogMissing ? EventId.ROOT : Eventlog.getClientHeadFromDb(dbEventlog)
+
+      const initialBackendHead = dbEventlogMissing ? EventId.ROOT.global : Eventlog.getBackendHeadFromDb(dbEventlog)
 
       if (initialBackendHead > initialLocalHead.global) {
         return shouldNeverHappen(
@@ -211,12 +239,12 @@ export const makeLeaderSyncProcessor = ({
         )
       }
 
-      const pendingMutationEvents = dbMutationLogMissing
+      const pendingEvents = dbEventlogMissing
         ? []
-        : yield* Mutationlog.getMutationEventsSince({ global: initialBackendHead, client: EventId.clientDefault })
+        : yield* Eventlog.getEventsSince({ global: initialBackendHead, client: EventId.clientDefault })
 
       const initialSyncState = new SyncState.SyncState({
-        pending: pendingMutationEvents,
+        pending: pendingEvents,
         upstreamHead: { global: initialBackendHead, client: EventId.clientDefault },
         localHead: initialLocalHead,
       })
@@ -225,16 +253,16 @@ export const makeLeaderSyncProcessor = ({
       yield* SubscriptionRef.set(syncStateSref, initialSyncState)
 
       // Rehydrate sync queue
-      if (pendingMutationEvents.length > 0) {
-        const globalPendingMutationEvents = pendingMutationEvents
-          // Don't sync clientOnly mutations
-          .filter((mutationEventEncoded) => {
-            const mutationDef = getMutationDef(schema, mutationEventEncoded.mutation)
-            return mutationDef.options.clientOnly === false
+      if (pendingEvents.length > 0) {
+        const globalPendingEvents = pendingEvents
+          // Don't sync clientOnly events
+          .filter((eventEncoded) => {
+            const eventDef = getEventDef(schema, eventEncoded.name)
+            return eventDef.eventDef.options.clientOnly === false
           })
 
-        if (globalPendingMutationEvents.length > 0) {
-          yield* BucketQueue.offerAll(syncBackendPushQueue, globalPendingMutationEvents)
+        if (globalPendingEvents.length > 0) {
+          yield* BucketQueue.offerAll(syncBackendPushQueue, globalPendingEvents)
         }
       }
 
@@ -259,18 +287,21 @@ export const makeLeaderSyncProcessor = ({
         connectedClientSessionPullQueues,
         mergeCounterRef,
         mergePayloads,
+        localPushBatchSize,
+        testing: {
+          delay: testing?.delays?.localPushProcessing,
+        },
       }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError), Effect.forkScoped)
 
       const backendPushingFiberHandle = yield* FiberHandle.make()
+      const backendPushingEffect = backgroundBackendPushing({
+        syncBackendPushQueue,
+        otelSpan,
+        devtoolsLatch: ctxRef.current?.devtoolsLatch,
+        backendPushBatchSize,
+      }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError))
 
-      yield* FiberHandle.run(
-        backendPushingFiberHandle,
-        backgroundBackendPushing({
-          syncBackendPushQueue,
-          otelSpan,
-          devtoolsLatch: ctxRef.current?.devtoolsLatch,
-        }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError)),
-      )
+      yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
 
       yield* backgroundBackendPulling({
         initialBackendHead,
@@ -285,14 +316,7 @@ export const makeLeaderSyncProcessor = ({
             yield* BucketQueue.offerAll(syncBackendPushQueue, filteredRebasedPending)
 
             // Restart pushing fiber
-            yield* FiberHandle.run(
-              backendPushingFiberHandle,
-              backgroundBackendPushing({
-                syncBackendPushQueue,
-                otelSpan,
-                devtoolsLatch: ctxRef.current?.devtoolsLatch,
-              }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError)),
-            )
+            yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
           }),
         syncStateSref,
         localPushesLatch,
@@ -303,26 +327,41 @@ export const makeLeaderSyncProcessor = ({
         connectedClientSessionPullQueues,
         mergeCounterRef,
         mergePayloads,
+        advancePushHead,
       }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError), Effect.forkScoped)
 
       return { initialLeaderHead: initialLocalHead }
     }).pipe(Effect.withSpanScoped('@livestore/common:LeaderSyncProcessor:boot'))
 
-    const pull: LeaderSyncProcessor['pull'] = ({ cursor }) => {
-      return Effect.gen(function* () {
+    const pull: LeaderSyncProcessor['pull'] = ({ cursor }) =>
+      Effect.gen(function* () {
         const queue = yield* pullQueue({ cursor })
         return Stream.fromQueue(queue)
       }).pipe(Stream.unwrapScoped)
-    }
 
     const pullQueue: LeaderSyncProcessor['pullQueue'] = ({ cursor }) => {
       const runtime = ctxRef.current?.runtime ?? shouldNeverHappen('Not initialized')
       return Effect.gen(function* () {
-        const queue = yield* connectedClientSessionPullQueues.makeQueue(cursor)
+        const queue = yield* connectedClientSessionPullQueues.makeQueue
         const payloadsSinceCursor = Array.from(mergePayloads.entries())
           .map(([mergeCounter, payload]) => ({ payload, mergeCounter }))
-          .filter(({ mergeCounter }) => mergeCounter > cursor)
+          .filter(({ mergeCounter }) => mergeCounter > cursor.mergeCounter)
           .toSorted((a, b) => a.mergeCounter - b.mergeCounter)
+          .map(({ payload, mergeCounter }) => {
+            if (payload._tag === 'upstream-advance') {
+              return {
+                payload: {
+                  _tag: 'upstream-advance' as const,
+                  newEvents: ReadonlyArray.dropWhile(payload.newEvents, (eventEncoded) =>
+                    EventId.isGreaterThanOrEqual(cursor.eventId, eventEncoded.id),
+                  ),
+                },
+                mergeCounter,
+              }
+            } else {
+              return { payload, mergeCounter }
+            }
+          })
 
         yield* queue.offerAll(payloadsSinceCursor)
 
@@ -363,24 +402,33 @@ const backgroundApplyLocalPushes = ({
   connectedClientSessionPullQueues,
   mergeCounterRef,
   mergePayloads,
+  localPushBatchSize,
+  testing,
 }: {
   pullLatch: Effect.Latch
   localPushesLatch: Effect.Latch
   localPushesQueue: BucketQueue.BucketQueue<LocalPushQueueItem>
   syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
-  syncBackendPushQueue: BucketQueue.BucketQueue<MutationEvent.EncodedWithMeta>
+  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.EncodedWithMeta>
   schema: LiveStoreSchema
-  isClientEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (eventEncoded: LiveStoreEvent.EncodedWithMeta) => boolean
   otelSpan: otel.Span | undefined
   currentLocalPushGenerationRef: { current: number }
   connectedClientSessionPullQueues: PullQueueSet
   mergeCounterRef: { current: number }
   mergePayloads: Map<number, typeof SyncState.PayloadUpstream.Type>
+  localPushBatchSize: number
+  testing: {
+    delay: Effect.Effect<void> | undefined
+  }
 }) =>
   Effect.gen(function* () {
     while (true) {
-      // TODO make batch size configurable
-      const batchItems = yield* BucketQueue.takeBetween(localPushesQueue, 1, LOCAL_PUSH_BATCH_SIZE)
+      if (testing.delay !== undefined) {
+        yield* testing.delay.pipe(Effect.withSpan('localPushProcessingDelay'))
+      }
+
+      const batchItems = yield* BucketQueue.takeBetween(localPushesQueue, 1, localPushBatchSize)
 
       // Wait for the backend pulling to finish
       yield* localPushesLatch.await
@@ -392,7 +440,7 @@ const backgroundApplyLocalPushes = ({
       // It's important that we filter after we got localPushesLatch, otherwise we might filter with the old generation
       const filteredBatchItems = batchItems
         .filter(([_1, _2, generation]) => generation === currentLocalPushGenerationRef.current)
-        .map(([mutationEventEncoded, deferred]) => [mutationEventEncoded, deferred] as const)
+        .map(([eventEncoded, deferred]) => [eventEncoded, deferred] as const)
 
       if (filteredBatchItems.length === 0) {
         // console.log('dropping old-gen batch', currentLocalPushGenerationRef.current)
@@ -410,14 +458,14 @@ const backgroundApplyLocalPushes = ({
         syncState,
         payload: { _tag: 'local-push', newEvents },
         isClientEvent,
-        isEqualEvent: MutationEvent.isEqualEncoded,
+        isEqualEvent: LiveStoreEvent.isEqualEncoded,
       })
 
       const mergeCounter = yield* incrementMergeCounter(mergeCounterRef)
 
       switch (mergeResult._tag) {
         case 'unexpected-error': {
-          otelSpan?.addEvent(`merge[${mergeCounter}]:local-push:unexpected-error`, {
+          otelSpan?.addEvent(`[${mergeCounter}]:push:unexpected-error`, {
             batchSize: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
           })
@@ -427,7 +475,7 @@ const backgroundApplyLocalPushes = ({
           return shouldNeverHappen('The leader thread should never have to rebase due to a local push')
         }
         case 'reject': {
-          otelSpan?.addEvent(`merge[${mergeCounter}]:local-push:reject`, {
+          otelSpan?.addEvent(`[${mergeCounter}]:push:reject`, {
             batchSize: newEvents.length,
             mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
@@ -491,28 +539,28 @@ const backgroundApplyLocalPushes = ({
       })
       mergePayloads.set(mergeCounter, SyncState.PayloadUpstreamAdvance.make({ newEvents: mergeResult.newEvents }))
 
-      otelSpan?.addEvent(`merge[${mergeCounter}]:local-push:advance`, {
+      otelSpan?.addEvent(`[${mergeCounter}]:push:advance`, {
         batchSize: newEvents.length,
         mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
       })
 
-      // Don't sync clientOnly mutations
-      const filteredBatch = mergeResult.newEvents.filter((mutationEventEncoded) => {
-        const mutationDef = getMutationDef(schema, mutationEventEncoded.mutation)
-        return mutationDef.options.clientOnly === false
+      // Don't sync clientOnly events
+      const filteredBatch = mergeResult.newEvents.filter((eventEncoded) => {
+        const eventDef = getEventDef(schema, eventEncoded.name)
+        return eventDef.eventDef.options.clientOnly === false
       })
 
       yield* BucketQueue.offerAll(syncBackendPushQueue, filteredBatch)
 
-      yield* applyMutationsBatch({ batchItems: newEvents, deferreds })
+      yield* applyEventsBatch({ batchItems: mergeResult.newEvents, deferreds })
 
       // Allow the backend pulling to start
       yield* pullLatch.open
     }
   })
 
-type ApplyMutationsBatch = (_: {
-  batchItems: ReadonlyArray<MutationEvent.EncodedWithMeta>
+type ApplyEventsBatch = (_: {
+  batchItems: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
   /**
    * The deferreds are used by the caller to know when the mutation has been processed.
    * Indexes are aligned with `batchItems`
@@ -521,13 +569,13 @@ type ApplyMutationsBatch = (_: {
 }) => Effect.Effect<void, UnexpectedError, LeaderThreadCtx>
 
 // TODO how to handle errors gracefully
-const applyMutationsBatch: ApplyMutationsBatch = ({ batchItems, deferreds }) =>
+const applyEventsBatch: ApplyEventsBatch = ({ batchItems, deferreds }) =>
   Effect.gen(function* () {
-    const { dbReadModel: db, dbMutationLog, applyMutation } = yield* LeaderThreadCtx
+    const { dbReadModel: db, dbEventlog, applyEvent } = yield* LeaderThreadCtx
 
-    // NOTE We always start a transaction to ensure consistency between db and mutation log (even for single-item batches)
+    // NOTE We always start a transaction to ensure consistency between db and eventlog (even for single-item batches)
     db.execute('BEGIN TRANSACTION', undefined) // Start the transaction
-    dbMutationLog.execute('BEGIN TRANSACTION', undefined) // Start the transaction
+    dbEventlog.execute('BEGIN TRANSACTION', undefined) // Start the transaction
 
     yield* Effect.addFinalizer((exit) =>
       Effect.gen(function* () {
@@ -535,12 +583,12 @@ const applyMutationsBatch: ApplyMutationsBatch = ({ batchItems, deferreds }) =>
 
         // Rollback in case of an error
         db.execute('ROLLBACK', undefined)
-        dbMutationLog.execute('ROLLBACK', undefined)
+        dbEventlog.execute('ROLLBACK', undefined)
       }),
     )
 
     for (let i = 0; i < batchItems.length; i++) {
-      const { sessionChangeset } = yield* applyMutation(batchItems[i]!)
+      const { sessionChangeset } = yield* applyEvent(batchItems[i]!)
       batchItems[i]!.meta.sessionChangeset = sessionChangeset
 
       if (deferreds?.[i] !== undefined) {
@@ -549,11 +597,11 @@ const applyMutationsBatch: ApplyMutationsBatch = ({ batchItems, deferreds }) =>
     }
 
     db.execute('COMMIT', undefined) // Commit the transaction
-    dbMutationLog.execute('COMMIT', undefined) // Commit the transaction
+    dbEventlog.execute('COMMIT', undefined) // Commit the transaction
   }).pipe(
     Effect.uninterruptible,
     Effect.scoped,
-    Effect.withSpan('@livestore/common:LeaderSyncProcessor:applyMutationItems', {
+    Effect.withSpan('@livestore/common:LeaderSyncProcessor:applyEventItems', {
       attributes: { batchSize: batchItems.length },
     }),
     Effect.tapCauseLogPretty,
@@ -573,11 +621,12 @@ const backgroundBackendPulling = ({
   connectedClientSessionPullQueues,
   mergeCounterRef,
   mergePayloads,
+  advancePushHead,
 }: {
   initialBackendHead: EventId.GlobalEventId
-  isClientEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (eventEncoded: LiveStoreEvent.EncodedWithMeta) => boolean
   restartBackendPushing: (
-    filteredRebasedPending: ReadonlyArray<MutationEvent.EncodedWithMeta>,
+    filteredRebasedPending: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
   ) => Effect.Effect<void, UnexpectedError, LeaderThreadCtx | HttpClient.HttpClient>
   otelSpan: otel.Span | undefined
   syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
@@ -588,13 +637,14 @@ const backgroundBackendPulling = ({
   connectedClientSessionPullQueues: PullQueueSet
   mergeCounterRef: { current: number }
   mergePayloads: Map<number, typeof SyncState.PayloadUpstream.Type>
+  advancePushHead: (eventId: EventId.EventId) => void
 }) =>
   Effect.gen(function* () {
-    const { syncBackend, dbReadModel: db, dbMutationLog, schema } = yield* LeaderThreadCtx
+    const { syncBackend, dbReadModel: db, dbEventlog, schema } = yield* LeaderThreadCtx
 
     if (syncBackend === undefined) return
 
-    const onNewPullChunk = (newEvents: MutationEvent.EncodedWithMeta[], remaining: number) =>
+    const onNewPullChunk = (newEvents: LiveStoreEvent.EncodedWithMeta[], remaining: number) =>
       Effect.gen(function* () {
         if (newEvents.length === 0) return
 
@@ -615,7 +665,7 @@ const backgroundBackendPulling = ({
           syncState,
           payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
           isClientEvent,
-          isEqualEvent: MutationEvent.isEqualEncoded,
+          isEqualEvent: LiveStoreEvent.isEqualEncoded,
           ignoreClientEvents: true,
         })
 
@@ -624,7 +674,7 @@ const backgroundBackendPulling = ({
         if (mergeResult._tag === 'reject') {
           return shouldNeverHappen('The leader thread should never reject upstream advances')
         } else if (mergeResult._tag === 'unexpected-error') {
-          otelSpan?.addEvent(`merge[${mergeCounter}]:backend-pull:unexpected-error`, {
+          otelSpan?.addEvent(`[${mergeCounter}]:pull:unexpected-error`, {
             newEventsCount: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
           })
@@ -633,24 +683,24 @@ const backgroundBackendPulling = ({
 
         const newBackendHead = newEvents.at(-1)!.id
 
-        Mutationlog.updateBackendHead(dbMutationLog, newBackendHead)
+        Eventlog.updateBackendHead(dbEventlog, newBackendHead)
 
         if (mergeResult._tag === 'rebase') {
-          otelSpan?.addEvent(`merge[${mergeCounter}]:backend-pull:rebase`, {
+          otelSpan?.addEvent(`[${mergeCounter}]:pull:rebase`, {
             newEventsCount: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
             rollbackCount: mergeResult.rollbackEvents.length,
             mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
 
-          const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((mutationEvent) => {
-            const mutationDef = getMutationDef(schema, mutationEvent.mutation)
-            return mutationDef.options.clientOnly === false
+          const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
+            const eventDef = getEventDef(schema, event.name)
+            return eventDef.eventDef.options.clientOnly === false
           })
           yield* restartBackendPushing(globalRebasedPendingEvents)
 
           if (mergeResult.rollbackEvents.length > 0) {
-            yield* rollback({ db, dbMutationLog, eventIdsToRollback: mergeResult.rollbackEvents.map((_) => _.id) })
+            yield* rollback({ db, dbEventlog, eventIdsToRollback: mergeResult.rollbackEvents.map((_) => _.id) })
           }
 
           yield* connectedClientSessionPullQueues.offer({
@@ -668,7 +718,7 @@ const backgroundBackendPulling = ({
             }),
           )
         } else {
-          otelSpan?.addEvent(`merge[${mergeCounter}]:backend-pull:advance`, {
+          otelSpan?.addEvent(`[${mergeCounter}]:pull:advance`, {
             newEventsCount: newEvents.length,
             mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
@@ -682,19 +732,19 @@ const backgroundBackendPulling = ({
           if (mergeResult.confirmedEvents.length > 0) {
             // `mergeResult.confirmedEvents` don't contain the correct sync metadata, so we need to use
             // `newEvents` instead which we filter via `mergeResult.confirmedEvents`
-            const confirmedNewEvents = newEvents.filter((mutationEvent) =>
-              mergeResult.confirmedEvents.some((confirmedEvent) =>
-                EventId.isEqual(mutationEvent.id, confirmedEvent.id),
-              ),
+            const confirmedNewEvents = newEvents.filter((event) =>
+              mergeResult.confirmedEvents.some((confirmedEvent) => EventId.isEqual(event.id, confirmedEvent.id)),
             )
-            yield* Mutationlog.updateSyncMetadata(confirmedNewEvents)
+            yield* Eventlog.updateSyncMetadata(confirmedNewEvents)
           }
         }
 
         // Removes the changeset rows which are no longer needed as we'll never have to rollback beyond this point
         trimChangesetRows(db, newBackendHead)
 
-        yield* applyMutationsBatch({ batchItems: mergeResult.newEvents, deferreds: undefined })
+        advancePushHead(mergeResult.newSyncState.localHead)
+
+        yield* applyEventsBatch({ batchItems: mergeResult.newEvents, deferreds: undefined })
 
         yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
 
@@ -704,7 +754,7 @@ const backgroundBackendPulling = ({
         }
       })
 
-    const cursorInfo = yield* Mutationlog.getSyncBackendCursorInfo(initialBackendHead)
+    const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo(initialBackendHead)
 
     yield* syncBackend.pull(cursorInfo).pipe(
       // TODO only take from queue while connected
@@ -717,13 +767,13 @@ const backgroundBackendPulling = ({
           //   },
           // })
 
-          // NOTE we only want to take process mutations when the sync backend is connected
+          // NOTE we only want to take process events when the sync backend is connected
           // (e.g. needed for simulating being offline)
           // TODO remove when there's a better way to handle this in stream above
           yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
           yield* onNewPullChunk(
-            batch.map((_) => MutationEvent.EncodedWithMeta.fromGlobal(_.mutationEventEncoded, _.metadata)),
+            batch.map((_) => LiveStoreEvent.EncodedWithMeta.fromGlobal(_.eventEncoded, _.metadata)),
             remaining,
           )
 
@@ -739,10 +789,12 @@ const backgroundBackendPushing = ({
   syncBackendPushQueue,
   otelSpan,
   devtoolsLatch,
+  backendPushBatchSize,
 }: {
-  syncBackendPushQueue: BucketQueue.BucketQueue<MutationEvent.EncodedWithMeta>
+  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.EncodedWithMeta>
   otelSpan: otel.Span | undefined
   devtoolsLatch: Effect.Latch | undefined
+  backendPushBatchSize: number
 }) =>
   Effect.gen(function* () {
     const { syncBackend } = yield* LeaderThreadCtx
@@ -751,8 +803,7 @@ const backgroundBackendPushing = ({
     while (true) {
       yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
-      // TODO make batch size configurable
-      const queueItems = yield* BucketQueue.takeBetween(syncBackendPushQueue, 1, BACKEND_PUSH_BATCH_SIZE)
+      const queueItems = yield* BucketQueue.takeBetween(syncBackendPushQueue, 1, backendPushBatchSize)
 
       yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
@@ -786,9 +837,7 @@ const trimChangesetRows = (db: SqliteDb, newHead: EventId.EventId) => {
 }
 
 interface PullQueueSet {
-  makeQueue: (
-    cursor: number,
-  ) => Effect.Effect<
+  makeQueue: Effect.Effect<
     Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type; mergeCounter: number }>,
     UnexpectedError,
     Scope.Scope | LeaderThreadCtx
@@ -812,19 +861,18 @@ const makePullQueueSet = Effect.gen(function* () {
     }),
   )
 
-  const makeQueue: PullQueueSet['makeQueue'] = () =>
-    Effect.gen(function* () {
-      const queue = yield* Queue.unbounded<{
-        payload: typeof SyncState.PayloadUpstream.Type
-        mergeCounter: number
-      }>().pipe(Effect.acquireRelease(Queue.shutdown))
+  const makeQueue: PullQueueSet['makeQueue'] = Effect.gen(function* () {
+    const queue = yield* Queue.unbounded<{
+      payload: typeof SyncState.PayloadUpstream.Type
+      mergeCounter: number
+    }>().pipe(Effect.acquireRelease(Queue.shutdown))
 
-      yield* Effect.addFinalizer(() => Effect.sync(() => set.delete(queue)))
+    yield* Effect.addFinalizer(() => Effect.sync(() => set.delete(queue)))
 
-      set.add(queue)
+    set.add(queue)
 
-      return queue
-    })
+    return queue
+  })
 
   const offer: PullQueueSet['offer'] = (item) =>
     Effect.gen(function* () {
@@ -861,3 +909,27 @@ const getMergeCounterFromDb = (dbReadModel: SqliteDb) =>
     )
     return result[0]?.mergeCounter ?? 0
   })
+
+const validatePushBatch = (batch: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>, pushHead: EventId.EventId) =>
+  Effect.gen(function* () {
+    if (batch.length === 0) {
+      return
+    }
+
+    // Make sure batch is monotonically increasing
+    for (let i = 1; i < batch.length; i++) {
+      if (EventId.isGreaterThanOrEqual(batch[i - 1]!.id, batch[i]!.id)) {
+        shouldNeverHappen(
+          `Events must be ordered in monotonically ascending order by eventId. Received: [${batch.map((e) => EventId.toString(e.id)).join(', ')}]`,
+        )
+      }
+    }
+
+    // Make sure smallest event id is > pushHead
+    if (EventId.isGreaterThanOrEqual(pushHead, batch[0]!.id)) {
+      return yield* LeaderAheadError.make({
+        minimumExpectedId: pushHead,
+        providedId: batch[0]!.id,
+      })
+    }
+  })