@livestore/common 0.4.0-dev.2 → 0.4.0-dev.20

package/src/sync/sync-backend.ts

@@ -0,0 +1,185 @@
+import {
+  type Cause,
+  type Effect,
+  type HttpClient,
+  type KeyValueStore,
+  Option,
+  Schema,
+  type Scope,
+  type Stream,
+  type SubscriptionRef,
+} from '@livestore/utils/effect'
+import type { UnknownError } from '../adapter-types.ts'
+import type * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
+import type { EventSequenceNumber } from '../schema/mod.ts'
+import type { InvalidPullError, InvalidPushError, IsOfflineError } from './errors.ts'
+
+export * from './sync-backend-kv.ts'
+
+/**
+ * Those arguments can be used to implement multi-tenancy etc and are passed in from the store.
+ */
+export type MakeBackendArgs<TPayload = Schema.JsonValue> = {
+  storeId: string
+  clientId: string
+  payload: TPayload | undefined
+}
+
+// TODO rename to `SyncProviderClientConstructor`
+export type SyncBackendConstructor<TSyncMetadata = Schema.JsonValue, TPayload = Schema.JsonValue> = (
+  args: MakeBackendArgs<TPayload>,
+) => Effect.Effect<
+  SyncBackend<TSyncMetadata>,
+  UnknownError,
+  Scope.Scope | HttpClient.HttpClient | KeyValueStore.KeyValueStore
+>
+
+// TODO add more runtime sync metadata/metrics
+// - latency histogram
+// - number of events pushed/pulled
+// - dynamic sync backend data;
+//   - data center location (e.g. colo on CF workers)
+
+// TODO rename to `SyncProviderClient`
+export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
+  /**
+   * Can be implemented to prepare a connection to the sync backend to speed up the first pull/push.
+   */
+  connect: Effect.Effect<void, IsOfflineError | UnknownError, Scope.Scope>
+  pull: (
+    cursor: Option.Option<{
+      eventSequenceNumber: EventSequenceNumber.Global.Type
+      /** Metadata is needed by some sync backends */
+      metadata: Option.Option<TSyncMetadata>
+    }>,
+    options?: {
+      /**
+       * If true, the sync backend will return a stream of events that have been pushed after the cursor.
+       *
+       * @default false
+       */
+      live?: boolean
+    },
+  ) => Stream.Stream<PullResItem<TSyncMetadata>, IsOfflineError | InvalidPullError>
+  // TODO support transactions (i.e. group of mutation events which need to be applied together)
+  push: (
+    /**
+     * Constraints for batch:
+     * - Number of events: 1-100
+     * - sequence numbers must be in ascending order
+     * */
+    batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+  ) => Effect.Effect<void, IsOfflineError | InvalidPushError>
+  ping: Effect.Effect<void, IsOfflineError | UnknownError | Cause.TimeoutException>
+  // TODO also expose latency information additionally to whether the backend is connected
+  isConnected: SubscriptionRef.SubscriptionRef<boolean>
+  /**
+   * Metadata describing the sync backend. (Currently only used by devtools.)
+   */
+  metadata: { name: string; description: string } & Record<string, Schema.JsonValue>
+  /** Information about the sync backend capabilities. */
+  supports: {
+    /**
+     * Whether the sync backend supports the `hasMore` field in the pull response.
+     */
+    pullPageInfoKnown: boolean
+    /**
+     * Whether the sync backend supports the `live` option for the pull method and thus
+     * long-lived, reactive pull streams.
+     */
+    pullLive: boolean
+  }
+}
+
+/**
+ * Connectivity metadata emitted by sync backends.
+ */
+export const NetworkStatus = Schema.Struct({
+  /** True when the upstream sync backend is reachable and responding to health checks. */
+  isConnected: Schema.Boolean,
+  /** Unix epoch timestamp (ms) of the latest connectivity state transition. */
+  timestampMs: Schema.Number,
+  /** Devtools specific metadata describing simulator overrides. */
+  devtools: Schema.Struct({
+    /** Indicates whether the devtools latch forced the client into an offline state. */
+    latchClosed: Schema.Boolean,
+  }),
+}).annotations({ title: 'NetworkStatus' })
+
+export type NetworkStatus = typeof NetworkStatus.Type
+
+/**
+ * Runtime type guard for SyncBackend objects.
+ * Performs lightweight structural checks on the object shape.
+ */
+export const isSyncBackend = (value: unknown): value is SyncBackend<any> => {
+  if (typeof value !== 'object' || value === null) return false
+
+  const v: any = value
+  const hasCoreFns =
+    typeof v.connect === 'function' &&
+    typeof v.pull === 'function' &&
+    typeof v.push === 'function' &&
+    typeof v.ping === 'function'
+
+  const hasSupports =
+    typeof v.supports === 'object' &&
+    v.supports !== null &&
+    typeof v.supports.pullPageInfoKnown === 'boolean' &&
+    typeof v.supports.pullLive === 'boolean'
+
+  const hasMetadata =
+    typeof v.metadata === 'object' &&
+    v.metadata !== null &&
+    typeof v.metadata.name === 'string' &&
+    typeof v.metadata.description === 'string'
+
+  const hasIsConnected = typeof v.isConnected === 'object' && v.isConnected !== null
+
+  return hasCoreFns && hasSupports && hasMetadata && hasIsConnected
+}
+
+export const PullResPageInfo = Schema.Union(
+  Schema.TaggedStruct('MoreUnknown', {}),
+  Schema.TaggedStruct('MoreKnown', {
+    remaining: Schema.Number,
+  }),
+  Schema.TaggedStruct('NoMore', {}),
+)
+
+export type PullResPageInfo = typeof PullResPageInfo.Type
+
+export const pageInfoNoMore: PullResPageInfo = { _tag: 'NoMore' } as const
+export const pageInfoMoreUnknown: PullResPageInfo = { _tag: 'MoreUnknown' } as const
+export const pageInfoMoreKnown = (remaining: number): PullResPageInfo => ({ _tag: 'MoreKnown', remaining })
+
+export const pullResItemEmpty = <TSyncMetadata = Schema.JsonValue>(): PullResItem<TSyncMetadata> => ({
+  batch: [],
+  pageInfo: pageInfoNoMore,
+})
+
+export interface PullResItem<TSyncMetadata = Schema.JsonValue> {
+  batch: ReadonlyArray<{
+    eventEncoded: LiveStoreEvent.Global.Encoded
+    metadata: Option.Option<TSyncMetadata>
+  }>
+  pageInfo: PullResPageInfo
+}
+
+export const of = <TSyncMetadata = Schema.JsonValue>(obj: SyncBackend<TSyncMetadata>) => obj
+
+/**
+ * Useful to continue pulling from the last event in the batch.
+ */
+export const cursorFromPullResItem = <TSyncMetadata = Schema.JsonValue>(
+  item: PullResItem<TSyncMetadata>,
+): Option.Option<{
+  eventSequenceNumber: EventSequenceNumber.Global.Type
+  metadata: Option.Option<TSyncMetadata>
+}> => {
+  const lastEvent = item.batch.at(-1)
+  if (!lastEvent) {
+    return Option.none()
+  }
+  return Option.some({ eventSequenceNumber: lastEvent.eventEncoded.seqNum, metadata: lastEvent.metadata })
+}

package/src/sync/sync.ts

@@ -1,22 +1,12 @@
-import type { Effect, HttpClient, Option, Scope, Stream, SubscriptionRef } from '@livestore/utils/effect'
-import { Schema } from '@livestore/utils/effect'
+export * from './errors.ts'
+export * as SyncBackend from './sync-backend.ts'
 
-import type { UnexpectedError } from '../adapter-types.ts'
+import type { Schema } from '@livestore/utils/effect'
 import type { InitialSyncOptions } from '../leader-thread/types.ts'
-import * as EventSequenceNumber from '../schema/EventSequenceNumber.ts'
-import type * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
+import type { SyncBackendConstructor } from './sync-backend.ts'
 
-/**
- * Those arguments can be used to implement multi-tenancy etc and are passed in from the store.
- */
-export type MakeBackendArgs = {
-  storeId: string
-  clientId: string
-  payload: Schema.JsonValue | undefined
-}
-
-export type SyncOptions = {
-  backend?: SyncBackendConstructor<any>
+export type SyncOptions<TPayload = Schema.JsonValue> = {
+  backend?: SyncBackendConstructor<any, TPayload>
   /** @default { _tag: 'Skip' } */
   initialSyncOptions?: InitialSyncOptions
   /**
@@ -29,81 +19,9 @@ export type SyncOptions = {
    * @default 'ignore'
    * */
   onSyncError?: 'shutdown' | 'ignore'
-}
-
-// TODO rename to `SyncProviderClientConstructor`
-export type SyncBackendConstructor<TSyncMetadata = Schema.JsonValue> = (
-  args: MakeBackendArgs,
-) => Effect.Effect<SyncBackend<TSyncMetadata>, UnexpectedError, Scope.Scope | HttpClient.HttpClient>
-
-// TODO add more runtime sync metadata
-// - latency histogram
-// - number of events pushed/pulled
-// - dynamic sync backend data;
-//   - data center location (e.g. colo on CF workers)
-
-// TODO rename to `SyncProviderClient`
-export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   /**
-   * Can be implemented to prepare a connection to the sync backend to speed up the first pull/push.
+   * Whether the sync backend should reactively pull new events from the sync backend
+   * @default true
    */
-  connect: Effect.Effect<void, IsOfflineError | UnexpectedError, HttpClient.HttpClient | Scope.Scope>
-  pull: (
-    args: Option.Option<{
-      cursor: EventSequenceNumber.EventSequenceNumber
-      metadata: Option.Option<TSyncMetadata>
-    }>,
-  ) => Stream.Stream<
-    {
-      batch: ReadonlyArray<{
-        eventEncoded: LiveStoreEvent.AnyEncodedGlobal
-        metadata: Option.Option<TSyncMetadata>
-      }>
-      remaining: number
-    },
-    IsOfflineError | InvalidPullError,
-    HttpClient.HttpClient
-  >
-  // TODO support transactions (i.e. group of mutation events which need to be applied together)
-  push: (
-    /**
-     * Constraints for batch:
-     * - Number of events: 1-100
-     * - sequence numbers must be in ascending order
-     * */
-    batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>,
-  ) => Effect.Effect<void, IsOfflineError | InvalidPushError, HttpClient.HttpClient>
-  isConnected: SubscriptionRef.SubscriptionRef<boolean>
-  /**
-   * Metadata describing the sync backend. (Currently only used by devtools.)
-   */
-  metadata: { name: string; description: string } & Record<string, Schema.JsonValue>
+  livePull?: boolean
 }
