@livestore/common 0.3.0-dev.3 → 0.3.0-dev.30

package/src/schema-management/migrations.ts

@@ -1,15 +1,15 @@
-import { SqliteAst, SqliteDsl } from '@livestore/db-schema'
 import { memoizeByStringifyArgs } from '@livestore/utils'
 import { Effect, Schema as EffectSchema } from '@livestore/utils/effect'
 
-import type { SynchronousDatabase } from '../adapter-types.js'
+import type { MigrationsReport, MigrationsReportEntry, SqliteDb, UnexpectedError } from '../adapter-types.js'
+import { SqliteAst, SqliteDsl } from '../schema/db-schema/mod.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
-import type { SchemaMetaRow, SchemaMutationsMetaRow } from '../schema/system-tables.js'
+import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/system-tables.js'
 import {
+  SCHEMA_EVENT_DEFS_META_TABLE,
   SCHEMA_META_TABLE,
-  SCHEMA_MUTATIONS_META_TABLE,
+  schemaEventDefsMetaTable,
   schemaMetaTable,
-  schemaMutationsMetaTable,
   systemTables,
 } from '../schema/system-tables.js'
 import { sql } from '../util.js'
@@ -19,24 +19,23 @@ import { validateSchema } from './validate-mutation-defs.js'
 
 const getMemoizedTimestamp = memoizeByStringifyArgs(() => new Date().toISOString())
 
