@livestore/common 0.3.0-dev.5 → 0.3.0-dev.50

package/src/schema-management/common.ts

@@ -1,4 +1,4 @@
-import type { SynchronousDatabase } from '../adapter-types.js'
+import type { SqliteDb } from '../adapter-types.js'
 import type { ParamsObject } from '../util.js'
 import { prepareBindValues } from '../util.js'
 
@@ -6,7 +6,7 @@ import { prepareBindValues } from '../util.js'
 // will require proper scope-aware cleanup etc (for testing and apps with multiple LiveStore instances)
 // const cachedStmts = new Map<string, PreparedStatement>()
 
-export const dbExecute = (db: SynchronousDatabase, queryStr: string, bindValues?: ParamsObject) => {
+export const dbExecute = (db: SqliteDb, queryStr: string, bindValues?: ParamsObject) => {
   // let stmt = cachedStmts.get(queryStr)
   // if (!stmt) {
   const stmt = db.prepare(queryStr)
@@ -20,7 +20,7 @@ export const dbExecute = (db: SynchronousDatabase, queryStr: string, bindValues?
   stmt.finalize()
 }
 
-export const dbSelect = <T>(db: SynchronousDatabase, queryStr: string, bindValues?: ParamsObject) => {
+export const dbSelect = <T>(db: SqliteDb, queryStr: string, bindValues?: ParamsObject) => {
   // let stmt = cachedStmts.get(queryStr)
   // if (!stmt) {
   const stmt = db.prepare(queryStr)
@@ -33,12 +33,12 @@ export const dbSelect = <T>(db: SynchronousDatabase, queryStr: string, bindValue
 }
 
 export interface SchemaManager {
-  getMutationDefInfos: () => ReadonlyArray<MutationDefInfo>
+  getEventDefInfos: () => ReadonlyArray<EventDefInfo>
 
-  setMutationDefInfo: (mutationDefInfo: MutationDefInfo) => void
+  setEventDefInfo: (eventDefInfo: EventDefInfo) => void
 }
 
-export type MutationDefInfo = {
-  mutationName: string
+export type EventDefInfo = {
+  eventName: string
   schemaHash: number
 }

package/src/schema-management/migrations.ts

@@ -1,42 +1,41 @@
-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 type { LiveStoreSchema } from '../schema/mod.js'
-import type { SchemaMetaRow, SchemaMutationsMetaRow } from '../schema/system-tables.js'
+import { SqliteAst, SqliteDsl } from '../schema/state/sqlite/db-schema/mod.js'
+import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables.js'
 import {
+  isStateSystemTable,
+  SCHEMA_EVENT_DEFS_META_TABLE,
   SCHEMA_META_TABLE,
-  SCHEMA_MUTATIONS_META_TABLE,
-  schemaMetaTable,
-  schemaMutationsMetaTable,
-  systemTables,
-} from '../schema/system-tables.js'
+  schemaEventDefsMetaTable,
+  stateSystemTables,
+} from '../schema/state/sqlite/system-tables.js'
 import { sql } from '../util.js'
 import type { SchemaManager } from './common.js'
 import { dbExecute, dbSelect } from './common.js'
-import { validateSchema } from './validate-mutation-defs.js'
+import { validateSchema } from './validate-schema.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,16 +50,18 @@ 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,
-      tableAst: schemaMetaTable.sqliteDef.ast,
-      behaviour: 'create-if-not-exists',
-    })
+    for (const tableDef of stateSystemTables) {
+      yield* migrateTable({
+        db,
+        tableAst: tableDef.sqliteDef.ast,
+        behaviour: 'create-if-not-exists',
+      })
+    }
 
     // TODO enforce that migrating tables isn't allowed once the store is running
 
@@ -73,14 +74,15 @@ export const migrateDb = ({
       schemaMetaRows.map(({ tableName, schemaHash }) => [tableName, schemaHash]),
     )
 
-    const tableDefs = new Set([
+    const tableDefs = [
       // NOTE it's important the `SCHEMA_META_TABLE` comes first since we're writing to it below
-      ...systemTables,
-      ...Array.from(schema.tables.values()).filter((_) => _.sqliteDef.name !== SCHEMA_META_TABLE),
-    ])
+      ...stateSystemTables,
+      ...Array.from(schema.state.sqlite.tables.values()).filter((_) => !isStateSystemTable(_.sqliteDef.name)),
+    ]
 
     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 +92,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 +110,8 @@ export const migrateDb = ({
         yield* onProgress({ done: processedTables, total: tablesCount })
       }
     }
+
+    return { migrations: migrationsReportEntries }
   })
 
 export const migrateTable = ({
@@ -116,7 +121,7 @@ export const migrateTable = ({
   behaviour,
   skipMetaTable = false,
 }: {
-  db: SynchronousDatabase
+  db: SqliteDb
   tableAst: SqliteAst.Table
   schemaHash?: number
   behaviour: 'drop-and-recreate' | 'create-if-not-exists'
@@ -182,6 +187,7 @@ const toSqliteColumnSpec = (column: SqliteAst.Column) => {
   const defaultValueStr = (() => {
     if (column.default._tag === 'None') return ''
 
+    if (column.default.value === null) return 'default null'
     if (SqliteDsl.isSqlDefaultValue(column.default.value)) return `default ${column.default.value.sql}`
 
     const encodeValue = EffectSchema.encodeSync(column.schema)

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

@@ -0,0 +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 { EventDefInfo, SchemaManager } from './common.js'
+
+export const validateSchema = (schema: LiveStoreSchema, schemaManager: SchemaManager) =>
+  Effect.gen(function* () {
+    // Validate mutation definitions
+    const registeredEventDefInfos = schemaManager.getEventDefInfos()
+
+    const missingEventDefs = registeredEventDefInfos.filter(
+      (registeredEventDefInfo) => !schema.eventsDefsMap.has(registeredEventDefInfo.eventName),
+    )
+
+    if (missingEventDefs.length > 0) {
+      yield* new UnexpectedError({
+        cause: `Missing mutation definitions: ${missingEventDefs.map((info) => info.eventName).join(', ')}`,
+      })
+    }
+
+    for (const [, eventDef] of schema.eventsDefsMap) {
+      const registeredEventDefInfo = registeredEventDefInfos.find((info) => info.eventName === eventDef.name)
+
+      validateEventDef(eventDef, schemaManager, registeredEventDefInfo)
+    }
+
+    // Validate table schemas
+  })
+
+export const validateEventDef = (
+  eventDef: EventDef.AnyWithoutFn,
+  schemaManager: SchemaManager,
+  registeredEventDefInfo: EventDefInfo | undefined,
+) => {
+  const schemaHash = Schema.hash(eventDef.schema)
+
+  if (registeredEventDefInfo === undefined) {
+    schemaManager.setEventDefInfo({
+      schemaHash,
+      eventName: eventDef.name,
+    })
+
+    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, eventDef.schema)
+
+  // if (!newSchemaIsCompatibleWithOldSchema) {
+  //   shouldNeverHappen(`Schema for mutation ${eventDef.name} has changed in an incompatible way`)
+  // }
+
+  schemaManager.setEventDefInfo({
+    schemaHash,
+    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/state/sqlite/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/state/sqlite/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/state/sqlite/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 EventSequenceNumber from '../schema/EventSequenceNumber.js'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
+import { getEventDef, type LiveStoreSchema, SystemTables } 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 state 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,
+  materializeEvent,
+  rollback,
+  refreshTables,
+  span,
+  params,
+  confirmUnsavedChanges,
+}: {
+  schema: LiveStoreSchema
+  clientSession: ClientSession
+  runtime: Runtime.Runtime<Scope.Scope>
+  materializeEvent: (
+    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 baseEventSequenceNumber = syncStateRef.current.localHead
+    const encodedEventDefs = batch.map(({ name, args }) => {
+      const eventDef = getEventDef(schema, name)
+      const nextNumPair = EventSequenceNumber.nextPair(baseEventSequenceNumber, eventDef.eventDef.options.clientOnly)
+      baseEventSequenceNumber = nextNumPair.seqNum
+      return new LiveStoreEvent.EncodedWithMeta(
+        Schema.encodeUnknownSync(eventSchema)({
+          name,
+          args,
+          ...nextNumPair,
+          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 = materializeEvent(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 ${SystemTables.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(), eventNum: 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 = materializeEvent(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) => 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'