-
-export class IsOfflineError extends Schema.TaggedError<IsOfflineError>()('IsOfflineError', {}) {}
-
-// TODO gt rid of this error in favour of SyncError
-export class InvalidPushError extends Schema.TaggedError<InvalidPushError>()('InvalidPushError', {
-  reason: Schema.Union(
-    Schema.TaggedStruct('Unexpected', {
-      message: Schema.String,
-    }),
-    Schema.TaggedStruct('ServerAhead', {
-      minimumExpectedNum: Schema.Number,
-      providedNum: Schema.Number,
-    }),
-  ),
-}) {}
-
-// TODO gt rid of this error in favour of SyncError
-export class InvalidPullError extends Schema.TaggedError<InvalidPullError>()('InvalidPullError', {
-  message: Schema.String,
-}) {}
-
-// TODO gt rid of this error in favour of SyncError
-export class LeaderAheadError extends Schema.TaggedError<LeaderAheadError>()('LeaderAheadError', {
-  minimumExpectedNum: EventSequenceNumber.EventSequenceNumber,
-  providedNum: EventSequenceNumber.EventSequenceNumber,
-  /** Generation number the client session should use for subsequent pushes */
-  // nextGeneration: Schema.Number,
-}) {}

package/src/sync/syncstate.test.ts

@@ -1,31 +1,33 @@
 import { describe, expect, it } from 'vitest'
 
-import * as EventSequenceNumber from '../schema/EventSequenceNumber.ts'
-import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber/mod.ts'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
 import * as SyncState from './syncstate.ts'
 