-export const makeSchemaManager = (db: SynchronousDatabase): Effect.Effect<SchemaManager> =>
+export const makeSchemaManager = (db: SqliteDb): Effect.Effect<SchemaManager> =>
   Effect.gen(function* () {
     yield* migrateTable({
       db,
-      tableAst: schemaMutationsMetaTable.sqliteDef.ast,
+      tableAst: schemaEventDefsMetaTable.sqliteDef.ast,
       behaviour: 'create-if-not-exists',
     })
 
     return {
-      getMutationDefInfos: () =>
-        dbSelect<SchemaMutationsMetaRow>(db, sql`SELECT * FROM ${SCHEMA_MUTATIONS_META_TABLE}`),
+      getEventDefInfos: () => dbSelect<SchemaEventDefsMetaRow>(db, sql`SELECT * FROM ${SCHEMA_EVENT_DEFS_META_TABLE}`),
 
-      setMutationDefInfo: (info) => {
+      setEventDefInfo: (info) => {
         dbExecute(
           db,
-          sql`INSERT OR REPLACE INTO ${SCHEMA_MUTATIONS_META_TABLE} (mutationName, schemaHash, updatedAt) VALUES ($mutationName, $schemaHash, $updatedAt)`,
+          sql`INSERT OR REPLACE INTO ${SCHEMA_EVENT_DEFS_META_TABLE} (eventName, schemaHash, updatedAt) VALUES ($eventName, $schemaHash, $updatedAt)`,
           {
-            mutationName: info.mutationName,
+            eventName: info.eventName,
             schemaHash: info.schemaHash,
             updatedAt: new Date().toISOString(),
           },
@@ -51,10 +50,10 @@ export const migrateDb = ({
   schema,
   onProgress,
 }: {
-  db: SynchronousDatabase
+  db: SqliteDb
   schema: LiveStoreSchema
   onProgress?: (opts: { done: number; total: number }) => Effect.Effect<void>
-}) =>
+}): Effect.Effect<MigrationsReport, UnexpectedError> =>
   Effect.gen(function* () {
     yield* migrateTable({
       db,
@@ -81,6 +80,7 @@ export const migrateDb = ({
 
     const tablesToMigrate = new Set<{ tableAst: SqliteAst.Table; schemaHash: number }>()
 
+    const migrationsReportEntries: MigrationsReportEntry[] = []
     for (const tableDef of tableDefs) {
       const tableAst = tableDef.sqliteDef.ast
       const tableName = tableAst.name
@@ -90,9 +90,10 @@ export const migrateDb = ({
       if (schemaHash !== dbSchemaHash) {
         tablesToMigrate.add({ tableAst, schemaHash })
 
-        console.log(
-          `Schema hash mismatch for table '${tableName}' (DB: ${dbSchemaHash}, expected: ${schemaHash}), migrating table...`,
-        )
+        migrationsReportEntries.push({
+          tableName,
+          hashes: { expected: schemaHash, actual: dbSchemaHash },
+        })
       }
     }
 
@@ -107,6 +108,8 @@ export const migrateDb = ({
         yield* onProgress({ done: processedTables, total: tablesCount })
       }
     }
+
+    return { migrations: migrationsReportEntries }
   })
 
 export const migrateTable = ({
@@ -116,7 +119,7 @@ export const migrateTable = ({
   behaviour,
   skipMetaTable = false,
 }: {
-  db: SynchronousDatabase
+  db: SqliteDb
   tableAst: SqliteAst.Table
   schemaHash?: number
   behaviour: 'drop-and-recreate' | 'create-if-not-exists'
@@ -129,10 +132,10 @@ export const migrateTable = ({
 
     if (behaviour === 'drop-and-recreate') {
       // TODO need to possibly handle cascading deletes due to foreign keys
-      dbExecute(db, sql`drop table if exists ${tableName}`)
-      dbExecute(db, sql`create table if not exists ${tableName} (${columnSpec}) strict`)
+      dbExecute(db, sql`drop table if exists '${tableName}'`)
+      dbExecute(db, sql`create table if not exists '${tableName}' (${columnSpec}) strict`)
     } else if (behaviour === 'create-if-not-exists') {
-      dbExecute(db, sql`create table if not exists ${tableName} (${columnSpec}) strict`)
+      dbExecute(db, sql`create table if not exists '${tableName}' (${columnSpec}) strict`)
     }
 
     for (const index of tableAst.indexes) {
@@ -162,11 +165,11 @@ export const migrateTable = ({
 
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
   const uniqueStr = index.unique ? 'UNIQUE' : ''
-  return sql`create ${uniqueStr} index if not exists ${index.name} on ${tableName} (${index.columns.join(', ')})`
+  return sql`create ${uniqueStr} index if not exists '${index.name}' on '${tableName}' (${index.columns.join(', ')})`
 }
 
 export const makeColumnSpec = (tableAst: SqliteAst.Table) => {
-  const primaryKeys = tableAst.columns.filter((_) => _.primaryKey).map((_) => _.name)
+  const primaryKeys = tableAst.columns.filter((_) => _.primaryKey).map((_) => `'${_.name}'`)
   const columnDefStrs = tableAst.columns.map(toSqliteColumnSpec)
   if (primaryKeys.length > 0) {
     columnDefStrs.push(`PRIMARY KEY (${primaryKeys.join(', ')})`)
@@ -191,5 +194,5 @@ const toSqliteColumnSpec = (column: SqliteAst.Column) => {
     return `default ${encodedDefaultValue}`
   })()
 
-  return `${column.name} ${columnTypeStr} ${nullableStr} ${defaultValueStr}`
+  return `'${column.name}' ${columnTypeStr} ${nullableStr} ${defaultValueStr}`
 }

package/src/schema-management/validate-mutation-defs.ts

@@ -1,63 +1,61 @@
 import { Effect, Schema } from '@livestore/utils/effect'
 
 import { UnexpectedError } from '../adapter-types.js'
+import type { EventDef } from '../schema/EventDef.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
-import type { MutationDef } from '../schema/mutations.js'
-import type { MutationDefInfo, SchemaManager } from './common.js'
+import type { EventDefInfo, SchemaManager } from './common.js'
 
 export const validateSchema = (schema: LiveStoreSchema, schemaManager: SchemaManager) =>
   Effect.gen(function* () {
     // Validate mutation definitions
-    const registeredMutationDefInfos = schemaManager.getMutationDefInfos()
+    const registeredEventDefInfos = schemaManager.getEventDefInfos()
 
-    const missingMutationDefs = registeredMutationDefInfos.filter(
-      (registeredMutationDefInfo) => !schema.mutations.has(registeredMutationDefInfo.mutationName),
+    const missingEventDefs = registeredEventDefInfos.filter(
+      (registeredEventDefInfo) => !schema.eventsDefsMap.has(registeredEventDefInfo.eventName),
     )
 
-    if (missingMutationDefs.length > 0) {
+    if (missingEventDefs.length > 0) {
       yield* new UnexpectedError({
-        cause: `Missing mutation definitions: ${missingMutationDefs.map((info) => info.mutationName).join(', ')}`,
+        cause: `Missing mutation definitions: ${missingEventDefs.map((info) => info.eventName).join(', ')}`,
       })
     }
 
-    for (const [, mutationDef] of schema.mutations) {
-      const registeredMutationDefInfo = registeredMutationDefInfos.find(
-        (info) => info.mutationName === mutationDef.name,
-      )
+    for (const [, eventDef] of schema.eventsDefsMap) {
+      const registeredEventDefInfo = registeredEventDefInfos.find((info) => info.eventName === eventDef.name)
 
-      validateMutationDef(mutationDef, schemaManager, registeredMutationDefInfo)
+      validateEventDef(eventDef, schemaManager, registeredEventDefInfo)
     }
 
     // Validate table schemas
   })
 
-export const validateMutationDef = (
-  mutationDef: MutationDef.Any,
+export const validateEventDef = (
+  eventDef: EventDef.AnyWithoutFn,
   schemaManager: SchemaManager,
-  registeredMutationDefInfo: MutationDefInfo | undefined,
+  registeredEventDefInfo: EventDefInfo | undefined,
 ) => {
-  const schemaHash = Schema.hash(mutationDef.schema)
+  const schemaHash = Schema.hash(eventDef.schema)
 
-  if (registeredMutationDefInfo === undefined) {
-    schemaManager.setMutationDefInfo({
+  if (registeredEventDefInfo === undefined) {
+    schemaManager.setEventDefInfo({
       schemaHash,
-      mutationName: mutationDef.name,
+      eventName: eventDef.name,
     })
 
     return
   }
 
-  if (schemaHash === registeredMutationDefInfo.schemaHash) return
+  if (schemaHash === registeredEventDefInfo.schemaHash) return
 
   // TODO bring back some form of schema compatibility check (see https://github.com/livestorejs/livestore/issues/69)
-  // const newSchemaIsCompatibleWithOldSchema = Schema.isSubType(jsonSchemaDefFromMgmtStore, mutationDef.schema)
+  // const newSchemaIsCompatibleWithOldSchema = Schema.isSubType(jsonSchemaDefFromMgmtStore, eventDef.schema)
 
   // if (!newSchemaIsCompatibleWithOldSchema) {
-  //   shouldNeverHappen(`Schema for mutation ${mutationDef.name} has changed in an incompatible way`)
+  //   shouldNeverHappen(`Schema for mutation ${eventDef.name} has changed in an incompatible way`)
   // }
 
-  schemaManager.setMutationDefInfo({
+  schemaManager.setEventDefInfo({
     schemaHash,
-    mutationName: mutationDef.name,
+    eventName: eventDef.name,
   })
 }

package/src/sql-queries/sql-queries.ts

@@ -1,7 +1,7 @@
-import type { SqliteDsl } from '@livestore/db-schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import { pipe, ReadonlyArray, Schema, TreeFormatter } from '@livestore/utils/effect'
 
+import type { SqliteDsl } from '../schema/db-schema/mod.js'
 import { sql } from '../util.js'
 import { objectEntries } from './misc.js'
 import * as ClientTypes from './types.js'

package/src/sql-queries/sql-query-builder.ts

@@ -1,5 +1,4 @@
-import type { SqliteDsl } from '@livestore/db-schema'
-
+import type { SqliteDsl } from '../schema/db-schema/mod.js'
 import type { BindValues } from './sql-queries.js'
 import * as SqlQueries from './sql-queries.js'
 import type * as ClientTypes from './types.js'

package/src/sql-queries/types.ts

@@ -1,6 +1,8 @@
-import type { Prettify, SqliteDsl } from '@livestore/db-schema'
+import type { Prettify } from '@livestore/utils'
 import type { Schema } from '@livestore/utils/effect'
 
+import type { SqliteDsl } from '../schema/db-schema/mod.js'
+
 export type DecodedValuesForTableAll<TSchema extends SqliteDsl.DbSchema, TTableName extends keyof TSchema> = {
   [K in keyof GetColumns<TSchema, TTableName>]: Schema.Schema.Type<GetColumn<TSchema, TTableName, K>['schema']>
 }

package/src/sync/ClientSessionSyncProcessor.ts

@@ -0,0 +1,332 @@
+/// <reference lib="dom" />
+import { LS_DEV, shouldNeverHappen, TRACE_VERBOSE } from '@livestore/utils'
+import type { Runtime, Scope } from '@livestore/utils/effect'
+import { BucketQueue, Effect, FiberHandle, Queue, Schema, Stream, Subscribable } from '@livestore/utils/effect'
+import * as otel from '@opentelemetry/api'
+
+import type { ClientSession, UnexpectedError } from '../adapter-types.js'
+import * as EventId from '../schema/EventId.js'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
+import { getEventDef, LEADER_MERGE_COUNTER_TABLE, type LiveStoreSchema } from '../schema/mod.js'
+import { sql } from '../util.js'
+import * as SyncState from './syncstate.js'
+
+/**
+ * Rebase behaviour:
+ * - We continously pull events from the leader and apply them to the local store.
+ * - If there was a race condition (i.e. the leader and client session have both advacned),
+ *   we'll need to rebase the local pending events on top of the leader's head.
+ * - The goal is to never block the UI, so we'll interrupt rebasing if a new events is pushed by the client session.
+ * - We also want to avoid "backwards-jumping" in the UI, so we'll transactionally apply a read model changes during a rebase.
+ * - We might need to make the rebase behaviour configurable e.g. to let users manually trigger a rebase
+ *
+ * Longer term we should evalutate whether we can unify the ClientSessionSyncProcessor with the LeaderSyncProcessor.
+ */
+export const makeClientSessionSyncProcessor = ({
+  schema,
+  clientSession,
+  runtime,
+  applyEvent,
+  rollback,
+  refreshTables,
+  span,
+  params,
+  confirmUnsavedChanges,
+}: {
+  schema: LiveStoreSchema
+  clientSession: ClientSession
+  runtime: Runtime.Runtime<Scope.Scope>
+  applyEvent: (
+    eventDecoded: LiveStoreEvent.PartialAnyDecoded,
+    options: { otelContext: otel.Context; withChangeset: boolean },
+  ) => {
+    writeTables: Set<string>
+    sessionChangeset: { _tag: 'sessionChangeset'; data: Uint8Array; debug: any } | { _tag: 'no-op' } | { _tag: 'unset' }
+  }
+  rollback: (changeset: Uint8Array) => void
+  refreshTables: (tables: Set<string>) => void
+  span: otel.Span
+  params: {
+    leaderPushBatchSize: number
+  }
+  /**
+   * Currently only used in the web adapter:
+   * If true, registers a beforeunload event listener to confirm unsaved changes.
+   */
+  confirmUnsavedChanges: boolean
+}): ClientSessionSyncProcessor => {
+  const eventSchema = LiveStoreEvent.makeEventDefSchemaMemo(schema)
+
+  const syncStateRef = {
+    // The initial state is identical to the leader's initial state
+    current: new SyncState.SyncState({
+      localHead: clientSession.leaderThread.initialState.leaderHead,
+      upstreamHead: clientSession.leaderThread.initialState.leaderHead,
+      // Given we're starting with the leader's snapshot, we don't have any pending events intially
+      pending: [],
+    }),
+  }
+
+  const syncStateUpdateQueue = Queue.unbounded<SyncState.SyncState>().pipe(Effect.runSync)
+  const isClientEvent = (eventEncoded: LiveStoreEvent.EncodedWithMeta) =>
+    getEventDef(schema, eventEncoded.name).eventDef.options.clientOnly
+
+  /** We're queuing push requests to reduce the number of messages sent to the leader by batching them */
+  const leaderPushQueue = BucketQueue.make<LiveStoreEvent.EncodedWithMeta>().pipe(Effect.runSync)
+
+  const push: ClientSessionSyncProcessor['push'] = (batch, { otelContext }) => {
+    // TODO validate batch
+
+    let baseEventId = syncStateRef.current.localHead
+    const encodedEventDefs = batch.map(({ name, args }) => {
+      const eventDef = getEventDef(schema, name)
+      const nextIdPair = EventId.nextPair(baseEventId, eventDef.eventDef.options.clientOnly)
+      baseEventId = nextIdPair.id
+      return new LiveStoreEvent.EncodedWithMeta(
+        Schema.encodeUnknownSync(eventSchema)({
+          name,
+          args,
+          ...nextIdPair,
+          clientId: clientSession.clientId,
+          sessionId: clientSession.sessionId,
+        }),
+      )
+    })
+
+    const mergeResult = SyncState.merge({
+      syncState: syncStateRef.current,
+      payload: { _tag: 'local-push', newEvents: encodedEventDefs },
+      isClientEvent,
+      isEqualEvent: LiveStoreEvent.isEqualEncoded,
+    })
+
+    if (mergeResult._tag === 'unexpected-error') {
+      return shouldNeverHappen('Unexpected error in client-session-sync-processor', mergeResult.cause)
+    }
+
+    span.addEvent('local-push', {
+      batchSize: encodedEventDefs.length,
+      mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+    })
+
+    if (mergeResult._tag !== 'advance') {
+      return shouldNeverHappen(`Expected advance, got ${mergeResult._tag}`)
+    }
+
+    syncStateRef.current = mergeResult.newSyncState
+    syncStateUpdateQueue.offer(mergeResult.newSyncState).pipe(Effect.runSync)
+
+    const writeTables = new Set<string>()
+    for (const event of mergeResult.newEvents) {
+      // TODO avoid encoding and decoding here again
+      const decodedEventDef = Schema.decodeSync(eventSchema)(event)
+      const res = applyEvent(decodedEventDef, { otelContext, withChangeset: true })
+      for (const table of res.writeTables) {
+        writeTables.add(table)
+      }
+      event.meta.sessionChangeset = res.sessionChangeset
+    }
+
+    // console.debug('pushToLeader', encodedEventDefs.length, ...encodedEventDefs.map((_) => _.toJSON()))
+    BucketQueue.offerAll(leaderPushQueue, encodedEventDefs).pipe(Effect.runSync)
+
+    return { writeTables }
+  }
+
+  const debugInfo = {
+    rebaseCount: 0,
+    advanceCount: 0,
+    rejectCount: 0,
+  }
+
+  const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+  const boot: ClientSessionSyncProcessor['boot'] = Effect.gen(function* () {
+    // eslint-disable-next-line unicorn/prefer-global-this
+    if (confirmUnsavedChanges && typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+      const onBeforeUnload = (event: BeforeUnloadEvent) => {
+        if (syncStateRef.current.pending.length > 0) {
+          // Trigger the default browser dialog
+          event.preventDefault()
+        }
+      }
+
+      yield* Effect.acquireRelease(
+        Effect.sync(() => window.addEventListener('beforeunload', onBeforeUnload)),
+        () => Effect.sync(() => window.removeEventListener('beforeunload', onBeforeUnload)),
+      )
+    }
+
+    const leaderPushingFiberHandle = yield* FiberHandle.make()
+
+    const backgroundLeaderPushing = Effect.gen(function* () {
+      const batch = yield* BucketQueue.takeBetween(leaderPushQueue, 1, params.leaderPushBatchSize)
+      yield* clientSession.leaderThread.events.push(batch).pipe(
+        Effect.catchTag('LeaderAheadError', () => {
+          debugInfo.rejectCount++
+          return BucketQueue.clear(leaderPushQueue)
+        }),
+      )
+    }).pipe(Effect.forever, Effect.interruptible, Effect.tapCauseLogPretty)
+
+    yield* FiberHandle.run(leaderPushingFiberHandle, backgroundLeaderPushing)
+
+    const getMergeCounter = () =>
+      clientSession.sqliteDb.select<{ mergeCounter: number }>(
+        sql`SELECT mergeCounter FROM ${LEADER_MERGE_COUNTER_TABLE} WHERE id = 0`,
+      )[0]?.mergeCounter ?? 0
+
+    // NOTE We need to lazily call `.pull` as we want the cursor to be updated
+    yield* Stream.suspend(() =>
+      clientSession.leaderThread.events.pull({
+        cursor: { mergeCounter: getMergeCounter(), eventId: syncStateRef.current.localHead },
+      }),
+    ).pipe(
+      Stream.tap(({ payload, mergeCounter: leaderMergeCounter }) =>
+        Effect.gen(function* () {
+          // yield* Effect.logDebug('ClientSessionSyncProcessor:pull', payload)
+
+          if (clientSession.devtools.enabled) {
+            yield* clientSession.devtools.pullLatch.await
+          }
+
+          const mergeResult = SyncState.merge({
+            syncState: syncStateRef.current,
+            payload,
+            isClientEvent,
+            isEqualEvent: LiveStoreEvent.isEqualEncoded,
+          })
+
+          if (mergeResult._tag === 'unexpected-error') {
+            return yield* Effect.fail(mergeResult.cause)
+          } else if (mergeResult._tag === 'reject') {
+            return shouldNeverHappen('Unexpected reject in client-session-sync-processor', mergeResult)
+          }
+
+          syncStateRef.current = mergeResult.newSyncState
+          syncStateUpdateQueue.offer(mergeResult.newSyncState).pipe(Effect.runSync)
+
+          if (mergeResult._tag === 'rebase') {
+            span.addEvent('merge:pull:rebase', {
+              payloadTag: payload._tag,
+              payload: TRACE_VERBOSE ? JSON.stringify(payload) : undefined,
+              newEventsCount: mergeResult.newEvents.length,
+              rollbackCount: mergeResult.rollbackEvents.length,
+              res: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+              leaderMergeCounter,
+            })
+
+            debugInfo.rebaseCount++
+
+            yield* FiberHandle.clear(leaderPushingFiberHandle)
+
+            // Reset the leader push queue since we're rebasing and will push again
+            yield* BucketQueue.clear(leaderPushQueue)
+
+            yield* FiberHandle.run(leaderPushingFiberHandle, backgroundLeaderPushing)
+
+            if (LS_DEV) {
+              Effect.logDebug(
+                'merge:pull:rebase: rollback',
+                mergeResult.rollbackEvents.length,
+                ...mergeResult.rollbackEvents.slice(0, 10).map((_) => _.toJSON()),
+                { leaderMergeCounter },
+              ).pipe(Effect.provide(runtime), Effect.runSync)
+            }
+
+            for (let i = mergeResult.rollbackEvents.length - 1; i >= 0; i--) {
+              const event = mergeResult.rollbackEvents[i]!
+              if (event.meta.sessionChangeset._tag !== 'no-op' && event.meta.sessionChangeset._tag !== 'unset') {
+                rollback(event.meta.sessionChangeset.data)
+                event.meta.sessionChangeset = { _tag: 'unset' }
+              }
+            }
+
+            yield* BucketQueue.offerAll(leaderPushQueue, mergeResult.newSyncState.pending)
+          } else {
+            span.addEvent('merge:pull:advance', {
+              payloadTag: payload._tag,
+              payload: TRACE_VERBOSE ? JSON.stringify(payload) : undefined,
+              newEventsCount: mergeResult.newEvents.length,
+              res: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+              leaderMergeCounter,
+            })
+
+            debugInfo.advanceCount++
+          }
+
+          if (mergeResult.newEvents.length === 0) return
+
+          const writeTables = new Set<string>()
+          for (const event of mergeResult.newEvents) {
+            // TODO apply changeset if available (will require tracking of write tables as well)
+            const decodedEventDef = Schema.decodeSync(eventSchema)(event)
+            const res = applyEvent(decodedEventDef, { otelContext, withChangeset: true })
+            for (const table of res.writeTables) {
+              writeTables.add(table)
+            }
+
+            event.meta.sessionChangeset = res.sessionChangeset
+          }
+
+          refreshTables(writeTables)
+        }).pipe(
+          Effect.tapCauseLogPretty,
+          Effect.catchAllCause((cause) => Effect.sync(() => clientSession.shutdown(cause))),
+        ),
+      ),
+      Stream.runDrain,
+      Effect.forever, // NOTE Whenever the leader changes, we need to re-start the stream
+      Effect.interruptible,
+      Effect.withSpan('client-session-sync-processor:pull'),
+      Effect.tapCauseLogPretty,
+      Effect.forkScoped,
+    )
+  })
+
+  return {
+    push,
+    boot,
+    syncState: Subscribable.make({
+      get: Effect.gen(function* () {
+        const syncState = syncStateRef.current
+        if (syncStateRef === undefined) return shouldNeverHappen('Not initialized')
+        return syncState
+      }),
+      changes: Stream.fromQueue(syncStateUpdateQueue),
+    }),
+    debug: {
+      print: () =>
+        Effect.gen(function* () {
+          console.log('debugInfo', debugInfo)
+          console.log('syncState', syncStateRef.current)
+          const pushQueueSize = yield* BucketQueue.size(leaderPushQueue)
+          console.log('pushQueueSize', pushQueueSize)
+          const pushQueueItems = yield* BucketQueue.peekAll(leaderPushQueue)
+          console.log(
+            'pushQueueItems',
+            pushQueueItems.map((_) => _.toJSON()),
+          )
+        }).pipe(Effect.provide(runtime), Effect.runSync),
+      debugInfo: () => debugInfo,
+    },
+  } satisfies ClientSessionSyncProcessor
+}
+
+export interface ClientSessionSyncProcessor {
+  push: (
+    batch: ReadonlyArray<LiveStoreEvent.PartialAnyDecoded>,
+    options: { otelContext: otel.Context },
+  ) => {
+    writeTables: Set<string>
+  }
+  boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
+  syncState: Subscribable.Subscribable<SyncState.SyncState>
+  debug: {
+    print: () => void
+    debugInfo: () => {
+      rebaseCount: number
+      advanceCount: number
+    }
+  }
+}

package/src/sync/index.ts

@@ -1,3 +1,3 @@
 export * from './sync.js'
 export * from './validate-push-payload.js'
-export * from './client-session-sync-processor.js'
+export * from './ClientSessionSyncProcessor.js'