@livestore/common 0.4.0 → 0.5.0-dev.0

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -1,8 +1,11 @@
-import { casesHandled, isNotUndefined, LS_DEV, TRACE_VERBOSE } from '@livestore/utils'
-import type { HttpClient, Runtime, Scope, Tracer } from '@livestore/utils/effect'
+import { casesHandled, LS_DEV, TRACE_VERBOSE } from '@livestore/utils'
 import {
-  BucketQueue,
+  type HttpClient,
+  type Latch,
+  type Scope,
+  type Tracer,
   Cause,
+  Context,
   Deferred,
   Duration,
   Effect,
@@ -10,38 +13,47 @@ import {
   FiberHandle,
   Layer,
   Option,
+  Predicate,
   Queue,
   ReadonlyArray,
+  References,
+  Result,
   Schedule,
   Schema,
+  Semaphore,
   Stream,
   Subscribable,
   SubscriptionRef,
+  TxQueue,
 } from '@livestore/utils/effect'
 
-import { type MaterializeError, type SqliteDb, UnknownError } from '../adapter-types.ts'
+import { MaterializeError, type SqliteDb, UnknownError } from '../adapter-types.ts'
+import type { UnknownEventError } from '../errors.ts'
 import { IntentionalShutdownCause } from '../errors.ts'
 import { makeMaterializerHash } from '../materializer-helper.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from '../schema/mod.ts'
 import { EVENTLOG_META_TABLE, SYNC_STATUS_TABLE } from '../schema/state/sqlite/system-tables/eventlog-tables.ts'
+import * as StateHead from '../StateHead.ts'
 import type { BackendIdMismatchError, IsOfflineError, SyncBackend } from '../sync/sync.ts'
-import { isRejectedPushError, LeaderAheadError, NonMonotonicBatchError, StaleRebaseGenerationError } from './RejectedPushError.ts'
 import * as SyncState from '../sync/syncstate.ts'
 import { sql } from '../util.ts'
 import * as Eventlog from './eventlog.ts'
 import { rollback } from './materialize-event.ts'
+import {
+  isRejectedPushError,
+  LeaderAheadError,
+  NonContiguousBatchError,
+  NonMonotonicBatchError,
+  type RejectedPushError,
+  StaleRebaseGenerationError,
+} from './RejectedPushError.ts'
 import type { ShutdownChannel } from './shutdown-channel.ts'
-import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.ts'
+import type { InitialBlockingSyncContext } from './types.ts'
 import { LeaderThreadCtx } from './types.ts'
 
-/** Serialize value to JSON string for trace attributes */
-const jsonStringify = Schema.encodeSync(Schema.parseJson())
-
-type LocalPushQueueItem = [
-  event: LiveStoreEvent.Client.EncodedWithMeta,
-  deferred: Deferred.Deferred<void, LeaderAheadError | StaleRebaseGenerationError> | undefined,
-]
+export const TypeId = '~@livestore/common/LeaderSyncProcessor' as const
+export type TypeId = typeof TypeId
 
 /**
  * The LeaderSyncProcessor manages synchronization of events between
@@ -73,29 +85,59 @@ type LocalPushQueueItem = [
  *
  * See ClientSessionSyncProcessor for how the leader and session sync processors are similar/different.
  */
-export const makeLeaderSyncProcessor = ({
-  schema,
-  dbState,
-  initialBlockingSyncContext,
-  initialSyncState,
-  onError,
-  onBackendIdMismatch,
-  livePull,
-  params,
-  testing,
-}: {
-  schema: LiveStoreSchema
-  dbState: SqliteDb
-  initialBlockingSyncContext: InitialBlockingSyncContext
+export class LeaderSyncProcessor extends Context.Service<LeaderSyncProcessor, Service>()(
+  '@livestore/common/LeaderSyncProcessor',
+) {}
+
+export interface Service {
+  readonly [TypeId]: TypeId
+  /** Used by client sessions to subscribe to upstream sync state changes */
+  readonly pull: (args: {
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }>
+  /** The `pullQueue` API can be used instead of `pull` when more convenient */
+  readonly pullQueue: (args: {
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, never, Scope.Scope>
+
+  /**
+   * Used by client sessions to push events to the leader thread.
+   * The effect only finishes when the local push has been processed (i.e. succeeded or was rejected).
+   * This doesn't mean the events have been pushed to the sync backend.
+   */
+  readonly push: (
+    /** `batch` needs to follow the same rules as `batch` in `SyncBackend.push` */
+    batch: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
+  ) => Effect.Effect<void, RejectedPushError>
+
+  /** Currently only used by devtools which don't provide their own event numbers */
+  readonly pushPartial: (args: {
+    event: LiveStoreEvent.Input.Encoded
+    clientId: string
+    sessionId: string
+  }) => Effect.Effect<void, UnknownEventError>
+
+  readonly boot: Effect.Effect<
+    { initialLeaderHead: EventSequenceNumber.Client.Composite },
+    never,
+    LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
+  >
+  readonly syncState: Subscribable.Subscribable<SyncState.SyncState>
+}
+
+interface Options {
+  readonly schema: LiveStoreSchema
+  readonly dbState: SqliteDb
+  readonly initialBlockingSyncContext: InitialBlockingSyncContext
   /** Initial sync state rehydrated from the persisted eventlog or initial sync state */
-  initialSyncState: SyncState.SyncState
+  readonly initialSyncState: SyncState.SyncState
   /**
    * What to do when a failure (any cause) occurs (except `BackendIdMismatchError`).
    *
    * - `'shutdown'`: Send the error to the shutdown channel and terminate the sync processor.
    * - `'ignore'`: Continue running.
    */
-  onError: 'shutdown' | 'ignore'
+  readonly onError: 'shutdown' | 'ignore'
   /**
    * What to do when the sync backend identity has changed (i.e. the backend was reset).
    *
@@ -103,8 +145,8 @@ export const makeLeaderSyncProcessor = ({
    * - `'shutdown'`: Send a shutdown signal without clearing local storage.
    * - `'ignore'`: Continue running with stale data.
    */
-  onBackendIdMismatch: 'reset' | 'shutdown' | 'ignore'
-  params: {
+  readonly onBackendIdMismatch: 'reset' | 'shutdown' | 'ignore'
+  readonly params: {
     /**
      * Maximum number of local events to process per batch cycle.
      *
@@ -126,7 +168,7 @@ export const makeLeaderSyncProcessor = ({
      *
      * @default 10
      */
-    localPushBatchSize?: number
+    readonly localPushBatchSize?: number
     /**
      * Maximum number of events to push to the sync backend per batch.
      *
@@ -145,481 +187,736 @@ export const makeLeaderSyncProcessor = ({
      *
      * @default 50
      */
-    backendPushBatchSize?: number
+    readonly backendPushBatchSize?: number
   }
   /**
    * Whether the sync backend should reactively pull new events from the sync backend
    * When `false`, the sync processor will only do an initial pull
    */
-  livePull: boolean
-  testing: {
-    delays?: {
-      localPushProcessing?: Effect.Effect<void>
+  readonly livePull: boolean
+  readonly testing: {
+    readonly delays?: {
+      readonly localPushProcessing?: Effect.Effect<void>
+    }
+    readonly hooks?: {
+      readonly localPushAdmitted?: (events: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>) => Effect.Effect<void>
     }
   }
-}): Effect.Effect<LeaderSyncProcessor, never, Scope.Scope> =>
-  Effect.gen(function* () {
-    const syncBackendPushQueue = yield* BucketQueue.make<LiveStoreEvent.Client.EncodedWithMeta>()
-    const localPushBatchSize = params.localPushBatchSize ?? 10
-    const backendPushBatchSize = params.backendPushBatchSize ?? 50
+}
 
-    const syncStateSref = yield* SubscriptionRef.make<SyncState.SyncState | undefined>(undefined)
+export const make = Effect.fnUntraced(function* ({
+  schema,
+  dbState,
+  initialBlockingSyncContext,
+  initialSyncState,
+  onError,
+  onBackendIdMismatch,
+  livePull,
+  params,
+  testing,
+}: Options) {
+  const stateHead = yield* StateHead.StateHead
+  const syncBackendPushQueue = yield* TxQueue.unbounded<LiveStoreEvent.Client.EncodedWithMeta>()
+  const localPushBatchSize = params.localPushBatchSize ?? 10
+  const backendPushBatchSize = params.backendPushBatchSize ?? 50
+
+  const syncStateSref = yield* SubscriptionRef.make<SyncState.SyncState | undefined>(undefined)
+
+  const isClientOnlyEvent = (eventEncoded: LiveStoreEvent.Client.EncodedWithMeta) =>
+    schema.eventsDefsMap.get(eventEncoded.name)?.options.clientOnly ?? false
+
+  const connectedClientSessionPullQueues = yield* makePullQueueSet
+
+  // This context depends on data from `boot`, we should find a better implementation to avoid this ref indirection.
+  const ctxRef = {
+    current: undefined as
+      | undefined
+      | {
+          span: Tracer.Span
+          devtoolsLatch: Latch.Latch | undefined
+          services: Context.Context<LeaderThreadCtx>
+        },
+  }
 
-    const isClientEvent = (eventEncoded: LiveStoreEvent.Client.EncodedWithMeta) =>
-      schema.eventsDefsMap.get(eventEncoded.name)?.options.clientOnly ?? false
+  type LocalPushQueueItem = [
+    event: LiveStoreEvent.Client.EncodedWithMeta,
+    deferred: Deferred.Deferred<void, LeaderAheadError | StaleRebaseGenerationError>,
+  ]
+  const localPushesQueue = yield* TxQueue.unbounded<LocalPushQueueItem>()
+  // Reservations cover admitted pushes from validation until they are applied or rejected. The Set's
+  // insertion order mirrors admission order, so its last relevant item is the optimistic sequence head.
+  const reservedLocalPushItems = new Set<LocalPushQueueItem>()
+  // Ensures mutual exclusion between local push and backend pull processing.
+  const localPushBackendPullMutex = yield* Semaphore.make(1)
+  // Serializes validation, queue admission, and prefix-fence reconciliation.
+  const pushAdmissionSemaphore = yield* Semaphore.make(1)
 
-    const connectedClientSessionPullQueues = yield* makePullQueueSet
+  /**
+   * Admission fence for local pushes. Unlike `syncState.localHead`, this advances as soon as an event
+   * is queued, so another session cannot claim the same sequence number while that event is waiting
+   * to be applied. With authoritative head e0 and reserved pushes e1/e2, this points to e2.
+   *
+   * All reads and writes are protected by `pushAdmissionSemaphore` so validation and reservation are
+   * one atomic operation from the perspective of concurrent sessions and backend pulls.
+   */
+  const pushHeadRef = { current: initialSyncState.localHead }
 
-    // This context depends on data from `boot`, we should find a better implementation to avoid this ref indirection.
-    const ctxRef = {
-      current: undefined as
-        | undefined
-        | {
-            span: Tracer.Span
-            devtoolsLatch: Effect.Latch | undefined
-            runtime: Runtime.Runtime<LeaderThreadCtx>
-          },
-    }
+  /**
+   * A backend pull may advance or rebase authoritative history while local pushes remain reserved.
+   * Keep the fence at the newest reservation that is still valid for that history; if none remains,
+   * fall back to the authoritative head. Stale reservations are released later by the queue worker.
+   */
+  const reconcilePushHead = (authoritativeHead: EventSequenceNumber.Client.Composite) =>
+    pushAdmissionSemaphore.withPermits(1)(
+      Effect.gen(function* () {
+        const latestCurrentGenerationItem = [...reservedLocalPushItems].findLast(
+          ([event]) => event.seqNum.rebaseGeneration >= authoritativeHead.rebaseGeneration,
+        )
+        pushHeadRef.current = latestCurrentGenerationItem?.[0].seqNum ?? authoritativeHead
+      }).pipe(Effect.uninterruptible),
+    )
+  /**
+   * Stop completed, rejected, or stale queue items from extending the admission fence, then rebuild
+   * the fence from any pushes that are still reserved.
+   */
+  const releasePushReservations = (
+    items: ReadonlyArray<LocalPushQueueItem>,
+    authoritativeHead: EventSequenceNumber.Client.Composite,
+  ) =>
+    pushAdmissionSemaphore.withPermits(1)(
+      Effect.gen(function* () {
+        for (const item of items) reservedLocalPushItems.delete(item)
+        const latestCurrentGenerationItem = [...reservedLocalPushItems].findLast(
+          ([event]) => event.seqNum.rebaseGeneration >= authoritativeHead.rebaseGeneration,
+        )
+        pushHeadRef.current = latestCurrentGenerationItem?.[0].seqNum ?? authoritativeHead
+      }).pipe(Effect.uninterruptible),
+    )
 
-    const localPushesQueue = yield* BucketQueue.make<LocalPushQueueItem>()
-    // Ensures mutual exclusion between local push and backend pull processing.
-    const localPushBackendPullMutex = yield* Effect.makeSemaphore(1)
+  const backgroundApplyLocalPushes = Effect.gen(function* () {
+    while (true) {
+      if (testing.delays?.localPushProcessing !== undefined) {
+        yield* testing.delays.localPushProcessing.pipe(Effect.withSpan('localPushProcessingDelay'))
+      }
 
-    /**
-     * 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 purpose of the pushHeadRef is the guard the integrity of the local push queue
-     */
-    const pushHeadRef = { current: EventSequenceNumber.Client.ROOT }
-    const advancePushHead = (eventNum: EventSequenceNumber.Client.Composite) => {
-      pushHeadRef.current = EventSequenceNumber.Client.max(pushHeadRef.current, eventNum)
-    }
+      const batchItems = yield* TxQueue.takeBetween(localPushesQueue, 1, localPushBatchSize)
 
-    // NOTE: New events are only pushed to sync backend after successful local push processing
-    const push: LeaderSyncProcessor['push'] = (newEvents, options) =>
-      Effect.gen(function* () {
-        if (newEvents.length === 0) return
+      // Applies a batch of local pushes, guarded by the localPushBackendPullMutex to ensure mutual exclusion with backend pulling
+      yield* Effect.gen(function* () {
+        const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(
+          Effect.orDieDebugger,
+        )
+
+        const currentRebaseGeneration = syncState.localHead.rebaseGeneration
+
+        // Since the rebase generation might have changed since enqueuing, we need to filter out items with older generation
+        // It's important that we filter after acquiring the localPushBackendPullMutex, otherwise we might filter with the old generation
+        const [droppedItems, filteredItems] = ReadonlyArray.partition(batchItems, (batchItem) =>
+          batchItem[0].seqNum.rebaseGeneration >= currentRebaseGeneration
+            ? Result.succeed(batchItem)
+            : Result.fail(batchItem),
+        )
+
+        if (droppedItems.length > 0) {
+          yield* Effect.spanEvent(`push:drop-old-generation`, {
+            droppedCount: droppedItems.length,
+            currentRebaseGeneration,
+          })
+
+          yield* Effect.forEach(droppedItems, ([eventEncoded, deferred]) =>
+            Deferred.fail(
+              deferred,
+              StaleRebaseGenerationError.make({
+                currentRebaseGeneration,
+                providedRebaseGeneration: eventEncoded.seqNum.rebaseGeneration,
+                sessionId: eventEncoded.sessionId,
+              }),
+            ),
+          )
+
+          yield* releasePushReservations(droppedItems, syncState.localHead)
+        }
+
+        if (filteredItems.length === 0) {
+          return
+        }
+
+        const [newEvents, deferreds] = ReadonlyArray.unzip(filteredItems)
+
+        yield* Effect.annotateCurrentSpan({
+          batchSize: newEvents.length,
+          ...(TRACE_VERBOSE === true ? { newEvents: jsonStringify(newEvents) } : {}),
+        })
+
+        const mergeResult = yield* SyncState.merge({
+          syncState,
+          payload: { _tag: 'local-push', newEvents },
+          isClientOnlyEvent,
+          isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
+        })
 
-        // console.debug('push', newEvents)
+        switch (mergeResult._tag) {
+          case 'rebase': {
+            return yield* Effect.dieDebugger('The leader thread should never have to rebase due to a local push')
+          }
+          case 'reject': {
+            yield* Effect.spanEvent(`push:reject`, {
+              batchSize: newEvents.length,
+              ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
+            })
 
-        yield* validatePushBatch(newEvents, pushHeadRef.current)
+            // TODO: how to test this?
+            const nextRebaseGeneration = currentRebaseGeneration + 1
 
-        advancePushHead(newEvents.at(-1)!.seqNum)
+            const providedNum = newEvents.at(0)!.seqNum
+            // All subsequent pushes with same generation should be rejected as well
+            // We're also handling the case where the localPushQueue already contains events
+            // from the next generation which we preserve in the queue
+            const remainingEventsMatchingGeneration = yield* takePrefixUntil(
+              localPushesQueue,
+              ([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration >= nextRebaseGeneration,
+            )
 
-        const waitForProcessing = options?.waitForProcessing ?? false
+            // TODO we still need to better understand and handle this scenario
+            const remainingLocalPushes = yield* snapshotTxQueue(localPushesQueue)
+            if (LS_DEV === true && remainingLocalPushes.length > 0) {
+              console.log('localPushesQueue is not empty', remainingLocalPushes.length)
+              // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for unexpected queue state
+              debugger
+            }
 
-        if (waitForProcessing === true) {
-          const deferreds = yield* Effect.forEach(newEvents, () => Deferred.make<void, LeaderAheadError | StaleRebaseGenerationError>())
+            const allDeferredsToReject = [
+              ...deferreds,
+              ...remainingEventsMatchingGeneration.map(([_, deferred]) => deferred),
+            ]
 
-          const items = newEvents.map((eventEncoded, i) => [eventEncoded, deferreds[i]] as LocalPushQueueItem)
+            // The rejected batch and its drained same-generation suffix will never advance leader state,
+            // so release their sequence-number reservations before clients retry from the authoritative head.
+            yield* releasePushReservations(
+              [...filteredItems, ...remainingEventsMatchingGeneration],
+              syncState.localHead,
+            )
+
+            yield* Effect.forEach(allDeferredsToReject, (deferred) =>
+              Deferred.fail(
+                deferred,
+                LeaderAheadError.make({
+                  minimumExpectedNum: mergeResult.expectedMinimumId,
+                  providedNum,
+                  sessionId: newEvents.at(0)!.sessionId,
+                }),
+              ),
+            )
 
-          yield* BucketQueue.offerAll(localPushesQueue, items)
+            // In this case we're skipping state update and down/upstream processing
+            // We've cleared the local push queue and are now waiting for new local pushes / backend pulls
+            return
+          }
+          case 'advance': {
+            break
+          }
+          default: {
+            casesHandled(mergeResult)
+          }
+        }
 
-          yield* Effect.all(deferreds)
-        } else {
-          const items = newEvents.map((eventEncoded) => [eventEncoded, undefined] as LocalPushQueueItem)
-          yield* BucketQueue.offerAll(localPushesQueue, items)
+        // For a local-push advance, `newEvents` and the appended pending suffix describe the same logical
+        // events but serve different roles and may be distinct instances. Materialize the retained pending
+        // instances so their rollback metadata remains available if a later backend event causes a rebase.
+        const acceptedPendingEvents = mergeResult.newSyncState.pending.slice(syncState.pending.length)
+        if (acceptedPendingEvents.length !== mergeResult.newEvents.length) {
+          return yield* Effect.dieDebugger('Local push events must be retained in pending state')
         }
-      }).pipe(
-        Effect.withSpan('@livestore/common:LeaderSyncProcessor:push', {
-          attributes: {
-            batchSize: newEvents.length,
-            batch: TRACE_VERBOSE === true ? newEvents : undefined,
-          },
-          links:
-            ctxRef.current?.span !== undefined
-              ? [{ _tag: 'SpanLink', span: ctxRef.current.span, attributes: {} }]
-              : undefined,
-        }),
-      )
 
-    const pushPartial: LeaderSyncProcessor['pushPartial'] = ({ event: { name, args }, clientId, sessionId }) =>
-      Effect.gen(function* () {
-        const syncState = yield* Effect.fromNullable(yield* syncStateSref).pipe(Effect.orDieDebugger)
+        yield* materializeEventsBatch({ batchItems: acceptedPendingEvents })
 
-        const resolution = yield* resolveEventDef(schema, {
-          operation: '@livestore/common:LeaderSyncProcessor:pushPartial',
-          event: {
-            name,
-            args,
-            clientId,
-            sessionId,
-            seqNum: syncState.localHead,
-          },
+        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
+
+        yield* connectedClientSessionPullQueues.offer({
+          payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: acceptedPendingEvents }),
+          leaderHead: mergeResult.newSyncState.localHead,
         })
 
-        if (resolution._tag === 'unknown') {
-          // Ignore partial pushes for unrecognised events – they are still
-          // persisted server-side once a schema update ships.
+        yield* Effect.spanEvent(`push:advance`, {
+          batchSize: newEvents.length,
+          ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
+        })
+
+        // Don't sync client-only events
+        const globalOrUnknownEvents = acceptedPendingEvents.filter((e) => !isClientOnlyEvent(e))
+
+        yield* TxQueue.offerAll(syncBackendPushQueue, globalOrUnknownEvents)
+
+        yield* releasePushReservations(filteredItems, mergeResult.newSyncState.localHead)
+
+        // A push is acknowledged only after the complete batch is materialized, published in
+        // leader sync state, exposed to sessions, and queued for backend propagation.
+        yield* Effect.forEach(deferreds, (deferred) => Deferred.succeed(deferred, void 0))
+      }).pipe(localPushBackendPullMutex.withPermits(1))
+    }
+  })
+
+  const backgroundBackendPulling = Effect.fn('@livestore/common:LeaderSyncProcessor:backend-pulling')(function* ({
+    restartBackendPushing,
+  }: {
+    restartBackendPushing: (
+      filteredRebasedPending: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
+    ) => Effect.Effect<void, never, LeaderThreadCtx | HttpClient.HttpClient>
+  }) {
+    const { syncBackend, dbState: db, dbEventlog, schema } = yield* LeaderThreadCtx
+
+    if (syncBackend === undefined) return
+
+    let pullMutexHeld = false
+
+    const releasePullMutexIfHeld = Effect.gen(function* () {
+      if (pullMutexHeld === false) return
+      pullMutexHeld = false
+      yield* localPushBackendPullMutex.release(1)
+    })
+
+    const isPullPaginationComplete = (pageInfo: SyncBackend.PullResPageInfo) => pageInfo._tag === 'NoMore'
+
+    const onNewPullChunk = (
+      newEvents: LiveStoreEvent.Client.EncodedWithMeta[],
+      pageInfo: SyncBackend.PullResPageInfo,
+    ) =>
+      Effect.gen(function* () {
+        if (ctxRef.current?.devtoolsLatch !== undefined) {
+          yield* ctxRef.current.devtoolsLatch.await
+        }
+
+        if (newEvents.length === 0) {
+          if (isPullPaginationComplete(pageInfo) === true) {
+            yield* releasePullMutexIfHeld
+          }
           return
         }
 
-        const eventEncoded = new LiveStoreEvent.Client.EncodedWithMeta({
-          name,
-          args,
-          clientId,
-          sessionId,
-          ...EventSequenceNumber.Client.nextPair({
-            seqNum: syncState.localHead,
-            isClient: resolution.eventDef.options.clientOnly,
-          }),
-        })
+        // Prevent more local pushes from being processed until this pull pagination sequence is finished.
+        if (pullMutexHeld === false) {
+          yield* localPushBackendPullMutex.take(1)
+          pullMutexHeld = true
+        }
 
-        yield* push([eventEncoded])
-      }).pipe(
-        // pushPartial constructs the event sequence number internally, so these errors should never happen.
-        Effect.catchIf(isRejectedPushError, Effect.die),
-      )
+        const chunkExit = yield* Effect.gen(function* () {
+          const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(
+            Effect.orDieDebugger,
+          )
 
-    // Starts various background loops
-    const boot: LeaderSyncProcessor['boot'] = Effect.gen(function* () {
-      const span = yield* Effect.currentSpan.pipe(Effect.orDie)
-      const { devtools, shutdownChannel } = yield* LeaderThreadCtx
-      const runtime = yield* Effect.runtime<LeaderThreadCtx>()
+          yield* Effect.annotateCurrentSpan({
+            'merge.newEventsCount': newEvents.length,
+            ...(TRACE_VERBOSE === true ? { 'merge.newEvents': jsonStringify(newEvents) } : {}),
+          })
 
-      ctxRef.current = {
-        span,
-        devtoolsLatch: devtools.enabled === true ? devtools.syncBackendLatch : undefined,
-        runtime,
-      }
+          const mergeResult = yield* SyncState.merge({
+            syncState,
+            payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
+            isClientOnlyEvent,
+            isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
+            ignoreClientOnlyEvents: true,
+          })
 
-      /** State transitions need to happen atomically, so we use a Ref to track the state */
-      yield* SubscriptionRef.set(syncStateSref, initialSyncState)
+          if (mergeResult._tag === 'reject') {
+            return yield* Effect.dieDebugger('The leader thread should never reject upstream advances')
+          }
 
-      // Rehydrate sync queue
-      if (initialSyncState.pending.length > 0) {
-        const globalPendingEvents = initialSyncState.pending
-          // Don't sync client-local events
-          .filter((eventEncoded) => {
-            const eventDef = schema.eventsDefsMap.get(eventEncoded.name)
-            return eventDef === undefined ? true : eventDef.options.clientOnly === false
-          })
+          const newBackendHead = newEvents.at(-1)!.seqNum
 
-        if (globalPendingEvents.length > 0) {
-          yield* BucketQueue.offerAll(syncBackendPushQueue, globalPendingEvents)
-        }
-      }
+          Eventlog.updateBackendHead(dbEventlog, newBackendHead)
 
-      const handleBackendIdMismatchError = (error: BackendIdMismatchError) =>
-        handleBackendIdMismatch({ error, onBackendIdMismatch, shutdownChannel })
+          if (mergeResult._tag === 'rebase') {
+            yield* Effect.spanEvent(`pull:rebase[${mergeResult.newSyncState.localHead.rebaseGeneration}]`, {
+              newEventsCount: newEvents.length,
+              ...(TRACE_VERBOSE === true ? { newEvents: jsonStringify(newEvents) } : {}),
+              rollbackCount: mergeResult.rollbackEvents.length,
+              ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
+            })
 
-      const maybeShutdownOnError = (
-        cause: Cause.Cause<
-          | UnknownError
-          | MaterializeError
-        >,
-      ) =>
-        Effect.gen(function* () {
-          if (onError === 'ignore') {
-            if (LS_DEV === true) {
-              yield* Effect.logDebug(
-                `Ignoring sync error (${cause._tag === 'Fail' ? cause.error._tag : cause._tag})`,
-                Cause.pretty(cause),
+            const globalOrUnknownRebasedPendingEvents = mergeResult.newSyncState.pending.filter(
+              (e) => !isClientOnlyEvent(e),
+            )
+            yield* restartBackendPushing(globalOrUnknownRebasedPendingEvents)
+
+            if (mergeResult.rollbackEvents.length > 0) {
+              yield* rollback({
+                dbState: db,
+                dbEventlog,
+                eventNumsToRollback: mergeResult.rollbackEvents.map((_) => _.seqNum),
+              })
+              yield* stateHead
+                .set(mergeResult.rollbackEvents[0]!.parentSeqNum)
+                .pipe(Effect.mapError((cause) => MaterializeError.make({ cause })))
+            }
+
+            yield* connectedClientSessionPullQueues.offer({
+              payload: SyncState.payloadFromMergeResult(mergeResult),
+              leaderHead: mergeResult.newSyncState.localHead,
+            })
+          } else {
+            yield* Effect.spanEvent(`pull:advance`, {
+              newEventsCount: newEvents.length,
+              ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
+            })
+
+            // Ensure push fiber is active after advance by restarting with current pending (non-client-only) events
+            const globalOrUnknownPendingEvents = mergeResult.newSyncState.pending.filter((e) => !isClientOnlyEvent(e))
+            yield* restartBackendPushing(globalOrUnknownPendingEvents)
+
+            yield* connectedClientSessionPullQueues.offer({
+              payload: SyncState.payloadFromMergeResult(mergeResult),
+              leaderHead: mergeResult.newSyncState.localHead,
+            })
+
+            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((event) =>
+                mergeResult.confirmedEvents.some((confirmedEvent) =>
+                  EventSequenceNumber.Client.isEqual(event.seqNum, confirmedEvent.seqNum),
+                ),
               )
+              yield* Eventlog.updateSyncMetadata(confirmedNewEvents).pipe(Effect.orDieDebugger)
             }
-            return
           }
 
-          const errorToSend = Cause.isFailType(cause) === true ? cause.error : UnknownError.make({ cause })
-          yield* shutdownChannel.send(errorToSend).pipe(Effect.orDie)
+          // Removes the changeset rows which are no longer needed as we'll never have to rollback beyond this point
+          trimChangesetRows(db, newBackendHead)
 
-          return yield* Effect.failCause(cause).pipe(Effect.orDie)
-        })
+          // The backend merge may advance or rebase the authoritative head. Realign the admission
+          // fence now so newly arriving pushes are validated against that history, not the pre-pull head.
+          yield* reconcilePushHead(mergeResult.newSyncState.localHead)
 
-      yield* backgroundApplyLocalPushes({
-        localPushBackendPullMutex,
-        localPushesQueue,
-        syncStateSref,
-        syncBackendPushQueue,
-        schema,
-        isClientEvent,
-        connectedClientSessionPullQueues,
-        localPushBatchSize,
-        testing: {
-          delay: testing?.delays?.localPushProcessing,
-        },
-      }).pipe(
-        Effect.catchAllCause(maybeShutdownOnError),
-        Effect.forkScoped,
-      )
+          // Apply the merged events to storage before publishing the new sync state below, so readers
+          // cannot observe a leader head whose events have not yet been materialized.
+          yield* materializeEventsBatch({ batchItems: mergeResult.newEvents })
 
-      const backendPushingFiberHandle = yield* FiberHandle.make<void, never>()
-      const backendPushingEffect = backgroundBackendPushing({
-        syncBackendPushQueue,
-        devtoolsLatch: ctxRef.current?.devtoolsLatch,
-        backendPushBatchSize,
-      }).pipe(
-        Effect.catchTag('BackendIdMismatchError', handleBackendIdMismatchError),
-        Effect.catchAllCause(maybeShutdownOnError),
-      )
+          yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
+        }).pipe(Effect.exit)
 
-      yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
+        if (Exit.isFailure(chunkExit) === true) {
+          yield* releasePullMutexIfHeld
+          return yield* Effect.failCause(chunkExit.cause)
+        }
 
-      yield* backgroundBackendPulling({
-        isClientEvent,
-        restartBackendPushing: (filteredRebasedPending) =>
-          Effect.gen(function* () {
-            // Stop current pushing fiber
-            yield* FiberHandle.clear(backendPushingFiberHandle)
+        if (isPullPaginationComplete(pageInfo) === true) {
+          yield* releasePullMutexIfHeld
+        }
+      })
 
-            // Reset the sync backend push queue
-            yield* BucketQueue.clear(syncBackendPushQueue)
-            yield* BucketQueue.offerAll(syncBackendPushQueue, filteredRebasedPending)
+    const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(Effect.orDieDebugger)
+    const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo({ remoteHead: syncState.upstreamHead.global })
 
-            // Restart pushing fiber
-            yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
-          }),
-        syncStateSref,
-        localPushBackendPullMutex,
-        livePull,
-        dbState,
-        initialBlockingSyncContext,
-        devtoolsLatch: ctxRef.current?.devtoolsLatch,
-        connectedClientSessionPullQueues,
-        advancePushHead,
-      }).pipe(
-        Effect.retry({
-          // Retry pulling when we've lost connection to the sync backend
-          // We're using `until` with a refinement instead of `while` to narrow `IsOfflineError` out of the error type.
-          // See https://github.com/Effect-TS/effect/issues/6122
-          until: (error): error is Exclude<typeof error, IsOfflineError> => error._tag !== 'IsOfflineError',
+    const hashMaterializerResult = makeMaterializerHash({ schema, dbState })
+
+    yield* syncBackend.pull(cursorInfo, { live: livePull }).pipe(
+      // TODO only take from queue while connected
+      Stream.tap(({ batch, pageInfo }) =>
+        Effect.gen(function* () {
+          // 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((_) =>
+              LiveStoreEvent.Client.EncodedWithMeta.fromGlobal(_.eventEncoded, {
+                syncMetadata: _.metadata,
+                // TODO we can't really know the materializer result here yet beyond the first event batch item as we need to materialize it one by one first
+                // This is a bug and needs to be fixed https://github.com/livestorejs/livestore/issues/503#issuecomment-3114533165
+                materializerHashLeader: hashMaterializerResult(LiveStoreEvent.Global.toClientEncoded(_.eventEncoded)),
+                materializerHashSession: Option.none(),
+              }),
+            ),
+            pageInfo,
+          )
+          yield* initialBlockingSyncContext.update({ processed: batch.length, pageInfo })
         }),
-        Effect.catchTag('BackendIdMismatchError', handleBackendIdMismatchError),
-        Effect.catchAllCause(maybeShutdownOnError),
-        // Needed to avoid `Fiber terminated with an unhandled error` logs which seem to happen because of the `Effect.retry` above.
-        // This might be a bug in Effect. Only seems to happen in the browser.
-        Effect.provide(Layer.setUnhandledErrorLogLevel(Option.none())),
-        Effect.forkScoped,
-      )
+      ),
+      Stream.runDrain,
+      Effect.interruptible,
+      Effect.ensuring(releasePullMutexIfHeld),
+    )
 
-      return { initialLeaderHead: initialSyncState.localHead }
-    }).pipe(Effect.withSpanScoped('@livestore/common:LeaderSyncProcessor:boot'))
+    // Should only ever happen when livePull is false
+    yield* Effect.logDebug('backend-pulling finished', { livePull })
+  })
 
-    const pull: LeaderSyncProcessor['pull'] = ({ cursor }) =>
-      Effect.gen(function* () {
-        const queue = yield* pullQueue({ cursor })
-        return Stream.fromQueue(queue)
-      }).pipe(Stream.unwrapScoped)
+  const backgroundBackendPushing = Effect.gen(function* () {
+    const { syncBackend } = yield* LeaderThreadCtx
+    if (syncBackend === undefined) return
 
-    /*
-    Notes for a potential new `LeaderSyncProcessor.pull` implementation:
-
-    - Doesn't take cursor but is "atomically called" in the leader during the snapshot phase
-      - TODO: how is this done "atomically" in the web adapter where the snapshot is read optimistically?
-    - Would require a new kind of "boot-phase" API which is stream based:
-      - initial message: state snapshot + seq num head
-      - subsequent messages: sync state payloads
-
-    - alternative: instead of session pulling sync state payloads from leader, we could send
-      - events in the "advance" case
-      - full new state db snapshot in the "rebase" case
-        - downside: importing the snapshot is expensive
-    */
-    const pullQueue: LeaderSyncProcessor['pullQueue'] = ({ cursor }) =>
-      Effect.fromNullable(ctxRef.current?.runtime).pipe(
-        Effect.orDieDebugger,
-        Effect.flatMap((runtime) =>
-          connectedClientSessionPullQueues.makeQueue(cursor).pipe(Effect.provide(runtime))
-        )
-      )
+    while (true) {
+      yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
-    const syncState = Subscribable.make({
-      get: syncStateSref.pipe(Effect.flatMap(Effect.fromNullable), Effect.orDieDebugger),
-      changes: syncStateSref.changes.pipe(Stream.filter(isNotUndefined)),
-    })
+      const queueItems = yield* TxQueue.takeBetween(syncBackendPushQueue, 1, backendPushBatchSize)
 
-    return {
-      pull,
-      pullQueue,
-      push,
-      pushPartial,
-      boot,
-      syncState,
-    } satisfies LeaderSyncProcessor
-  })
+      yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
-const backgroundApplyLocalPushes = ({
-  localPushBackendPullMutex,
-  localPushesQueue,
-  syncStateSref,
-  syncBackendPushQueue,
-  schema,
-  isClientEvent,
-  connectedClientSessionPullQueues,
-  localPushBatchSize,
-  testing,
-}: {
-  localPushBackendPullMutex: Effect.Semaphore
-  localPushesQueue: BucketQueue.BucketQueue<LocalPushQueueItem>
-  syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
-  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.Client.EncodedWithMeta>
-  schema: LiveStoreSchema
-  isClientEvent: (eventEncoded: LiveStoreEvent.Client.EncodedWithMeta) => boolean
-  connectedClientSessionPullQueues: PullQueueSet
-  localPushBatchSize: number
-  testing: {
-    delay: Effect.Effect<void> | undefined
-  }
-}) =>
-  Effect.gen(function* () {
-    while (true) {
-      if (testing.delay !== undefined) {
-        yield* testing.delay.pipe(Effect.withSpan('localPushProcessingDelay'))
+      if (ctxRef.current?.devtoolsLatch !== undefined) {
+        yield* ctxRef.current.devtoolsLatch.await
       }
 
-      const batchItems = yield* BucketQueue.takeBetween(localPushesQueue, 1, localPushBatchSize)
+      yield* Effect.spanEvent('backend-push', {
+        batchSize: queueItems.length,
+        ...(TRACE_VERBOSE === true ? { batch: jsonStringify(queueItems) } : {}),
+      })
 
-      // Applies a batch of local pushes, guarded by the localPushBackendPullMutex to ensure mutual exclusion with backend pulling
+      // Push with declarative retry/backoff using Effect schedules
+      // - Exponential backoff starting at 1s and doubling (1s, 2s, 4s, 8s, 16s, 30s ...)
+      // - Delay clamped at 30s (continues retrying at 30s)
+      // - Resets automatically after successful push
+      // TODO(metrics): expose counters/gauges for retry attempts and queue health via devtools/metrics
       yield* Effect.gen(function* () {
-        const syncState = yield* Effect.fromNullable(yield* syncStateSref).pipe(Effect.orDieDebugger)
+        const iteration = yield* Schedule.CurrentMetadata
 
-        const currentRebaseGeneration = syncState.localHead.rebaseGeneration
+        const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.result)
 
-        // Since the rebase generation might have changed since enqueuing, we need to filter out items with older generation
-        // It's important that we filter after acquiring the localPushBackendPullMutex, otherwise we might filter with the old generation
-        const [droppedItems, filteredItems] = ReadonlyArray.partition(
-          batchItems,
-          ([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration >= currentRebaseGeneration,
-        )
+        const retries = iteration.attempt
+        if (retries > 0 && Result.isSuccess(pushResult) === true) {
+          yield* Effect.spanEvent('backend-push-retry-success', { retries, batchSize: queueItems.length })
+        }
 
-        if (droppedItems.length > 0) {
-          yield* Effect.spanEvent(`push:drop-old-generation`, {
-          droppedCount: droppedItems.length,
-          currentRebaseGeneration,
-        })
+        if (Result.isFailure(pushResult) === true) {
+          yield* Effect.spanEvent('backend-push-error', {
+            error: pushResult.failure.toString(),
+            retries,
+            batchSize: queueItems.length,
+          })
+          const error = pushResult.failure
+          if (error._tag === 'ServerAheadError') {
+            // It's a core part of the sync protocol that the sync backend will emit a new pull chunk alongside the ServerAheadError
+            yield* Effect.logDebug('handled backend-push-error (waiting for interupt caused by pull)', { error })
+            return yield* Effect.never
+          }
 
-        /**
-         * Dropped pushes may still have a deferred awaiting completion.
-         * Fail it so the caller learns the leader advanced and resubmits with the updated generation.
-         */
-        yield* Effect.forEach(
-          droppedItems.filter(
-            (item): item is [LiveStoreEvent.Client.EncodedWithMeta, Deferred.Deferred<void, LeaderAheadError | StaleRebaseGenerationError>] =>
-                item[1] !== undefined,
-            ),
-            ([eventEncoded, deferred]) =>
-              Deferred.fail(
-                deferred,
-                StaleRebaseGenerationError.make({
-                  currentRebaseGeneration,
-                  providedRebaseGeneration: eventEncoded.seqNum.rebaseGeneration,
-                sessionId: eventEncoded.sessionId,
-                }),
-              ),
-          )
+          return yield* error
         }
+      }).pipe(
+        // Retry transient errors
+        Effect.retry({
+          schedule: Schedule.exponential(Duration.seconds(1)).pipe(
+            Schedule.modifyDelay(({ duration }) => Effect.succeed(Duration.min(duration, Duration.seconds(30)))), // Cap delay at 30s intervals.
+          ),
+          while: (error) => error._tag === 'IsOfflineError' || error._tag === 'UnknownError',
+        }),
+        // This is needed to narrow the Error type. Our retry policy runs indefinitely, but Effect.retry does not narrow the Error type.
+        Effect.catchIf((error) => error._tag === 'IsOfflineError' || error._tag === 'UnknownError', Effect.die),
+      )
+    }
+  }).pipe(Effect.interruptible)
 
-        if (filteredItems.length === 0) {
-          return
+  // NOTE: New events are only pushed to sync backend after successful local push processing
+  const push: Service['push'] = (newEvents) =>
+    Effect.gen(function* () {
+      if (newEvents.length === 0) return
+
+      const deferreds = yield* Effect.forEach(newEvents, () =>
+        Deferred.make<void, LeaderAheadError | StaleRebaseGenerationError>(),
+      )
+
+      const items = newEvents.map((eventEncoded, i) => [eventEncoded, deferreds[i]] as LocalPushQueueItem)
+
+      // Validation, reservation, enqueueing, and fence advancement form one admission transaction.
+      // Serializing them prevents concurrent sessions from both validating against the same head and
+      // prevents backend reconciliation from changing the fence midway through admission.
+      yield* pushAdmissionSemaphore.withPermits(1)(
+        // Cancellation must not leave reservations, queue contents, and the admission fence disagreeing.
+        Effect.gen(function* () {
+          yield* validatePushBatch(newEvents, pushHeadRef.current, isClientOnlyEvent)
+          for (const item of items) reservedLocalPushItems.add(item)
+          yield* TxQueue.offerAll(localPushesQueue, items)
+          pushHeadRef.current = newEvents.at(-1)!.seqNum
+          if (testing.hooks?.localPushAdmitted !== undefined) {
+            yield* testing.hooks.localPushAdmitted(newEvents)
+          }
+        }).pipe(Effect.uninterruptible),
+      )
+
+      yield* Effect.all(deferreds.map(Deferred.await))
+    }).pipe(
+      Effect.withSpan('@livestore/common:LeaderSyncProcessor:push', {
+        attributes: {
+          batchSize: newEvents.length,
+          batch: TRACE_VERBOSE === true ? newEvents : undefined,
+        },
+        links: ctxRef.current?.span !== undefined ? [{ span: ctxRef.current.span, attributes: {} }] : undefined,
+      }),
+    )
+
+  return LeaderSyncProcessor.of({
+    [TypeId]: TypeId,
+    // Starts various background loops
+    boot: Effect.gen(function* () {
+      const span = yield* Effect.currentSpan.pipe(Effect.orDie)
+      const { devtools, shutdownChannel } = yield* LeaderThreadCtx
+      const services = yield* Effect.context<LeaderThreadCtx>()
+
+      ctxRef.current = {
+        span,
+        devtoolsLatch: devtools.enabled === true ? devtools.syncBackendLatch : undefined,
+        services,
+      }
+
+      /** State transitions need to happen atomically, so we use a Ref to track the state */
+      yield* SubscriptionRef.set(syncStateSref, initialSyncState)
+
+      // Rehydrate sync queue
+      if (initialSyncState.pending.length > 0) {
+        const globalOrUnknownPendingEvents = initialSyncState.pending
+          // Don't sync client-only events
+          .filter((eventEncoded) => !isClientOnlyEvent(eventEncoded))
+
+        if (globalOrUnknownPendingEvents.length > 0) {
+          yield* TxQueue.offerAll(syncBackendPushQueue, globalOrUnknownPendingEvents)
         }
+      }
 
-        const [newEvents, deferreds] = ReadonlyArray.unzip(filteredItems)
+      const handleBackendIdMismatchError = (error: BackendIdMismatchError) =>
+        handleBackendIdMismatch({ error, onBackendIdMismatch, shutdownChannel })
+
+      const maybeShutdownOnError = (cause: Cause.Cause<UnknownError | MaterializeError>) =>
+        Effect.gen(function* () {
+          if (onError === 'ignore') {
+            if (LS_DEV === true) {
+              yield* Effect.logDebug(
+                `Ignoring sync error (${Option.getOrUndefined(Cause.findErrorOption(cause))?._tag ?? cause.toString()})`,
+                Cause.pretty(cause),
+              )
+            }
+            return
+          }
 
-        yield* Effect.annotateCurrentSpan({
-        'batchSize': newEvents.length,
-        ...(TRACE_VERBOSE === true ? { 'newEvents': jsonStringify(newEvents) } : {}),
-        })
+          const error = Option.getOrUndefined(Cause.findErrorOption(cause))
+          const errorToSend = error === undefined ? UnknownError.make({ cause }) : error
+          yield* shutdownChannel.send(errorToSend).pipe(Effect.orDie)
 
-        const mergeResult = yield* SyncState.merge({
-          syncState,
-          payload: { _tag: 'local-push', newEvents },
-          isClientEvent,
-          isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
+          return yield* Effect.failCause(cause).pipe(Effect.orDie)
         })
 
-        switch (mergeResult._tag) {
-          case 'rebase': {
-            return yield* Effect.dieDebugger('The leader thread should never have to rebase due to a local push')
-          }
-          case 'reject': {
-            yield* Effect.spanEvent(`push:reject`, {
-              batchSize: newEvents.length,
-              ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
-            })
-
-            // TODO: how to test this?
-            const nextRebaseGeneration = currentRebaseGeneration + 1
+      yield* backgroundApplyLocalPushes.pipe(Effect.catchCause(maybeShutdownOnError), Effect.forkScoped)
 
-            const providedNum = newEvents.at(0)!.seqNum
-            // All subsequent pushes with same generation should be rejected as well
-            // We're also handling the case where the localPushQueue already contains events
-            // from the next generation which we preserve in the queue
-            const remainingEventsMatchingGeneration = yield* BucketQueue.takeSplitWhere(
-              localPushesQueue,
-              ([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration >= nextRebaseGeneration,
-            )
+      const backendPushingFiberHandle = yield* FiberHandle.make<void, never>()
+      const backendPushingEffect = backgroundBackendPushing.pipe(
+        Effect.catchTag('BackendIdMismatchError', handleBackendIdMismatchError),
+        Effect.catchCause(maybeShutdownOnError),
+      )
 
-            // TODO we still need to better understand and handle this scenario
-            if (LS_DEV === true && (yield* BucketQueue.size(localPushesQueue)) > 0) {
-              console.log('localPushesQueue is not empty', yield* BucketQueue.size(localPushesQueue))
-              // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for unexpected queue state
-              debugger
-            }
+      yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
 
-            const allDeferredsToReject = [
-              ...deferreds,
-              ...remainingEventsMatchingGeneration.map(([_, deferred]) => deferred),
-            ].filter(isNotUndefined)
+      yield* backgroundBackendPulling({
+        restartBackendPushing: (filteredRebasedPending) =>
+          Effect.gen(function* () {
+            // Stop current pushing fiber
+            yield* FiberHandle.clear(backendPushingFiberHandle)
 
-            yield* Effect.forEach(allDeferredsToReject, (deferred) =>
-              Deferred.fail(
-                deferred,
-                LeaderAheadError.make({ minimumExpectedNum: mergeResult.expectedMinimumId, providedNum, sessionId: newEvents.at(0)!.sessionId }),
-              ),
-            )
+            // Reset the sync backend push queue
+            yield* TxQueue.clear(syncBackendPushQueue)
+            yield* TxQueue.offerAll(syncBackendPushQueue, filteredRebasedPending)
 
-            // In this case we're skipping state update and down/upstream processing
-            // We've cleared the local push queue and are now waiting for new local pushes / backend pulls
-            return
-          }
-          case 'advance': {
-            break
-          }
-          default: {
-            casesHandled(mergeResult)
-          }
-        }
+            // Restart pushing fiber
+            yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
+          }),
+      }).pipe(
+        Effect.retry({
+          // Retry pulling when we've lost connection to the sync backend
+          // We're using `until` with a refinement instead of `while` to narrow `IsOfflineError` out of the error type.
+          // See https://github.com/Effect-TS/effect/issues/6122
+          until: (error): error is Exclude<typeof error, IsOfflineError> => error._tag !== 'IsOfflineError',
+        }),
+        Effect.catchTag('BackendIdMismatchError', handleBackendIdMismatchError),
+        Effect.catchCause(maybeShutdownOnError),
+        // Needed to avoid `Fiber terminated with an unhandled error` logs which seem to happen because of the `Effect.retry` above.
+        // This might be a bug in Effect. Only seems to happen in the browser.
+        Effect.provideService(References.UnhandledLogLevel, undefined),
+        Effect.forkScoped,
+      )
 
-        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
+      return { initialLeaderHead: initialSyncState.localHead }
+    }).pipe(Effect.withSpanScoped('@livestore/common:LeaderSyncProcessor:boot')),
+    push,
+    pushPartial: ({ event: { name, args }, clientId, sessionId }) =>
+      Effect.gen(function* () {
+        const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(
+          Effect.orDieDebugger,
+        )
 
-        yield* connectedClientSessionPullQueues.offer({
-          payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: mergeResult.newEvents }),
-          leaderHead: mergeResult.newSyncState.localHead,
+        const resolution = yield* resolveEventDef(schema, {
+          operation: '@livestore/common:LeaderSyncProcessor:pushPartial',
+          event: {
+            name,
+            args,
+            clientId,
+            sessionId,
+            seqNum: syncState.localHead,
+          },
         })
 
-        yield* Effect.spanEvent(`push:advance`, {
-          batchSize: newEvents.length,
-        ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
-        })
+        if (resolution._tag === 'unknown') {
+          // Ignore partial pushes for unrecognised events – they are still
+          // persisted server-side once a schema update ships.
+          return
+        }
 
-        // Don't sync client-local events
-        const filteredBatch = mergeResult.newEvents.filter((eventEncoded) => {
-          const eventDef = schema.eventsDefsMap.get(eventEncoded.name)
-          return eventDef === undefined ? true : eventDef.options.clientOnly === false
+        const eventEncoded = new LiveStoreEvent.Client.EncodedWithMeta({
+          name,
+          args,
+          clientId,
+          sessionId,
+          ...EventSequenceNumber.Client.nextPair({
+            seqNum: syncState.localHead,
+            isClientOnly: resolution.eventDef.options.clientOnly,
+          }),
         })
 
-        yield* BucketQueue.offerAll(syncBackendPushQueue, filteredBatch)
-
-        yield* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds })
-      }).pipe(localPushBackendPullMutex.withPermits(1))
-    }
+        yield* push([eventEncoded])
+      }).pipe(
+        // pushPartial constructs the event sequence number internally, so these errors should never happen.
+        Effect.catchIf(isRejectedPushError, Effect.die),
+      ),
+    pull: ({ cursor }) =>
+      Effect.gen(function* () {
+        const queue = yield* Effect.fromNullishOr(ctxRef.current?.services).pipe(
+          Effect.orDieDebugger,
+          Effect.flatMap((services) =>
+            connectedClientSessionPullQueues.makeQueue(cursor).pipe(Effect.provide(services)),
+          ),
+        )
+        return Stream.fromQueue(queue)
+      }).pipe(Stream.unwrap),
+    /*
+      Notes for a potential new `LeaderSyncProcessor.pull` implementation:
+
+      - Doesn't take cursor but is "atomically called" in the leader during the snapshot phase
+        - TODO: how is this done "atomically" in the web adapter where the snapshot is read optimistically?
+      - Would require a new kind of "boot-phase" API which is stream based:
+        - initial message: state snapshot + seq num head
+        - subsequent messages: sync state payloads
+
+      - alternative: instead of session pulling sync state payloads from leader, we could send
+        - events in the "advance" case
+        - full new state db snapshot in the "rebase" case
+          - downside: importing the snapshot is expensive
+      */
+    pullQueue: ({ cursor }) =>
+      Effect.fromNullishOr(ctxRef.current?.services).pipe(
+        Effect.orDieDebugger,
+        Effect.flatMap((services) => connectedClientSessionPullQueues.makeQueue(cursor).pipe(Effect.provide(services))),
+      ),
+    syncState: Subscribable.make({
+      get: SubscriptionRef.get(syncStateSref).pipe(Effect.flatMap(Effect.fromNullishOr), Effect.orDieDebugger),
+      changes: SubscriptionRef.changes(syncStateSref).pipe(Stream.filter(Predicate.isNotUndefined)),
+    }),
   })
+})
+
+export const layer = (options: Options) => Layer.effect(LeaderSyncProcessor, make(options))
 
 type MaterializeEventsBatch = (_: {
   batchItems: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
-  /**
-   * The deferreds are used by the caller to know when the mutation has been processed.
-   * Indexes are aligned with `batchItems`
-   */
-  deferreds: ReadonlyArray<Deferred.Deferred<void, LeaderAheadError | StaleRebaseGenerationError> | undefined> | undefined
 }) => Effect.Effect<void, MaterializeError, LeaderThreadCtx>
 
 // TODO how to handle errors gracefully
-const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems, deferreds }) =>
+const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems }) =>
   Effect.gen(function* () {
     const { dbState: db, dbEventlog, materializeEvent } = yield* LeaderThreadCtx
 
@@ -641,10 +938,6 @@ const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems, deferreds
       const { sessionChangeset, hash } = yield* materializeEvent(batchItems[i]!)
       batchItems[i]!.meta.sessionChangeset = sessionChangeset
       batchItems[i]!.meta.materializerHashLeader = hash
-
-      if (deferreds?.[i] !== undefined) {
-        yield* Deferred.succeed(deferreds[i]!, void 0)
-      }
     }
 
     db.execute('COMMIT', undefined) // Commit the transaction
@@ -658,273 +951,6 @@ const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems, deferreds
     Effect.tapCauseLogPretty,
   )
 
-const backgroundBackendPulling = Effect.fn('@livestore/common:LeaderSyncProcessor:backend-pulling')(function* ({
-  isClientEvent,
-  restartBackendPushing,
-  dbState,
-  syncStateSref,
-  localPushBackendPullMutex,
-  livePull,
-  devtoolsLatch,
-  initialBlockingSyncContext,
-  connectedClientSessionPullQueues,
-  advancePushHead,
-}: {
-  isClientEvent: (eventEncoded: LiveStoreEvent.Client.EncodedWithMeta) => boolean
-  restartBackendPushing: (
-    filteredRebasedPending: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
-  ) => Effect.Effect<void, never, LeaderThreadCtx | HttpClient.HttpClient>
-  syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
-  dbState: SqliteDb
-  localPushBackendPullMutex: Effect.Semaphore
-  livePull: boolean
-  devtoolsLatch: Effect.Latch | undefined
-  initialBlockingSyncContext: InitialBlockingSyncContext
-  connectedClientSessionPullQueues: PullQueueSet
-  advancePushHead: (eventNum: EventSequenceNumber.Client.Composite) => void
-}) {
-  const { syncBackend, dbState: db, dbEventlog, schema } = yield* LeaderThreadCtx
-
-  if (syncBackend === undefined) return
-
-  let pullMutexHeld = false
-
-  const releasePullMutexIfHeld = Effect.gen(function* () {
-    if (pullMutexHeld === false) return
-    pullMutexHeld = false
-    yield* localPushBackendPullMutex.release(1)
-  })
-
-  const isPullPaginationComplete = (pageInfo: SyncBackend.PullResPageInfo) => pageInfo._tag === 'NoMore'
-
-  const onNewPullChunk = (newEvents: LiveStoreEvent.Client.EncodedWithMeta[], pageInfo: SyncBackend.PullResPageInfo) =>
-    Effect.gen(function* () {
-      if (devtoolsLatch !== undefined) {
-        yield* devtoolsLatch.await
-      }
-
-      if (newEvents.length === 0) {
-        if (isPullPaginationComplete(pageInfo) === true) {
-          yield* releasePullMutexIfHeld
-        }
-        return
-      }
-
-      // Prevent more local pushes from being processed until this pull pagination sequence is finished.
-      if (pullMutexHeld === false) {
-        yield* localPushBackendPullMutex.take(1)
-        pullMutexHeld = true
-      }
-
-      const chunkExit = yield* Effect.gen(function* () {
-        const syncState = yield* Effect.fromNullable(yield* syncStateSref).pipe(Effect.orDieDebugger)
-
-        yield* Effect.annotateCurrentSpan({
-        'merge.newEventsCount': newEvents.length,
-        ...(TRACE_VERBOSE === true ? { 'merge.newEvents': jsonStringify(newEvents) } : {}),
-      })
-
-      const mergeResult = yield* SyncState.merge({
-        syncState,
-        payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
-        isClientEvent,
-        isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
-        ignoreClientEvents: true,
-      })
-
-      if (mergeResult._tag === 'reject') {
-        return yield* Effect.dieDebugger('The leader thread should never reject upstream advances')
-      }
-
-        const newBackendHead = newEvents.at(-1)!.seqNum
-
-        Eventlog.updateBackendHead(dbEventlog, newBackendHead)
-
-        if (mergeResult._tag === 'rebase') {
-          yield* Effect.spanEvent(`pull:rebase[${mergeResult.newSyncState.localHead.rebaseGeneration}]`, {
-          newEventsCount: newEvents.length,
-          ...(TRACE_VERBOSE === true ? { newEvents: jsonStringify(newEvents) } : {}),
-          rollbackCount: mergeResult.rollbackEvents.length,
-          ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
-          })
-
-          const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
-            const eventDef = schema.eventsDefsMap.get(event.name)
-            return eventDef === undefined ? true : eventDef.options.clientOnly === false
-          })
-          yield* restartBackendPushing(globalRebasedPendingEvents)
-
-          if (mergeResult.rollbackEvents.length > 0) {
-            yield* rollback({
-              dbState: db,
-              dbEventlog,
-              eventNumsToRollback: mergeResult.rollbackEvents.map((_) => _.seqNum),
-            })
-          }
-
-          yield* connectedClientSessionPullQueues.offer({
-            payload: SyncState.payloadFromMergeResult(mergeResult),
-            leaderHead: mergeResult.newSyncState.localHead,
-          })
-        } else {
-          yield* Effect.spanEvent(`pull:advance`, {
-            newEventsCount: newEvents.length,
-          ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
-          })
-
-          // Ensure push fiber is active after advance by restarting with current pending (non-client) events
-          const globalPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
-            const eventDef = schema.eventsDefsMap.get(event.name)
-            return eventDef === undefined ? true : eventDef.options.clientOnly === false
-          })
-          yield* restartBackendPushing(globalPendingEvents)
-
-          yield* connectedClientSessionPullQueues.offer({
-            payload: SyncState.payloadFromMergeResult(mergeResult),
-            leaderHead: mergeResult.newSyncState.localHead,
-          })
-
-          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((event) =>
-              mergeResult.confirmedEvents.some((confirmedEvent) =>
-                EventSequenceNumber.Client.isEqual(event.seqNum, confirmedEvent.seqNum),
-              ),
-            )
-            yield* Eventlog.updateSyncMetadata(confirmedNewEvents).pipe(Effect.orDieDebugger)
-          }
-        }
-
-        // Removes the changeset rows which are no longer needed as we'll never have to rollback beyond this point
-        trimChangesetRows(db, newBackendHead)
-
-        advancePushHead(mergeResult.newSyncState.localHead)
-
-        yield* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds: undefined })
-
-        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
-      }).pipe(Effect.exit)
-
-      if (Exit.isFailure(chunkExit) === true) {
-        yield* releasePullMutexIfHeld
-        return yield* Effect.failCause(chunkExit.cause)
-      }
-
-      if (isPullPaginationComplete(pageInfo) === true) {
-        yield* releasePullMutexIfHeld
-      }
-    })
-
-  const syncState = yield* Effect.fromNullable(yield* syncStateSref).pipe(Effect.orDieDebugger)
-  const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo({ remoteHead: syncState.upstreamHead.global })
-
-  const hashMaterializerResult = makeMaterializerHash({ schema, dbState })
-
-  yield* syncBackend.pull(cursorInfo, { live: livePull }).pipe(
-    // TODO only take from queue while connected
-    Stream.tap(({ batch, pageInfo }) =>
-      Effect.gen(function* () {
-        // 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((_) =>
-            LiveStoreEvent.Client.EncodedWithMeta.fromGlobal(_.eventEncoded, {
-              syncMetadata: _.metadata,
-              // TODO we can't really know the materializer result here yet beyond the first event batch item as we need to materialize it one by one first
-              // This is a bug and needs to be fixed https://github.com/livestorejs/livestore/issues/503#issuecomment-3114533165
-              materializerHashLeader: hashMaterializerResult(LiveStoreEvent.Global.toClientEncoded(_.eventEncoded)),
-              materializerHashSession: Option.none(),
-            }),
-          ),
-          pageInfo,
-        )
-        yield* initialBlockingSyncContext.update({ processed: batch.length, pageInfo })
-      }),
-    ),
-    Stream.runDrain,
-    Effect.interruptible,
-    Effect.ensuring(releasePullMutexIfHeld),
-  )
-
-  // Should only ever happen when livePull is false
-  yield* Effect.logDebug('backend-pulling finished', { livePull })
-})
-
-const backgroundBackendPushing = Effect.fn('@livestore/common:LeaderSyncProcessor:backend-pushing')(function* ({
-  syncBackendPushQueue,
-  devtoolsLatch,
-  backendPushBatchSize,
-}: {
-  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.Client.EncodedWithMeta>
-  devtoolsLatch: Effect.Latch | undefined
-  backendPushBatchSize: number
-}) {
-  const { syncBackend } = yield* LeaderThreadCtx
-  if (syncBackend === undefined) return
-
-  while (true) {
-    yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
-
-    const queueItems = yield* BucketQueue.takeBetween(syncBackendPushQueue, 1, backendPushBatchSize)
-
-    yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
-
-    if (devtoolsLatch !== undefined) {
-      yield* devtoolsLatch.await
-    }
-
-    yield* Effect.spanEvent('backend-push', {
-      batchSize: queueItems.length,
-      ...(TRACE_VERBOSE === true ? { batch: jsonStringify(queueItems) } : {}),
-    })
-
-    // Push with declarative retry/backoff using Effect schedules
-    // - Exponential backoff starting at 1s and doubling (1s, 2s, 4s, 8s, 16s, 30s ...)
-    // - Delay clamped at 30s (continues retrying at 30s)
-    // - Resets automatically after successful push
-    // TODO(metrics): expose counters/gauges for retry attempts and queue health via devtools/metrics
-    yield* Effect.gen(function* () {
-      const iteration = yield* Schedule.CurrentIterationMetadata
-
-      const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.either)
-
-      const retries = iteration.recurrence
-      if (retries > 0 && pushResult._tag === 'Right') {
-        yield* Effect.spanEvent('backend-push-retry-success', { retries, batchSize: queueItems.length })
-      }
-
-      if (pushResult._tag === 'Left') {
-        yield* Effect.spanEvent('backend-push-error', {
-          error: pushResult.left.toString(),
-          retries,
-          batchSize: queueItems.length,
-        })
-        const error = pushResult.left
-        if (error._tag === 'ServerAheadError') {
-          // It's a core part of the sync protocol that the sync backend will emit a new pull chunk alongside the ServerAheadError
-          yield* Effect.logDebug('handled backend-push-error (waiting for interupt caused by pull)', { error })
-          return yield* Effect.never
-        }
-
-        return yield* error
-      }
-    }).pipe(
-      // Retry transient errors
-      Effect.retry({
-        schedule: Schedule.exponential(Duration.seconds(1)).pipe(
-          Schedule.modifyDelay((_, delay) => Duration.min(delay, Duration.seconds(30))) // Cap delay at 30s intervals.
-        ),
-        while: (error) => error._tag === 'IsOfflineError' || error._tag === 'UnknownError',
-      }),
-      // This is needed to narrow the Error type. Our retry policy runs indefinitely, but Effect.retry does not narrow the Error type.
-      Effect.catchIf((error) => error._tag === 'IsOfflineError' || error._tag === 'UnknownError', Effect.die),
-    )
-  }
-}, Effect.interruptible)
-
 const trimChangesetRows = (db: SqliteDb, newHead: EventSequenceNumber.Client.Composite) => {
   // Since we're using the session changeset rows to query for the current head,
   // we're keeping at least one row for the current head, and thus are using `<` instead of `<=`
@@ -964,9 +990,12 @@ const makePullQueueSet = Effect.gen(function* () {
 
   const makeQueue: PullQueueSet['makeQueue'] = (cursor) =>
     Effect.gen(function* () {
-      const queue = yield* Queue.unbounded<{
-        payload: typeof SyncState.PayloadUpstream.Type
-      }>().pipe(Effect.acquireRelease(Queue.shutdown))
+      const queue = yield* Effect.acquireRelease(
+        Queue.unbounded<{
+          payload: typeof SyncState.PayloadUpstream.Type
+        }>(),
+        Queue.shutdown,
+      )
 
       yield* Effect.addFinalizer(() => Effect.sync(() => set.delete(queue)))
 
@@ -1019,7 +1048,7 @@ const makePullQueueSet = Effect.gen(function* () {
       //   ]),
       // )
 
-      yield* queue.offerAll(payloadsSinceCursor)
+      yield* Queue.offerAll(queue, payloadsSinceCursor)
 
       set.add(queue)
 
@@ -1061,6 +1090,7 @@ const makePullQueueSet = Effect.gen(function* () {
 const validatePushBatch = (
   batch: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
   pushHead: EventSequenceNumber.Client.Composite,
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean,
 ) =>
   Effect.gen(function* () {
     if (batch.length === 0) {
@@ -1088,8 +1118,56 @@ const validatePushBatch = (
         sessionId: batch[0]!.sessionId,
       })
     }
+
+    // A rebase replaces the optimistic history that the client built on. Events from an older
+    // generation may now have the wrong parent and must be recreated from the leader's current head.
+    if (batch[0]!.seqNum.rebaseGeneration < pushHead.rebaseGeneration) {
+      return yield* StaleRebaseGenerationError.make({
+        currentRebaseGeneration: pushHead.rebaseGeneration,
+        providedRebaseGeneration: batch[0]!.seqNum.rebaseGeneration,
+        sessionId: batch[0]!.sessionId,
+      })
+    }
+
+    // Validate the batch as one unbroken chain starting at the admission fence. Checking only that
+    // numbers increase would still allow gaps or events that point at an unrelated parent.
+    let precedingSeqNum = pushHead
+    for (let i = 0; i < batch.length; i++) {
+      const event = batch[i]!
+      // Global events advance the global position; client-only events advance its client-local suffix.
+      const expectedPair = EventSequenceNumber.Client.nextPair({
+        seqNum: precedingSeqNum,
+        isClientOnly: isClientOnlyEvent(event),
+        rebaseGeneration: event.seqNum.rebaseGeneration,
+      })
+
+      if (
+        EventSequenceNumber.Client.isEqual(event.seqNum, expectedPair.seqNum) === false ||
+        isSameSequencePosition(event.parentSeqNum, expectedPair.parentSeqNum) === false
+      ) {
+        return yield* NonContiguousBatchError.make({
+          expectedSeqNum: expectedPair.seqNum,
+          providedSeqNum: event.seqNum,
+          expectedParentSeqNum: expectedPair.parentSeqNum,
+          providedParentSeqNum: event.parentSeqNum,
+          violationIndex: i,
+          sessionId: event.sessionId,
+        })
+      }
+
+      precedingSeqNum = event.seqNum
+    }
   })
 
+/**
+ * Parent linkage identifies a position in the event chain. Rebase generation describes the version
+ * of optimistic history, so it is validated on the event itself rather than as part of parent identity.
+ */
+const isSameSequencePosition = (
+  left: EventSequenceNumber.Client.Composite,
+  right: EventSequenceNumber.Client.Composite,
+) => left.global === right.global && left.client === right.client
+
 /**
  * Handles a BackendIdMismatchError based on the configured behavior.
  * This occurs when the sync backend has been reset and has a new identity.
@@ -1158,3 +1236,28 @@ const clearLocalDatabases = ({ dbEventlog, dbState }: { dbEventlog: SqliteDb; db
       dbState.execute(`DROP TABLE IF EXISTS "${name}"`)
     }
   })
+
+const snapshotTxQueue = <A>(queue: TxQueue.TxQueue<A>): Effect.Effect<ReadonlyArray<A>> =>
+  Effect.tx(
+    Effect.gen(function* () {
+      const items = yield* TxQueue.clear(queue)
+      yield* TxQueue.offerAll(queue, items)
+      return items
+    }),
+  )
+
+const takePrefixUntil = <A>(
+  queue: TxQueue.TxQueue<A>,
+  predicate: (value: A) => boolean,
+): Effect.Effect<ReadonlyArray<A>> =>
+  Effect.tx(
+    Effect.gen(function* () {
+      const items = yield* TxQueue.clear(queue)
+      const [prefix, rest] = ReadonlyArray.splitWhere(items, predicate)
+      yield* TxQueue.offerAll(queue, rest)
+      return prefix
+    }),
+  )
+
+/** Serialize value to JSON string for trace attributes */
+const jsonStringify = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown))