@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -1,8 +1,11 @@
-import { casesHandled, isNotUndefined, LS_DEV, shouldNeverHappen, 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,43 +13,47 @@ import {
   FiberHandle,
   Layer,
   Option,
-  OtelTracer,
-  pipe,
+  Predicate,
   Queue,
   ReadonlyArray,
+  References,
+  Result,
   Schedule,
+  Schema,
+  Semaphore,
   Stream,
   Subscribable,
   SubscriptionRef,
+  TxQueue,
 } from '@livestore/utils/effect'
-import type * as otel from '@opentelemetry/api'
-import {
-  type IntentionalShutdownCause,
-  type MaterializeError,
-  type SqliteDb,
-  UnexpectedError,
-} 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, getEventDef, LiveStoreEvent, SystemTables } from '../schema/mod.ts'
-import {
-  type InvalidPullError,
-  type InvalidPushError,
-  type IsOfflineError,
-  LeaderAheadError,
-  type SyncBackend,
-} from '../sync/sync.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 * as SyncState from '../sync/syncstate.ts'
 import { sql } from '../util.ts'
 import * as Eventlog from './eventlog.ts'
 import { rollback } from './materialize-event.ts'
-import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.ts'
+import {
+  isRejectedPushError,
+  LeaderAheadError,
+  NonContiguousBatchError,
+  NonMonotonicBatchError,
+  type RejectedPushError,
+  StaleRebaseGenerationError,
+} from './RejectedPushError.ts'
+import type { ShutdownChannel } from './shutdown-channel.ts'
+import type { InitialBlockingSyncContext } from './types.ts'
 import { LeaderThreadCtx } from './types.ts'
 
-type LocalPushQueueItem = [
-  event: LiveStoreEvent.EncodedWithMeta,
-  deferred: Deferred.Deferred<void, LeaderAheadError> | undefined,
-]
+export const TypeId = '~@livestore/common/LeaderSyncProcessor' as const
+export type TypeId = typeof TypeId
 
 /**
  * The LeaderSyncProcessor manages synchronization of events between
@@ -66,11 +73,11 @@ type LocalPushQueueItem = [
  *   - Maintains events in ascending order.
  *   - Uses `Deferred` objects to resolve/reject events based on application success.
  * - 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.
+ * - Controlled by a mutex (`Semaphore(1)`) to ensure mutual exclusion between local push and backend pull processing.
+ * - The backend pull side acquires the mutex before processing and releases it on post-pull completion.
  * - Processes up to `maxBatchSize` events per cycle.
  *
- * Currently we're advancing the state db and eventlog in lockstep, but we could also decouple this in the future
+ * Currently, we're advancing the state db 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.
@@ -78,660 +85,526 @@ type LocalPushQueueItem = [
  *
  * See ClientSessionSyncProcessor for how the leader and session sync processors are similar/different.
  */