-class TestEvent extends LiveStoreEvent.EncodedWithMeta {
-  public readonly payload: string
-  public readonly isClient: boolean
-  constructor(
-    seqNum: EventSequenceNumber.EventSequenceNumberInput,
-    parentSeqNum: EventSequenceNumber.EventSequenceNumberInput,
+class TestEvent extends LiveStoreEvent.Client.EncodedWithMeta {
+  public payload = 'uninitialized'
+  public isClient = false
+
+  static new = (
+    seqNum: EventSequenceNumber.Client.CompositeInput,
+    parentSeqNum: EventSequenceNumber.Client.CompositeInput,
     payload: string,
     isClient: boolean,
-  ) {
-    super({
-      seqNum: EventSequenceNumber.make(seqNum),
-      parentSeqNum: EventSequenceNumber.make(parentSeqNum),
+  ) => {
+    const event = new TestEvent({
+      seqNum: EventSequenceNumber.Client.Composite.make(seqNum),
+      parentSeqNum: EventSequenceNumber.Client.Composite.make(parentSeqNum),
       name: 'a',
       args: payload,
       clientId: 'static-local-id',
       sessionId: 'static-session-id',
     })
-    this.payload = payload
-    this.isClient = isClient
+    event.payload = payload
+    event.isClient = isClient
+    return event
   }
 
-  rebase_ = (parentSeqNum: EventSequenceNumber.EventSequenceNumber, rebaseGeneration: number) => {
+  rebase_ = (parentSeqNum: EventSequenceNumber.Client.Composite, rebaseGeneration: number) => {
     return this.rebase({ parentSeqNum, isClient: this.isClient, rebaseGeneration })
   }
 
@@ -34,17 +36,17 @@ class TestEvent extends LiveStoreEvent.EncodedWithMeta {
   // toString = () => this.toJSON()
 }
 
-const e0_1 = new TestEvent({ global: 0, client: 1 }, EventSequenceNumber.ROOT, 'a', true)
-const e1_0 = new TestEvent({ global: 1, client: 0 }, EventSequenceNumber.ROOT, 'a', false)
-const e1_1 = new TestEvent({ global: 1, client: 1 }, e1_0.seqNum, 'a', true)
-const e1_2 = new TestEvent({ global: 1, client: 2 }, e1_1.seqNum, 'a', true)
-const e1_3 = new TestEvent({ global: 1, client: 3 }, e1_2.seqNum, 'a', true)
-const e2_0 = new TestEvent({ global: 2, client: 0 }, e1_0.seqNum, 'a', false)
-const e2_1 = new TestEvent({ global: 2, client: 1 }, e2_0.seqNum, 'a', true)
+const e0_1 = TestEvent.new({ global: 0, client: 1 }, EventSequenceNumber.Client.ROOT, 'a', true)
+const e1_0 = TestEvent.new({ global: 1, client: 0 }, EventSequenceNumber.Client.ROOT, 'a', false)
+const e1_1 = TestEvent.new({ global: 1, client: 1 }, e1_0.seqNum, 'a', true)
+const e1_2 = TestEvent.new({ global: 1, client: 2 }, e1_1.seqNum, 'a', true)
+const e1_3 = TestEvent.new({ global: 1, client: 3 }, e1_2.seqNum, 'a', true)
+const e2_0 = TestEvent.new({ global: 2, client: 0 }, e1_0.seqNum, 'a', false)
+const e2_1 = TestEvent.new({ global: 2, client: 1 }, e2_0.seqNum, 'a', true)
 
-const isEqualEvent = LiveStoreEvent.isEqualEncoded
+const isEqualEvent = LiveStoreEvent.Client.isEqualEncoded
 
-const isClientEvent = (event: LiveStoreEvent.EncodedWithMeta) => (event as TestEvent).isClient
+const isClientEvent = (event: LiveStoreEvent.Client.EncodedWithMeta) => (event as TestEvent).isClient
 
 describe('syncstate', () => {
   describe('merge', () => {
@@ -62,7 +64,7 @@ describe('syncstate', () => {
       it('should rollback until start', () => {
         const syncState = new SyncState.SyncState({
           pending: [e2_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e2_0.seqNum,
         })
         const e1_0_e2_0 = e1_0.rebase_(e2_0.seqNum, 0)
@@ -86,7 +88,7 @@ describe('syncstate', () => {
       it('should rollback only to specified point', () => {
         const syncState = new SyncState.SyncState({
           pending: [e2_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e2_0.seqNum,
         })
         const e1_1_e2_0 = e1_1.rebase_(e1_0.seqNum, 0)
@@ -109,7 +111,7 @@ describe('syncstate', () => {
       it('should work for empty pending', () => {
         const syncState = new SyncState.SyncState({
           pending: [],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({
@@ -128,21 +130,21 @@ describe('syncstate', () => {
       it('should throw error if newEvents are not sorted in ascending order by event number (client)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_1, e1_0] } })
-        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+        expect(result).toMatchObject({ _tag: 'unknown-error' })
       })
 
       it('should throw error if newEvents are not sorted in ascending order by event number (global)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e2_0, e1_0] } })
-        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+        expect(result).toMatchObject({ _tag: 'unknown-error' })
       })
 
       it('should throw error if incoming event is < expected upstream head', () => {
@@ -152,7 +154,7 @@ describe('syncstate', () => {
           localHead: e2_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_0] } })
-        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+        expect(result).toMatchObject({ _tag: 'unknown-error' })
       })
 
       it('should throw error if incoming event is = expected upstream head', () => {
@@ -162,13 +164,13 @@ describe('syncstate', () => {
           localHead: e2_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e2_0] } })
-        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+        expect(result).toMatchObject({ _tag: 'unknown-error' })
       })
 
       it('should confirm pending event when receiving matching event', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_0] } })
@@ -184,7 +186,7 @@ describe('syncstate', () => {
       it('should confirm partial pending event when receiving matching event', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0, e2_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e2_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_0] } })
@@ -200,7 +202,7 @@ describe('syncstate', () => {
       it('should confirm pending event and add new event', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_0, e1_1] } })
@@ -235,7 +237,7 @@ describe('syncstate', () => {
       it('should confirm pending global event while keep pending client events', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0, e1_1],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_1.seqNum,
         })
         const result = merge({
@@ -254,7 +256,7 @@ describe('syncstate', () => {
       it('should ignore client events (incoming is subset of pending)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e0_1, e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({
@@ -273,7 +275,7 @@ describe('syncstate', () => {
       it('should ignore client events (incoming is subset of pending case 2)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e0_1, e1_0, e2_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({
@@ -292,7 +294,7 @@ describe('syncstate', () => {
       it('should ignore client events (incoming goes beyond pending)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e0_1, e1_0, e1_1],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_1.seqNum,
         })
         const result = merge({
@@ -316,7 +318,7 @@ describe('syncstate', () => {
           localHead: e2_0.seqNum,
         })
         const result = merge({ syncState, payload: { _tag: 'upstream-advance', newEvents: [e1_0] } })
-        expect(result).toMatchObject({ _tag: 'unexpected-error' })
+        expect(result).toMatchObject({ _tag: 'unknown-error' })
       })
     })
 
@@ -324,7 +326,7 @@ describe('syncstate', () => {
       it('should rebase single client event to end', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({ syncState, payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: [e1_1] }) })
@@ -340,10 +342,10 @@ describe('syncstate', () => {
       })
 
       it('should rebase different event with same id', () => {
-        const e2_0_b = new TestEvent({ global: 1, client: 0 }, e1_0.seqNum, '1_0_b', false)
+        const e2_0_b = TestEvent.new({ global: 1, client: 0 }, e1_0.seqNum, '1_0_b', false)
         const syncState = new SyncState.SyncState({
           pending: [e2_0_b],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e2_0_b.seqNum,
         })
         const result = merge({ syncState, payload: SyncState.PayloadUpstreamAdvance.make({ newEvents: [e2_0] }) })
@@ -360,7 +362,7 @@ describe('syncstate', () => {
       it('should rebase single client event to end (more incoming events)', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({
@@ -379,7 +381,7 @@ describe('syncstate', () => {
       it('should only rebase divergent events when first event matches', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0, e1_1],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_0.seqNum,
         })
         const result = merge({
@@ -400,7 +402,7 @@ describe('syncstate', () => {
       it('should rebase all client events when incoming chain starts differently', () => {
         const syncState = new SyncState.SyncState({
           pending: [e1_0, e1_1],
-          upstreamHead: EventSequenceNumber.ROOT,
+          upstreamHead: EventSequenceNumber.Client.ROOT,
           localHead: e1_1.seqNum,
         })
         const result = merge({
@@ -424,7 +426,7 @@ describe('syncstate', () => {
           it('should advance with new events', () => {
             const syncState = new SyncState.SyncState({
               pending: [e1_0],
-              upstreamHead: EventSequenceNumber.ROOT,
+              upstreamHead: EventSequenceNumber.Client.ROOT,
               localHead: e1_0.seqNum,
             })
             const result = merge({
@@ -434,18 +436,60 @@ describe('syncstate', () => {
 
             expectAdvance(result)
             expectEventArraysEqual(result.newSyncState.pending, [e1_0, e1_1, e1_2, e1_3])
-            expect(result.newSyncState.upstreamHead).toMatchObject(EventSequenceNumber.ROOT)
+            expect(result.newSyncState.upstreamHead).toMatchObject(EventSequenceNumber.Client.ROOT)
             expect(result.newSyncState.localHead).toMatchObject(e1_3.seqNum)
             expectEventArraysEqual(result.newEvents, [e1_1, e1_2, e1_3])
             expectEventArraysEqual(result.confirmedEvents, [])
           })
+
+          // Leaders can choose to ignore client-only events while still returning them for broadcast.
+          // Ensure pending/local head only reflects events that must be pushed upstream.
+          it('keeps pending empty when pushing only client-only events that are being ignored', () => {
+            const syncState = new SyncState.SyncState({
+              pending: [],
+              upstreamHead: EventSequenceNumber.Client.ROOT,
+              localHead: EventSequenceNumber.Client.ROOT,
+            })
+
+            const result = merge({
+              syncState,
+              payload: SyncState.PayloadLocalPush.make({ newEvents: [e0_1] }),
+              ignoreClientEvents: true,
+            })
+
+            expectAdvance(result)
+            expectEventArraysEqual(result.newSyncState.pending, [])
+            expect(result.newSyncState.upstreamHead).toMatchObject(EventSequenceNumber.Client.ROOT)
+            expect(result.newSyncState.localHead).toMatchObject(EventSequenceNumber.Client.ROOT)
+            expectEventArraysEqual(result.newEvents, [e0_1])
+          })
+
+          it('appends only upstream-bound events to pending when ignoring client-only pushes', () => {
+            const syncState = new SyncState.SyncState({
+              pending: [],
+              upstreamHead: EventSequenceNumber.Client.ROOT,
+              localHead: EventSequenceNumber.Client.ROOT,
+            })
+
+            const result = merge({
+              syncState,
+              payload: SyncState.PayloadLocalPush.make({ newEvents: [e0_1, e1_0] }),
+              ignoreClientEvents: true,
+            })
+
+            expectAdvance(result)
+            expectEventArraysEqual(result.newSyncState.pending, [e1_0])
+            expect(result.newSyncState.upstreamHead).toMatchObject(EventSequenceNumber.Client.ROOT)
+            expect(result.newSyncState.localHead).toMatchObject(e1_0.seqNum)
+            expectEventArraysEqual(result.newEvents, [e0_1, e1_0])
+          })
         })
 
         describe('reject', () => {
           it('should reject when new events are greater than pending events', () => {
             const syncState = new SyncState.SyncState({
               pending: [e1_0, e1_1],
-              upstreamHead: EventSequenceNumber.ROOT,
+              upstreamHead: EventSequenceNumber.Client.ROOT,
               localHead: e1_1.seqNum,
             })
             const result = merge({
@@ -463,8 +507,8 @@ describe('syncstate', () => {
 })
 
 const expectEventArraysEqual = (
-  actual: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
-  expected: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
+  actual: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
+  expected: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
 ) => {
   expect(actual.length).toBe(expected.length)
   actual.forEach((event, i) => {