-export const makeLeaderSyncProcessor = ({
-  schema,
-  dbState,
-  initialBlockingSyncContext,
-  initialSyncState,
-  onError,
-  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
-  onError: 'shutdown' | 'ignore'
-  params: {
+  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.
+   */
+  readonly onError: 'shutdown' | 'ignore'
+  /**
+   * What to do when the sync backend identity has changed (i.e. the backend was reset).
+   *
+   * - `'reset'`: Clear local databases (eventlog and state) and send an intentional shutdown signal.
+   * - `'shutdown'`: Send a shutdown signal without clearing local storage.
+   * - `'ignore'`: Continue running with stale data.
+   */
+  readonly onBackendIdMismatch: 'reset' | 'shutdown' | 'ignore'
+  readonly params: {
     /**
+     * Maximum number of local events to process per batch cycle.
+     *
+     * This controls how many events from client sessions are applied to the local state
+     * in a single iteration before yielding to allow potential backend pulls.
+     *
+     * **Trade-offs:**
+     * - **Lower values (1-5):** More responsive to remote updates since pull processing can
+     *   interleave more frequently. Better for high-conflict scenarios where rebases are common.
+     *   Slightly higher per-event overhead due to more frequent transaction commits.
+     *
+     * - **Higher values (10-50+):** Better throughput for bulk local writes as more events are
+     *   batched into a single transaction. However, may delay remote update processing and
+     *   increase rebase complexity if many local events queue up during a slow pull.
+     *
+     * - **Very high values (100+):** Risk of starvation for pull processing if local pushes
+     *   arrive continuously. May cause larger rollbacks during rebases. Not recommended
+     *   unless you have a write-heavy workload with minimal remote synchronization.
+     *
      * @default 10
      */
-    localPushBatchSize?: number
+    readonly localPushBatchSize?: number
     /**
+     * Maximum number of events to push to the sync backend per batch.
+     *
+     * This controls how many events are sent in a single push request to the remote server.
+     *
+     * **Trade-offs:**
+     * - **Lower values (1-10):** Lower latency for each push operation. Faster feedback on
+     *   push success/failure. Slightly higher network overhead due to more requests.
+     *
+     * - **Higher values (50-100):** Better network efficiency by amortizing request overhead.
+     *   Preferred for high-throughput scenarios. May increase latency to first confirmation.
+     *
+     * - **Very high values (200+):** Risk of hitting server request size limits or timeouts.
+     *   A single failed request loses the entire batch (will be retried). May cause memory
+     *   pressure if events accumulate faster than they can be pushed.
+     *
      * @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>
     }
-  }
-}): Effect.Effect<LeaderSyncProcessor, UnexpectedError, Scope.Scope> =>
-  Effect.gen(function* () {
-    const syncBackendPushQueue = yield* BucketQueue.make<LiveStoreEvent.EncodedWithMeta>()
-    const localPushBatchSize = params.localPushBatchSize ?? 1
-    const backendPushBatchSize = params.backendPushBatchSize ?? 2
-
-    const syncStateSref = yield* SubscriptionRef.make<SyncState.SyncState | undefined>(undefined)
-
-    const isClientEvent = (eventEncoded: LiveStoreEvent.EncodedWithMeta) => {
-      const { eventDef } = getEventDef(schema, eventEncoded.name)
-      return eventDef.options.clientOnly
+    readonly hooks?: {
+      readonly localPushAdmitted?: (events: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>) => Effect.Effect<void>
     }
+  }
+}
 
-    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
-        | {
-            otelSpan: otel.Span | undefined
-            span: Tracer.Span
-            devtoolsLatch: Effect.Latch | undefined
-            runtime: Runtime.Runtime<LeaderThreadCtx>
-          },
-    }
+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 localPushesQueue = yield* BucketQueue.make<LocalPushQueueItem>()
-    const localPushesLatch = yield* Effect.makeLatch(true)
-    const pullLatch = yield* Effect.makeLatch(true)
+  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)
 
-    /**
-     * 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.ROOT }
-    const advancePushHead = (eventNum: EventSequenceNumber.EventSequenceNumber) => {
-      pushHeadRef.current = EventSequenceNumber.max(pushHeadRef.current, eventNum)
-    }
+  /**
+   * 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 }
 
-    // NOTE: New events are only pushed to sync backend after successful local push processing
-    const push: LeaderSyncProcessor['push'] = (newEvents, options) =>
+  /**
+   * 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* () {
-        if (newEvents.length === 0) return
-
-        // console.debug('push', newEvents)
-
-        yield* validatePushBatch(newEvents, pushHeadRef.current)
-
-        advancePushHead(newEvents.at(-1)!.seqNum)
-
-        const waitForProcessing = options?.waitForProcessing ?? false
-
-        if (waitForProcessing) {
-          const deferreds = yield* Effect.forEach(newEvents, () => Deferred.make<void, LeaderAheadError>())
-
-          const items = newEvents.map((eventEncoded, i) => [eventEncoded, deferreds[i]] as LocalPushQueueItem)
-
-          yield* BucketQueue.offerAll(localPushesQueue, items)
-
-          yield* Effect.all(deferreds)
-        } else {
-          const items = newEvents.map((eventEncoded) => [eventEncoded, undefined] as LocalPushQueueItem)
-          yield* BucketQueue.offerAll(localPushesQueue, items)
-        }
-      }).pipe(
-        Effect.withSpan('@livestore/common:LeaderSyncProcessor:push', {
-          attributes: {
-            batchSize: newEvents.length,
-            batch: TRACE_VERBOSE ? newEvents : undefined,
-          },
-          links: ctxRef.current?.span ? [{ _tag: 'SpanLink', span: ctxRef.current.span, attributes: {} }] : undefined,
-        }),
-      )
-
-    const pushPartial: LeaderSyncProcessor['pushPartial'] = ({ event: { name, args }, clientId, sessionId }) =>
+        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* () {
-        const syncState = yield* syncStateSref
-        if (syncState === undefined) return shouldNeverHappen('Not initialized')
-
-        const { eventDef } = getEventDef(schema, name)
+        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 eventEncoded = new LiveStoreEvent.EncodedWithMeta({
-          name,
-          args,
-          clientId,
-          sessionId,
-          ...EventSequenceNumber.nextPair({ seqNum: syncState.localHead, isClient: eventDef.options.clientOnly }),
-        })
+  const backgroundApplyLocalPushes = Effect.gen(function* () {
+    while (true) {
+      if (testing.delays?.localPushProcessing !== undefined) {
+        yield* testing.delays.localPushProcessing.pipe(Effect.withSpan('localPushProcessingDelay'))
+      }
 
-        yield* push([eventEncoded])
-      }).pipe(Effect.catchTag('LeaderAheadError', Effect.orDie))
+      const batchItems = yield* TxQueue.takeBetween(localPushesQueue, 1, localPushBatchSize)
 
-    // Starts various background loops
-    const boot: LeaderSyncProcessor['boot'] = Effect.gen(function* () {
-      const span = yield* Effect.currentSpan.pipe(Effect.orDie)
-      const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.catchAll(() => Effect.succeed(undefined)))
-      const { devtools, shutdownChannel } = yield* LeaderThreadCtx
-      const runtime = yield* Effect.runtime<LeaderThreadCtx>()
+      // 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,
+        )
 
-      ctxRef.current = {
-        otelSpan,
-        span,
-        devtoolsLatch: devtools.enabled ? devtools.syncBackendLatch : undefined,
-        runtime,
-      }
+        const currentRebaseGeneration = syncState.localHead.rebaseGeneration
 
-      /** State transitions need to happen atomically, so we use a Ref to track the state */
-      yield* SubscriptionRef.set(syncStateSref, initialSyncState)
+        // 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),
+        )
 
-      // Rehydrate sync queue
-      if (initialSyncState.pending.length > 0) {
-        const globalPendingEvents = initialSyncState.pending
-          // Don't sync clientOnly events
-          .filter((eventEncoded) => {
-            const { eventDef } = getEventDef(schema, eventEncoded.name)
-            return eventDef.options.clientOnly === false
+        if (droppedItems.length > 0) {
+          yield* Effect.spanEvent(`push:drop-old-generation`, {
+            droppedCount: droppedItems.length,
+            currentRebaseGeneration,
           })
 
-        if (globalPendingEvents.length > 0) {
-          yield* BucketQueue.offerAll(syncBackendPushQueue, globalPendingEvents)
+          yield* Effect.forEach(droppedItems, ([eventEncoded, deferred]) =>
+            Deferred.fail(
+              deferred,
+              StaleRebaseGenerationError.make({
+                currentRebaseGeneration,
+                providedRebaseGeneration: eventEncoded.seqNum.rebaseGeneration,
+                sessionId: eventEncoded.sessionId,
+              }),
+            ),
+          )
+
+          yield* releasePushReservations(droppedItems, syncState.localHead)
         }
-      }
 
-      const maybeShutdownOnError = (
-        cause: Cause.Cause<
-          | UnexpectedError
-          | IntentionalShutdownCause
-          | IsOfflineError
-          | InvalidPushError
-          | InvalidPullError
-          | MaterializeError
-        >,
-      ) =>
-        Effect.gen(function* () {
-          if (onError === 'ignore') {
-            if (LS_DEV) {
-              yield* Effect.logDebug(
-                `Ignoring sync error (${cause._tag === 'Fail' ? cause.error._tag : cause._tag})`,
-                Cause.pretty(cause),
-              )
-            }
-            return
-          }
+        if (filteredItems.length === 0) {
+          return
+        }
 
-          const errorToSend = Cause.isFailType(cause) ? cause.error : UnexpectedError.make({ cause })
-          yield* shutdownChannel.send(errorToSend).pipe(Effect.orDie)
+        const [newEvents, deferreds] = ReadonlyArray.unzip(filteredItems)
 
-          return yield* Effect.die(cause)
+        yield* Effect.annotateCurrentSpan({
+          batchSize: newEvents.length,
+          ...(TRACE_VERBOSE === true ? { newEvents: jsonStringify(newEvents) } : {}),
         })
 
-      yield* backgroundApplyLocalPushes({
-        localPushesLatch,
-        localPushesQueue,
-        pullLatch,
-        syncStateSref,
-        syncBackendPushQueue,
-        schema,
-        isClientEvent,
-        otelSpan,
-        connectedClientSessionPullQueues,
-        localPushBatchSize,
-        testing: {
-          delay: testing?.delays?.localPushProcessing,
-        },
-      }).pipe(Effect.catchAllCause(maybeShutdownOnError), Effect.forkScoped)
-
-      const backendPushingFiberHandle = yield* FiberHandle.make<void, never>()
-      const backendPushingEffect = backgroundBackendPushing({
-        syncBackendPushQueue,
-        otelSpan,
-        devtoolsLatch: ctxRef.current?.devtoolsLatch,
-        backendPushBatchSize,
-      }).pipe(Effect.catchAllCause(maybeShutdownOnError))
-
-      yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
-
-      yield* backgroundBackendPulling({
-        isClientEvent,
-        restartBackendPushing: (filteredRebasedPending) =>
-          Effect.gen(function* () {
-            // Stop current pushing fiber
-            yield* FiberHandle.clear(backendPushingFiberHandle)
-
-            // Reset the sync backend push queue
-            yield* BucketQueue.clear(syncBackendPushQueue)
-            yield* BucketQueue.offerAll(syncBackendPushQueue, filteredRebasedPending)
-
-            // Restart pushing fiber
-            yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
-          }),
-        syncStateSref,
-        localPushesLatch,
-        pullLatch,
-        livePull,
-        dbState,
-        otelSpan,
-        initialBlockingSyncContext,
-        devtoolsLatch: ctxRef.current?.devtoolsLatch,
-        connectedClientSessionPullQueues,
-        advancePushHead,
-      }).pipe(
-        Effect.retry({
-          // We want to retry pulling if we've lost connection to the sync backend
-          while: (cause) => cause._tag === 'IsOfflineError',
-        }),
-        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,
-      )
-
-      return { initialLeaderHead: initialSyncState.localHead }
-    }).pipe(Effect.withSpanScoped('@livestore/common:LeaderSyncProcessor:boot'))
-
-    const pull: LeaderSyncProcessor['pull'] = ({ cursor }) =>
-      Effect.gen(function* () {
-        const queue = yield* pullQueue({ cursor })
-        return Stream.fromQueue(queue)
-      }).pipe(Stream.unwrapScoped)
-
-    /*
-    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 }) => {
-      const runtime = ctxRef.current?.runtime ?? shouldNeverHappen('Not initialized')
-      return connectedClientSessionPullQueues.makeQueue(cursor).pipe(Effect.provide(runtime))
-    }
-
-    const syncState = Subscribable.make({
-      get: Effect.gen(function* () {
-        const syncState = yield* syncStateSref
-        if (syncState === undefined) return shouldNeverHappen('Not initialized')
-        return syncState
-      }),
-      changes: syncStateSref.changes.pipe(Stream.filter(isNotUndefined)),
-    })
-
-    return {
-      pull,
-      pullQueue,
-      push,
-      pushPartial,
-      boot,
-      syncState,
-    } satisfies LeaderSyncProcessor
-  })
-
-const backgroundApplyLocalPushes = ({
-  localPushesLatch,
-  localPushesQueue,
-  pullLatch,
-  syncStateSref,
-  syncBackendPushQueue,
-  schema,
-  isClientEvent,
-  otelSpan,
-  connectedClientSessionPullQueues,
-  localPushBatchSize,
-  testing,
-}: {
-  pullLatch: Effect.Latch
-  localPushesLatch: Effect.Latch
-  localPushesQueue: BucketQueue.BucketQueue<LocalPushQueueItem>
-  syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
-  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.EncodedWithMeta>
-  schema: LiveStoreSchema
-  isClientEvent: (eventEncoded: LiveStoreEvent.EncodedWithMeta) => boolean
-  otelSpan: otel.Span | undefined
-  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'))
-      }
-
-      const batchItems = yield* BucketQueue.takeBetween(localPushesQueue, 1, localPushBatchSize)
-
-      // Wait for the backend pulling to finish
-      yield* localPushesLatch.await
-
-      // Prevent backend pull processing until this local push is finished
-      yield* pullLatch.close
-
-      const syncState = yield* syncStateSref
-      if (syncState === undefined) return shouldNeverHappen('Not initialized')
+        const mergeResult = yield* SyncState.merge({
+          syncState,
+          payload: { _tag: 'local-push', newEvents },
+          isClientOnlyEvent,
+          isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
+        })
 
-      const currentRebaseGeneration = syncState.localHead.rebaseGeneration
+        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) } : {}),
+            })
 
-      // 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 we got localPushesLatch, otherwise we might filter with the old generation
-      const [newEvents, deferreds] = pipe(
-        batchItems,
-        ReadonlyArray.filter(([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration === currentRebaseGeneration),
-        ReadonlyArray.unzip,
-      )
+            // TODO: how to test this?
+            const nextRebaseGeneration = currentRebaseGeneration + 1
 
-      if (newEvents.length === 0) {
-        // console.log('dropping old-gen batch', currentLocalPushGenerationRef.current)
-        // Allow the backend pulling to start
-        yield* pullLatch.open
-        continue
-      }
+            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 mergeResult = SyncState.merge({
-        syncState,
-        payload: { _tag: 'local-push', newEvents },
-        isClientEvent,
-        isEqualEvent: LiveStoreEvent.isEqualEncoded,
-      })
+            // 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
+            }
 
-      switch (mergeResult._tag) {
-        case 'unexpected-error': {
-          otelSpan?.addEvent(`push:unexpected-error`, {
-            batchSize: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-          })
-          return yield* new UnexpectedError({ cause: mergeResult.message })
-        }
-        case 'rebase': {
-          return shouldNeverHappen('The leader thread should never have to rebase due to a local push')
-        }
-        case 'reject': {
-          otelSpan?.addEvent(`push:reject`, {
-            batchSize: newEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-          })
+            const allDeferredsToReject = [
+              ...deferreds,
+              ...remainingEventsMatchingGeneration.map(([_, deferred]) => deferred),
+            ]
 
-          // TODO: how to test this?
-          const nextRebaseGeneration = currentRebaseGeneration + 1
+            // 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,
+            )
 
-          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,
-          )
+            yield* Effect.forEach(allDeferredsToReject, (deferred) =>
+              Deferred.fail(
+                deferred,
+                LeaderAheadError.make({
+                  minimumExpectedNum: mergeResult.expectedMinimumId,
+                  providedNum,
+                  sessionId: newEvents.at(0)!.sessionId,
+                }),
+              ),
+            )
 
-          // TODO we still need to better understand and handle this scenario
-          if (LS_DEV && (yield* BucketQueue.size(localPushesQueue)) > 0) {
-            console.log('localPushesQueue is not empty', yield* BucketQueue.size(localPushesQueue))
-            // biome-ignore lint/suspicious/noDebugger: debugging
-            debugger
+            // 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)
           }
-
-          const allDeferredsToReject = [
-            ...deferreds,
-            ...remainingEventsMatchingGeneration.map(([_, deferred]) => deferred),
-          ].filter(isNotUndefined)
-
-          yield* Effect.forEach(allDeferredsToReject, (deferred) =>
-            Deferred.fail(
-              deferred,
-              LeaderAheadError.make({ minimumExpectedNum: mergeResult.expectedMinimumId, providedNum }),
-            ),
-          )
-
-          // Allow the backend pulling to start
-          yield* pullLatch.open
-
-          // 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
-          continue
-        }
-        case 'advance': {
-          break
-        }
-        default: {
-          casesHandled(mergeResult)
         }
-      }
-
-      yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
-
-      yield* connectedClientSessionPullQueues.offer({
-        payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: mergeResult.newEvents }),
-        leaderHead: mergeResult.newSyncState.localHead,
-      })
-
-      otelSpan?.addEvent(`push:advance`, {
-        batchSize: newEvents.length,
-        mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-      })
 
-      // Don't sync clientOnly events
-      const filteredBatch = mergeResult.newEvents.filter((eventEncoded) => {
-        const { eventDef } = getEventDef(schema, eventEncoded.name)
-        return eventDef.options.clientOnly === false
-      })
-
-      yield* BucketQueue.offerAll(syncBackendPushQueue, filteredBatch)
+        // 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')
+        }
 
-      yield* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds })
+        yield* materializeEventsBatch({ batchItems: acceptedPendingEvents })
 
-      // Allow the backend pulling to start
-      yield* pullLatch.open
-    }
-  })
-
-type MaterializeEventsBatch = (_: {
-  batchItems: ReadonlyArray<LiveStoreEvent.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> | undefined> | undefined
-}) => Effect.Effect<void, MaterializeError, LeaderThreadCtx>
+        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
 
-// TODO how to handle errors gracefully
-const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems, deferreds }) =>
-  Effect.gen(function* () {
-    const { dbState: db, dbEventlog, materializeEvent } = yield* LeaderThreadCtx
+        yield* connectedClientSessionPullQueues.offer({
+          payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: acceptedPendingEvents }),
+          leaderHead: mergeResult.newSyncState.localHead,
+        })
 
-    // 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
-    dbEventlog.execute('BEGIN TRANSACTION', undefined) // Start the transaction
+        yield* Effect.spanEvent(`push:advance`, {
+          batchSize: newEvents.length,
+          ...(TRACE_VERBOSE === true ? { mergeResult: jsonStringify(mergeResult) } : {}),
+        })
 
-    yield* Effect.addFinalizer((exit) =>
-      Effect.gen(function* () {
-        if (Exit.isSuccess(exit)) return
+        // Don't sync client-only events
+        const globalOrUnknownEvents = acceptedPendingEvents.filter((e) => !isClientOnlyEvent(e))
 
-        // Rollback in case of an error
-        db.execute('ROLLBACK', undefined)
-        dbEventlog.execute('ROLLBACK', undefined)
-      }),
-    )
+        yield* TxQueue.offerAll(syncBackendPushQueue, globalOrUnknownEvents)
 
-    for (let i = 0; i < batchItems.length; i++) {
-      const { sessionChangeset, hash } = yield* materializeEvent(batchItems[i]!)
-      batchItems[i]!.meta.sessionChangeset = sessionChangeset
-      batchItems[i]!.meta.materializerHashLeader = hash
+        yield* releasePushReservations(filteredItems, mergeResult.newSyncState.localHead)
 
-      if (deferreds?.[i] !== undefined) {
-        yield* Deferred.succeed(deferreds[i]!, void 0)
-      }
+        // 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))
     }
+  })
 
-    db.execute('COMMIT', undefined) // Commit the transaction
-    dbEventlog.execute('COMMIT', undefined) // Commit the transaction
-  }).pipe(
-    Effect.uninterruptible,
-    Effect.scoped,
-    Effect.withSpan('@livestore/common:LeaderSyncProcessor:materializeEventItems', {
-      attributes: { batchSize: batchItems.length },
-    }),
-    Effect.tapCauseLogPretty,
-  )
-
-const backgroundBackendPulling = ({
-  isClientEvent,
-  restartBackendPushing,
-  otelSpan,
-  dbState,
-  syncStateSref,
-  localPushesLatch,
-  livePull,
-  pullLatch,
-  devtoolsLatch,
-  initialBlockingSyncContext,
-  connectedClientSessionPullQueues,
-  advancePushHead,
-}: {
-  isClientEvent: (eventEncoded: LiveStoreEvent.EncodedWithMeta) => boolean
-  restartBackendPushing: (
-    filteredRebasedPending: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
-  ) => Effect.Effect<void, UnexpectedError, LeaderThreadCtx | HttpClient.HttpClient>
-  otelSpan: otel.Span | undefined
-  syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
-  dbState: SqliteDb
-  localPushesLatch: Effect.Latch
-  pullLatch: Effect.Latch
-  livePull: boolean
-  devtoolsLatch: Effect.Latch | undefined
-  initialBlockingSyncContext: InitialBlockingSyncContext
-  connectedClientSessionPullQueues: PullQueueSet
-  advancePushHead: (eventNum: EventSequenceNumber.EventSequenceNumber) => void
-}) =>
-  Effect.gen(function* () {
+  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
 
-    const onNewPullChunk = (newEvents: LiveStoreEvent.EncodedWithMeta[], pageInfo: SyncBackend.PullResPageInfo) =>
-      Effect.gen(function* () {
-        if (newEvents.length === 0) return
-
-        if (devtoolsLatch !== undefined) {
-          yield* devtoolsLatch.await
-        }
-
-        // Prevent more local pushes from being processed until this pull is finished
-        yield* localPushesLatch.close
+    let pullMutexHeld = false
 
-        // Wait for pending local pushes to finish
-        yield* pullLatch.await
+    const releasePullMutexIfHeld = Effect.gen(function* () {
+      if (pullMutexHeld === false) return
+      pullMutexHeld = false
+      yield* localPushBackendPullMutex.release(1)
+    })
 
-        const syncState = yield* syncStateSref
-        if (syncState === undefined) return shouldNeverHappen('Not initialized')
+    const isPullPaginationComplete = (pageInfo: SyncBackend.PullResPageInfo) => pageInfo._tag === 'NoMore'
 
-        const mergeResult = SyncState.merge({
-          syncState,
-          payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
-          isClientEvent,
-          isEqualEvent: LiveStoreEvent.isEqualEncoded,
-          ignoreClientEvents: true,
-        })
+    const onNewPullChunk = (
+      newEvents: LiveStoreEvent.Client.EncodedWithMeta[],
+      pageInfo: SyncBackend.PullResPageInfo,
+    ) =>
+      Effect.gen(function* () {
+        if (ctxRef.current?.devtoolsLatch !== undefined) {
+          yield* ctxRef.current.devtoolsLatch.await
+        }
 
-        if (mergeResult._tag === 'reject') {
-          return shouldNeverHappen('The leader thread should never reject upstream advances')
-        } else if (mergeResult._tag === 'unexpected-error') {
-          otelSpan?.addEvent(`pull:unexpected-error`, {
-            newEventsCount: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-          })
-          return yield* new UnexpectedError({ cause: mergeResult.message })
+        if (newEvents.length === 0) {
+          if (isPullPaginationComplete(pageInfo) === true) {
+            yield* releasePullMutexIfHeld
+          }
+          return
         }
 
-        const newBackendHead = newEvents.at(-1)!.seqNum
+        // Prevent more local pushes from being processed until this pull pagination sequence is finished.
+        if (pullMutexHeld === false) {
+          yield* localPushBackendPullMutex.take(1)
+          pullMutexHeld = true
+        }
 
-        Eventlog.updateBackendHead(dbEventlog, newBackendHead)
+        const chunkExit = yield* Effect.gen(function* () {
+          const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(
+            Effect.orDieDebugger,
+          )
 
-        if (mergeResult._tag === 'rebase') {
-          otelSpan?.addEvent(`pull:rebase[${mergeResult.newSyncState.localHead.rebaseGeneration}]`, {
-            newEventsCount: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-            rollbackCount: mergeResult.rollbackEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+          yield* Effect.annotateCurrentSpan({
+            'merge.newEventsCount': newEvents.length,
+            ...(TRACE_VERBOSE === true ? { 'merge.newEvents': jsonStringify(newEvents) } : {}),
           })
 
-          const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
-            const { eventDef } = getEventDef(schema, event.name)
-            return eventDef.options.clientOnly === false
+          const mergeResult = yield* SyncState.merge({
+            syncState,
+            payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
+            isClientOnlyEvent,
+            isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
+            ignoreClientOnlyEvents: true,
           })
-          yield* restartBackendPushing(globalRebasedPendingEvents)
 
-          if (mergeResult.rollbackEvents.length > 0) {
-            yield* rollback({
-              dbState: db,
-              dbEventlog,
-              eventNumsToRollback: mergeResult.rollbackEvents.map((_) => _.seqNum),
-            })
+          if (mergeResult._tag === 'reject') {
+            return yield* Effect.dieDebugger('The leader thread should never reject upstream advances')
           }
 
-          yield* connectedClientSessionPullQueues.offer({
-            payload: SyncState.payloadFromMergeResult(mergeResult),
-            leaderHead: mergeResult.newSyncState.localHead,
-          })
-        } else {
-          otelSpan?.addEvent(`pull:advance`, {
-            newEventsCount: newEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-          })
+          const newBackendHead = newEvents.at(-1)!.seqNum
 
-          // Ensure push fiber is active after advance by restarting with current pending (non-client) events
-          const globalPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
-            const { eventDef } = getEventDef(schema, event.name)
-            return eventDef.options.clientOnly === false
-          })
-          yield* restartBackendPushing(globalPendingEvents)
+          Eventlog.updateBackendHead(dbEventlog, newBackendHead)
 
-          yield* connectedClientSessionPullQueues.offer({
-            payload: SyncState.payloadFromMergeResult(mergeResult),
-            leaderHead: mergeResult.newSyncState.localHead,
-          })
+          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) } : {}),
+            })
 
-          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.isEqual(event.seqNum, confirmedEvent.seqNum),
-              ),
+            const globalOrUnknownRebasedPendingEvents = mergeResult.newSyncState.pending.filter(
+              (e) => !isClientOnlyEvent(e),
             )
-            yield* Eventlog.updateSyncMetadata(confirmedNewEvents).pipe(UnexpectedError.mapToUnexpectedError)
+            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)
+            }
           }
-        }
 
-        // Removes the changeset rows which are no longer needed as we'll never have to rollback beyond this point
-        trimChangesetRows(db, newBackendHead)
+          // 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)
+          // 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* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds: undefined })
+          // 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 })
 
-        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
+          yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
+        }).pipe(Effect.exit)
+
+        if (Exit.isFailure(chunkExit) === true) {
+          yield* releasePullMutexIfHeld
+          return yield* Effect.failCause(chunkExit.cause)
+        }
 
-        // Allow local pushes to be processed again
-        if (pageInfo._tag === 'NoMore') {
-          yield* localPushesLatch.open
+        if (isPullPaginationComplete(pageInfo) === true) {
+          yield* releasePullMutexIfHeld
         }
       })
 
-    const syncState = yield* syncStateSref
-    if (syncState === undefined) return shouldNeverHappen('Not initialized')
+    const syncState = yield* Effect.fromNullishOr(yield* SubscriptionRef.get(syncStateSref)).pipe(Effect.orDieDebugger)
     const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo({ remoteHead: syncState.upstreamHead.global })
 
     const hashMaterializerResult = makeMaterializerHash({ schema, dbState })
@@ -740,23 +613,17 @@ const backgroundBackendPulling = ({
       // TODO only take from queue while connected
       Stream.tap(({ batch, pageInfo }) =>
         Effect.gen(function* () {
-          // yield* Effect.spanEvent('batch', {
-          //   attributes: {
-          //     batchSize: batch.length,
-          //     batch: TRACE_VERBOSE ? batch : undefined,
-          //   },
-          // })
           // 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.EncodedWithMeta.fromGlobal(_.eventEncoded, {
+              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.encodedFromGlobal(_.eventEncoded)),
+                materializerHashLeader: hashMaterializerResult(LiveStoreEvent.Global.toClientEncoded(_.eventEncoded)),
                 materializerHashSession: Option.none(),
               }),
             ),
@@ -767,41 +634,31 @@ const backgroundBackendPulling = ({
       ),
       Stream.runDrain,
       Effect.interruptible,
+      Effect.ensuring(releasePullMutexIfHeld),
     )
 
     // Should only ever happen when livePull is false
     yield* Effect.logDebug('backend-pulling finished', { livePull })
-  }).pipe(Effect.withSpan('@livestore/common:LeaderSyncProcessor:backend-pulling'))
+  })
 
-const backgroundBackendPushing = ({
-  syncBackendPushQueue,
-  otelSpan,
-  devtoolsLatch,
-  backendPushBatchSize,
-}: {
-  syncBackendPushQueue: BucketQueue.BucketQueue<LiveStoreEvent.EncodedWithMeta>
-  otelSpan: otel.Span | undefined
-  devtoolsLatch: Effect.Latch | undefined
-  backendPushBatchSize: number
-}) =>
-  Effect.gen(function* () {
+  const backgroundBackendPushing = Effect.gen(function* () {
     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)
+      const queueItems = yield* TxQueue.takeBetween(syncBackendPushQueue, 1, backendPushBatchSize)
 
       yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
-      if (devtoolsLatch !== undefined) {
-        yield* devtoolsLatch.await
+      if (ctxRef.current?.devtoolsLatch !== undefined) {
+        yield* ctxRef.current.devtoolsLatch.await
       }
 
-      otelSpan?.addEvent('backend-push', {
+      yield* Effect.spanEvent('backend-push', {
         batchSize: queueItems.length,
-        batch: TRACE_VERBOSE ? JSON.stringify(queueItems) : undefined,
+        ...(TRACE_VERBOSE === true ? { batch: jsonStringify(queueItems) } : {}),
       })
 
       // Push with declarative retry/backoff using Effect schedules
@@ -809,40 +666,24 @@ const backgroundBackendPushing = ({
       // - 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
-
-      // Only retry for transient UnexpectedError cases
-      const isRetryable = (err: InvalidPushError | IsOfflineError) =>
-        err._tag === 'InvalidPushError' && err.cause._tag === 'LiveStore.UnexpectedError'
-
-      // Input: InvalidPushError | IsOfflineError, Output: Duration
-      const retrySchedule: Schedule.Schedule<Duration.DurationInput, InvalidPushError | IsOfflineError> =
-        Schedule.exponential(Duration.seconds(1)).pipe(
-          Schedule.andThenEither(Schedule.spaced(Duration.seconds(30))), // clamp at 30 second intervals
-          Schedule.compose(Schedule.elapsed),
-          Schedule.whileInput(isRetryable),
-        )
-
       yield* Effect.gen(function* () {
-        const iteration = yield* Schedule.CurrentIterationMetadata
+        const iteration = yield* Schedule.CurrentMetadata
 
-        const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.either)
+        const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.result)
 
-        const retries = iteration.recurrence
-        if (retries > 0 && pushResult._tag === 'Right') {
-          otelSpan?.addEvent('backend-push-retry-success', { retries, batchSize: queueItems.length })
+        const retries = iteration.attempt
+        if (retries > 0 && Result.isSuccess(pushResult) === true) {
+          yield* Effect.spanEvent('backend-push-retry-success', { retries, batchSize: queueItems.length })
         }
 
-        if (pushResult._tag === 'Left') {
-          otelSpan?.addEvent('backend-push-error', {
-            error: pushResult.left.toString(),
+        if (Result.isFailure(pushResult) === true) {
+          yield* Effect.spanEvent('backend-push-error', {
+            error: pushResult.failure.toString(),
             retries,
             batchSize: queueItems.length,
           })
-          const error = pushResult.left
-          if (
-            error._tag === 'IsOfflineError' ||
-            (error._tag === 'InvalidPushError' && error.cause._tag === 'ServerAheadError')
-          ) {
+          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
@@ -850,11 +691,267 @@ const backgroundBackendPushing = ({
 
           return yield* error
         }
-      }).pipe(Effect.retry(retrySchedule))
+      }).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, Effect.withSpan('@livestore/common:LeaderSyncProcessor:backend-pushing'))
+  }).pipe(Effect.interruptible)
+
+  // 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 trimChangesetRows = (db: SqliteDb, newHead: EventSequenceNumber.EventSequenceNumber) => {
+      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 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
+          }
+
+          const error = Option.getOrUndefined(Cause.findErrorOption(cause))
+          const errorToSend = error === undefined ? UnknownError.make({ cause }) : error
+          yield* shutdownChannel.send(errorToSend).pipe(Effect.orDie)
+
+          return yield* Effect.failCause(cause).pipe(Effect.orDie)
+        })
+
+      yield* backgroundApplyLocalPushes.pipe(Effect.catchCause(maybeShutdownOnError), Effect.forkScoped)
+
+      const backendPushingFiberHandle = yield* FiberHandle.make<void, never>()
+      const backendPushingEffect = backgroundBackendPushing.pipe(
+        Effect.catchTag('BackendIdMismatchError', handleBackendIdMismatchError),
+        Effect.catchCause(maybeShutdownOnError),
+      )
+
+      yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect)
+
+      yield* backgroundBackendPulling({
+        restartBackendPushing: (filteredRebasedPending) =>
+          Effect.gen(function* () {
+            // Stop current pushing fiber
+            yield* FiberHandle.clear(backendPushingFiberHandle)
+
+            // Reset the sync backend push queue
+            yield* TxQueue.clear(syncBackendPushQueue)
+            yield* TxQueue.offerAll(syncBackendPushQueue, filteredRebasedPending)
+
+            // 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,
+      )
+
+      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,
+        )
+
+        const resolution = yield* resolveEventDef(schema, {
+          operation: '@livestore/common:LeaderSyncProcessor:pushPartial',
+          event: {
+            name,
+            args,
+            clientId,
+            sessionId,
+            seqNum: syncState.localHead,
+          },
+        })
+
+        if (resolution._tag === 'unknown') {
+          // Ignore partial pushes for unrecognised events – they are still
+          // persisted server-side once a schema update ships.
+          return
+        }
+
+        const eventEncoded = new LiveStoreEvent.Client.EncodedWithMeta({
+          name,
+          args,
+          clientId,
+          sessionId,
+          ...EventSequenceNumber.Client.nextPair({
+            seqNum: syncState.localHead,
+            isClientOnly: resolution.eventDef.options.clientOnly,
+          }),
+        })
+
+        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>
+}) => Effect.Effect<void, MaterializeError, LeaderThreadCtx>
+
+// TODO how to handle errors gracefully
+const materializeEventsBatch: MaterializeEventsBatch = ({ batchItems }) =>
+  Effect.gen(function* () {
+    const { dbState: db, dbEventlog, materializeEvent } = yield* LeaderThreadCtx
+
+    // 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
+    dbEventlog.execute('BEGIN TRANSACTION', undefined) // Start the transaction
+
+    yield* Effect.addFinalizer((exit) =>
+      Effect.gen(function* () {
+        if (Exit.isSuccess(exit) === true) return
+
+        // Rollback in case of an error
+        db.execute('ROLLBACK', undefined)
+        dbEventlog.execute('ROLLBACK', undefined)
+      }),
+    )
+
+    for (let i = 0; i < batchItems.length; i++) {
+      const { sessionChangeset, hash } = yield* materializeEvent(batchItems[i]!)
+      batchItems[i]!.meta.sessionChangeset = sessionChangeset
+      batchItems[i]!.meta.materializerHashLeader = hash
+    }
+
+    db.execute('COMMIT', undefined) // Commit the transaction
+    dbEventlog.execute('COMMIT', undefined) // Commit the transaction
+  }).pipe(
+    Effect.uninterruptible,
+    Effect.scoped,
+    Effect.withSpan('@livestore/common:LeaderSyncProcessor:materializeEventItems', {
+      attributes: { batchSize: batchItems.length },
+    }),
+    Effect.tapCauseLogPretty,
+  )
+
+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 `<=`
   db.execute(sql`DELETE FROM ${SystemTables.SESSION_CHANGESET_META_TABLE} WHERE seqNumGlobal < ${newHead.global}`)
@@ -862,16 +959,16 @@ const trimChangesetRows = (db: SqliteDb, newHead: EventSequenceNumber.EventSeque
 
 interface PullQueueSet {
   makeQueue: (
-    cursor: EventSequenceNumber.EventSequenceNumber,
+    cursor: EventSequenceNumber.Client.Composite,
   ) => Effect.Effect<
     Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>,
-    UnexpectedError,
+    never,
     Scope.Scope | LeaderThreadCtx
   >
   offer: (item: {
     payload: typeof SyncState.PayloadUpstream.Type
-    leaderHead: EventSequenceNumber.EventSequenceNumber
-  }) => Effect.Effect<void, UnexpectedError>
+    leaderHead: EventSequenceNumber.Client.Composite
+  }) => Effect.Effect<void, never>
 }
 
 const makePullQueueSet = Effect.gen(function* () {
@@ -893,25 +990,28 @@ 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)))
 
       const payloadsSinceCursor = Array.from(cachedPayloads.entries())
         .flatMap(([seqNumStr, payloads]) =>
-          payloads.map((payload) => ({ payload, seqNum: EventSequenceNumber.fromString(seqNumStr) })),
+          payloads.map((payload) => ({ payload, seqNum: EventSequenceNumber.Client.fromString(seqNumStr) })),
         )
-        .filter(({ seqNum }) => EventSequenceNumber.isGreaterThan(seqNum, cursor))
-        .toSorted((a, b) => EventSequenceNumber.compare(a.seqNum, b.seqNum))
+        .filter(({ seqNum }) => EventSequenceNumber.Client.isGreaterThan(seqNum, cursor))
+        .toSorted((a, b) => EventSequenceNumber.Client.compare(a.seqNum, b.seqNum))
         .map(({ payload }) => {
           if (payload._tag === 'upstream-advance') {
             return {
               payload: {
                 _tag: 'upstream-advance' as const,
                 newEvents: ReadonlyArray.dropWhile(payload.newEvents, (eventEncoded) =>
-                  EventSequenceNumber.isGreaterThanOrEqual(cursor, eventEncoded.seqNum),
+                  EventSequenceNumber.Client.isGreaterThanOrEqual(cursor, eventEncoded.seqNum),
                 ),
               },
             }
@@ -948,7 +1048,7 @@ const makePullQueueSet = Effect.gen(function* () {
       //   ]),
       // )
 
-      yield* queue.offerAll(payloadsSinceCursor)
+      yield* Queue.offerAll(queue, payloadsSinceCursor)
 
       set.add(queue)
 
@@ -957,8 +1057,8 @@ const makePullQueueSet = Effect.gen(function* () {
 
   const offer: PullQueueSet['offer'] = (item) =>
     Effect.gen(function* () {
-      const seqNumStr = EventSequenceNumber.toString(item.leaderHead)
-      if (cachedPayloads.has(seqNumStr)) {
+      const seqNumStr = EventSequenceNumber.Client.toString(item.leaderHead)
+      if (cachedPayloads.has(seqNumStr) === true) {
         cachedPayloads.get(seqNumStr)!.push(item.payload)
       } else {
         cachedPayloads.set(seqNumStr, [item.payload])
@@ -982,29 +1082,182 @@ const makePullQueueSet = Effect.gen(function* () {
   }
 })
 
+/**
+ * Validate a client-provided batch before it is admitted to the leader queue.
+ * Ensures the numbers form a strictly increasing chain and that the first
+ * event sits ahead of the current push head.
+ */
 const validatePushBatch = (
-  batch: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
-  pushHead: EventSequenceNumber.EventSequenceNumber,
+  batch: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
+  pushHead: EventSequenceNumber.Client.Composite,
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean,
 ) =>
   Effect.gen(function* () {
     if (batch.length === 0) {
       return
     }
 
-    // Make sure batch is monotonically increasing
+    // Defensive check: callers should already provide a strictly increasing sequence
+    // of event numbers.
     for (let i = 1; i < batch.length; i++) {
-      if (EventSequenceNumber.isGreaterThanOrEqual(batch[i - 1]!.seqNum, batch[i]!.seqNum)) {
-        shouldNeverHappen(
-          `Events must be ordered in monotonically ascending order by eventNum. Received: [${batch.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
-        )
+      if (EventSequenceNumber.Client.isGreaterThanOrEqual(batch[i - 1]!.seqNum, batch[i]!.seqNum) === true) {
+        return yield* NonMonotonicBatchError.make({
+          precedingSeqNum: batch[i - 1]!.seqNum,
+          violatingSeqNum: batch[i]!.seqNum,
+          violationIndex: i,
+          sessionId: batch[i]!.sessionId,
+        })
       }
     }
 
-    // Make sure smallest sequence number is > pushHead
-    if (EventSequenceNumber.isGreaterThanOrEqual(pushHead, batch[0]!.seqNum)) {
+    // Reject stale batches whose first event is at or behind the leader's push head.
+    if (EventSequenceNumber.Client.isGreaterThanOrEqual(pushHead, batch[0]!.seqNum) === true) {
       return yield* LeaderAheadError.make({
         minimumExpectedNum: pushHead,
         providedNum: batch[0]!.seqNum,
+        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.
+ */
+const handleBackendIdMismatch = Effect.fn('@livestore/common:LeaderSyncProcessor:handleBackendIdMismatch')(function* ({
+  error,
+  onBackendIdMismatch,
+  shutdownChannel,
+}: {
+  error: BackendIdMismatchError
+  onBackendIdMismatch: 'reset' | 'shutdown' | 'ignore'
+  shutdownChannel: ShutdownChannel
+}) {
+  const { dbEventlog, dbState } = yield* LeaderThreadCtx
+
+  if (onBackendIdMismatch === 'reset') {
+    yield* Effect.logWarning(
+      'Sync backend identity changed (backend was reset). Clearing local storage and shutting down.',
+      error,
+    )
+
+    // Clear local databases so the client can start fresh on next boot
+    yield* clearLocalDatabases({ dbEventlog, dbState })
+
+    // Send shutdown signal with special reason
+    yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'backend-id-mismatch' })).pipe(Effect.orDie)
+
+    return yield* Effect.die(error)
+  }
+
+  if (onBackendIdMismatch === 'shutdown') {
+    yield* Effect.logWarning(
+      'Sync backend identity changed (backend was reset). Shutting down without clearing local storage.',
+      error,
+    )
+
+    yield* shutdownChannel.send(error).pipe(Effect.orDie)
+
+    return yield* Effect.die(error)
+  }
+
+  // ignore mode
+  if (LS_DEV === true) {
+    yield* Effect.logDebug(
+      'Ignoring BackendIdMismatchError (sync backend was reset but client continues with stale data)',
+      error,
+    )
+  }
+})
+
+/**
+ * Clears local databases (eventlog and state) so the client can start fresh on next boot.
+ * This is used when the sync backend identity has changed (i.e. backend was reset).
+ */
+const clearLocalDatabases = ({ dbEventlog, dbState }: { dbEventlog: SqliteDb; dbState: SqliteDb }) =>
+  Effect.sync(() => {
+    // Clear eventlog tables
+    dbEventlog.execute(sql`DELETE FROM ${EVENTLOG_META_TABLE}`)
+    dbEventlog.execute(sql`DELETE FROM ${SYNC_STATUS_TABLE}`)
+
+    // Drop all state tables - they'll be recreated on next boot
+    const tables = dbState.select<{ name: string }>(
+      sql`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`,
+    )
+    for (const { name } of tables) {
+      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))