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

package/src/leader-thread/make-leader-thread-layer.ts

@@ -1,13 +1,30 @@
-import { shouldNeverHappen } from '@livestore/utils'
-import type { HttpClient, Schema, Scope } from '@livestore/utils/effect'
-import { Deferred, Effect, Layer, Queue, SubscriptionRef } from '@livestore/utils/effect'
-
-import type { BootStatus, MakeSqliteDb, SqliteDb, SqliteError } from '../adapter-types.ts'
-import { UnexpectedError } from '../adapter-types.ts'
+import { omitUndefineds, shouldNeverHappen } from '@livestore/utils'
+import type { HttpClient, Scope } from '@livestore/utils/effect'
+import {
+  Deferred,
+  Effect,
+  KeyValueStore,
+  Layer,
+  PlatformError,
+  Queue,
+  Schema,
+  Stream,
+  Subscribable,
+  SubscriptionRef,
+} from '@livestore/utils/effect'
+import {
+  type BootStatus,
+  type MakeSqliteDb,
+  type MaterializerHashMismatchError,
+  type SqliteDb,
+  type SqliteError,
+  UnknownError,
+} from '../adapter-types.ts'
+import type { MigrationsReport } from '../defs.ts'
 import type * as Devtools from '../devtools/mod.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { EventSequenceNumber, LiveStoreEvent, SystemTables } from '../schema/mod.ts'
-import type { InvalidPullError, IsOfflineError, SyncOptions } from '../sync/sync.ts'
+import type { InvalidPullError, IsOfflineError, SyncBackend, SyncOptions } from '../sync/sync.ts'
 import { SyncState } from '../sync/syncstate.ts'
 import { sql } from '../util.ts'
 import * as Eventlog from './eventlog.ts'
@@ -17,6 +34,7 @@ import { makeMaterializeEvent } from './materialize-event.ts'
 import { recreateDb } from './recreate-db.ts'
 import type { ShutdownChannel } from './shutdown-channel.ts'
 import type {
+  DevtoolsContext,
   DevtoolsOptions,
   InitialBlockingSyncContext,
   InitialSyncOptions,
@@ -27,7 +45,8 @@ import { LeaderThreadCtx } from './types.ts'
 
 export interface MakeLeaderThreadLayerParams {
   storeId: string
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadSchema: Schema.Schema<any> | undefined
+  syncPayloadEncoded: Schema.JsonValue | undefined
   clientId: string
   schema: LiveStoreSchema
   makeSqliteDb: MakeSqliteDb
@@ -53,7 +72,8 @@ export const makeLeaderThreadLayer = ({
   schema,
   storeId,
   clientId,
-  syncPayload,
+  syncPayloadSchema = Schema.JsonValue,
+  syncPayloadEncoded,
   makeSqliteDb,
   syncOptions,
   dbState,
@@ -62,8 +82,11 @@ export const makeLeaderThreadLayer = ({
   shutdownChannel,
   params,
   testing,
-}: MakeLeaderThreadLayerParams): Layer.Layer<LeaderThreadCtx, UnexpectedError, Scope.Scope | HttpClient.HttpClient> =>
+}: MakeLeaderThreadLayerParams): Layer.Layer<LeaderThreadCtx, UnknownError, Scope.Scope | HttpClient.HttpClient> =>
   Effect.gen(function* () {
+    const syncPayloadDecoded =
+      syncPayloadEncoded === undefined ? undefined : yield* Schema.decodeUnknown(syncPayloadSchema)(syncPayloadEncoded)
+
     const bootStatusQueue = yield* Queue.unbounded<BootStatus>().pipe(Effect.acquireRelease(Queue.shutdown))
 
     const dbEventlogMissing = !hasEventlogTables(dbEventlog)
@@ -71,10 +94,45 @@ export const makeLeaderThreadLayer = ({
     // Either happens on initial boot or if schema changes
     const dbStateMissing = !hasStateTables(dbState)
 
+    yield* Eventlog.initEventlogDb(dbEventlog)
+
     const syncBackend =
       syncOptions?.backend === undefined
         ? undefined
-        : yield* syncOptions.backend({ storeId, clientId, payload: syncPayload })
+        : yield* syncOptions.backend({ storeId, clientId, payload: syncPayloadDecoded }).pipe(
+            Effect.provide(
+              Layer.succeed(
+                KeyValueStore.KeyValueStore,
+                KeyValueStore.makeStringOnly({
+                  get: (_key) =>
+                    Effect.sync(() => Eventlog.getBackendIdFromDb(dbEventlog)).pipe(
+                      Effect.catchAllDefect((cause) =>
+                        PlatformError.BadArgument.make({
+                          method: 'getBackendIdFromDb',
+                          description: 'Failed to get backendId',
+                          module: 'KeyValueStore',
+                          cause,
+                        }),
+                      ),
+                    ),
+                  set: (_key, value) =>
+                    Effect.sync(() => Eventlog.updateBackendId(dbEventlog, value)).pipe(
+                      Effect.catchAllDefect((cause) =>
+                        PlatformError.BadArgument.make({
+                          method: 'updateBackendId',
+                          module: 'KeyValueStore',
+                          description: 'Failed to update backendId',
+                          cause,
+                        }),
+                      ),
+                    ),
+                  clear: Effect.dieMessage(`Not implemented. Should never be used.`),
+                  remove: () => Effect.dieMessage(`Not implemented. Should never be used.`),
+                  size: Effect.dieMessage(`Not implemented. Should never be used.`),
+                }),
+              ),
+            ),
+          )
 
     if (syncBackend !== undefined) {
       // We're already connecting to the sync backend concurrently
@@ -86,18 +144,29 @@ export const makeLeaderThreadLayer = ({
       bootStatusQueue,
     })
 
+    const materializeEvent = yield* makeMaterializeEvent({ schema, dbState, dbEventlog })
+
+    // Recreate state database if needed BEFORE creating sync processor
+    // This ensures all system tables exist before any queries are made
+    const { migrationsReport } = dbStateMissing
+      ? yield* recreateDb({ dbState, dbEventlog, schema, bootStatusQueue, materializeEvent })
+      : { migrationsReport: { migrations: [] } }
+
     const syncProcessor = yield* makeLeaderSyncProcessor({
       schema,
       dbState,
       initialSyncState: getInitialSyncState({ dbEventlog, dbState, dbEventlogMissing }),
       initialBlockingSyncContext,
       onError: syncOptions?.onSyncError ?? 'ignore',
+      livePull: syncOptions?.livePull ?? true,
       params: {
-        localPushBatchSize: params?.localPushBatchSize,
-        backendPushBatchSize: params?.backendPushBatchSize,
+        ...omitUndefineds({
+          localPushBatchSize: params?.localPushBatchSize,
+          backendPushBatchSize: params?.backendPushBatchSize,
+        }),
       },
       testing: {
-        delays: testing?.syncProcessor?.delays,
+        ...omitUndefineds({ delays: testing?.syncProcessor?.delays }),
       },
     })
 
@@ -113,7 +182,7 @@ export const makeLeaderThreadLayer = ({
         }
       : { enabled: false as const }
 
-    const materializeEvent = yield* makeMaterializeEvent({ schema, dbState, dbEventlog })
+    const networkStatus = yield* makeNetworkStatusSubscribable({ syncBackend, devtoolsContext })
 
     const ctx = {
       schema,
@@ -123,7 +192,7 @@ export const makeLeaderThreadLayer = ({
       dbState,
       dbEventlog,
       makeSqliteDb,
-      eventSchema: LiveStoreEvent.makeEventDefSchema(schema),
+      eventSchema: LiveStoreEvent.Client.makeSchema(schema),
       shutdownStateSubRef: yield* SubscriptionRef.make<ShutdownState>('running'),
       shutdownChannel,
       syncBackend,
@@ -131,6 +200,7 @@ export const makeLeaderThreadLayer = ({
       materializeEvent,
       extraIncomingMessagesQueue,
       devtools: devtoolsContext,
+      networkStatus,
       // State will be set during `bootLeaderThread`
       initialState: {} as any as LeaderThreadCtx['Type']['initialState'],
     } satisfies typeof LeaderThreadCtx.Service
@@ -141,7 +211,7 @@ export const makeLeaderThreadLayer = ({
     const layer = Layer.succeed(LeaderThreadCtx, ctx)
 
     ctx.initialState = yield* bootLeaderThread({
-      dbStateMissing,
+      migrationsReport,
       initialBlockingSyncContext,
       devtoolsOptions,
     }).pipe(Effect.provide(layer))
@@ -150,7 +220,7 @@ export const makeLeaderThreadLayer = ({
   }).pipe(
     Effect.withSpan('@livestore/common:leader-thread:boot'),
     Effect.withSpanScoped('@livestore/common:leader-thread'),
-    UnexpectedError.mapToUnexpectedError,
+    UnknownError.mapToUnknownError,
     Effect.tapCauseLogPretty,
     Layer.unwrapScoped,
   )
@@ -187,10 +257,12 @@ const getInitialSyncState = ({
   dbEventlogMissing: boolean
 }) => {
   const initialBackendHead = dbEventlogMissing
-    ? EventSequenceNumber.ROOT.global
+    ? EventSequenceNumber.Client.ROOT.global
     : Eventlog.getBackendHeadFromDb(dbEventlog)
 
-  const initialLocalHead = dbEventlogMissing ? EventSequenceNumber.ROOT : Eventlog.getClientHeadFromDb(dbEventlog)
+  const initialLocalHead = dbEventlogMissing
+    ? EventSequenceNumber.Client.ROOT
+    : Eventlog.getClientHeadFromDb(dbEventlog)
 
   if (initialBackendHead > initialLocalHead.global) {
     return shouldNeverHappen(
@@ -202,8 +274,8 @@ const getInitialSyncState = ({
     localHead: initialLocalHead,
     upstreamHead: {
       global: initialBackendHead,
-      client: EventSequenceNumber.clientDefault,
-      rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
+      client: EventSequenceNumber.Client.DEFAULT,
+      rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
     },
     pending: dbEventlogMissing
       ? []
@@ -212,7 +284,7 @@ const getInitialSyncState = ({
           dbState,
           since: {
             global: initialBackendHead,
-            client: EventSequenceNumber.clientDefault,
+            client: EventSequenceNumber.Client.DEFAULT,
             rebaseGeneration: initialLocalHead.rebaseGeneration,
           },
         }),
@@ -244,12 +316,12 @@ const makeInitialBlockingSyncContext = ({
 
     return {
       blockingDeferred,
-      update: ({ processed, remaining }) =>
+      update: ({ processed, pageInfo }) =>
         Effect.gen(function* () {
           if (ctx.isDone === true) return
 
-          if (ctx.total === -1) {
-            ctx.total = remaining + processed
+          if (ctx.total === -1 && pageInfo._tag === 'MoreKnown') {
+            ctx.total = pageInfo.remaining + processed
           }
 
           ctx.processedEvents += processed
@@ -258,7 +330,7 @@ const makeInitialBlockingSyncContext = ({
             progress: { done: ctx.processedEvents, total: ctx.total },
           })
 
-          if (remaining === 0 && blockingDeferred !== undefined) {
+          if (pageInfo._tag === 'NoMore' && blockingDeferred !== undefined) {
             yield* Deferred.succeed(blockingDeferred, void 0)
             ctx.isDone = true
           }
@@ -271,26 +343,20 @@ const makeInitialBlockingSyncContext = ({
  * It also starts various background processes (e.g. syncing)
  */
 const bootLeaderThread = ({
-  dbStateMissing,
+  migrationsReport,
   initialBlockingSyncContext,
   devtoolsOptions,
 }: {
-  dbStateMissing: boolean
+  migrationsReport: MigrationsReport
   initialBlockingSyncContext: InitialBlockingSyncContext
   devtoolsOptions: DevtoolsOptions
 }): Effect.Effect<
   LeaderThreadCtx['Type']['initialState'],
-  UnexpectedError | SqliteError | IsOfflineError | InvalidPullError,
+  UnknownError | SqliteError | IsOfflineError | InvalidPullError | MaterializerHashMismatchError,
   LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
 > =>
   Effect.gen(function* () {
-    const { dbEventlog, bootStatusQueue, syncProcessor, schema, materializeEvent, dbState } = yield* LeaderThreadCtx
-
-    yield* Eventlog.initEventlogDb(dbEventlog)
-
-    const { migrationsReport } = dbStateMissing
-      ? yield* recreateDb({ dbState, dbEventlog, schema, bootStatusQueue, materializeEvent })
-      : { migrationsReport: { migrations: [] } }
+    const { bootStatusQueue, syncProcessor } = yield* LeaderThreadCtx
 
     // NOTE the sync processor depends on the dbs being initialized properly
     const { initialLeaderHead } = yield* syncProcessor.boot
@@ -313,3 +379,56 @@ const bootLeaderThread = ({
 
     return { migrationsReport, leaderHead: initialLeaderHead }
   })
+
+/** @internal */
+export const makeNetworkStatusSubscribable = ({
+  syncBackend,
+  devtoolsContext,
+}: {
+  syncBackend: SyncBackend.SyncBackend | undefined
+  devtoolsContext: DevtoolsContext
+}): Effect.Effect<Subscribable.Subscribable<SyncBackend.NetworkStatus>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const initialIsConnected = syncBackend !== undefined ? yield* SubscriptionRef.get(syncBackend.isConnected) : false
+    const initialLatchClosed =
+      devtoolsContext.enabled === true
+        ? (yield* SubscriptionRef.get(devtoolsContext.syncBackendLatchState)).latchClosed
+        : false
+
+    const networkStatusRef = yield* SubscriptionRef.make<SyncBackend.NetworkStatus>({
+      isConnected: initialIsConnected,
+      timestampMs: Date.now(),
+      devtools: { latchClosed: initialLatchClosed },
+    })
+
+    const updateNetworkStatus = (patch: { isConnected?: boolean; latchClosed?: boolean }) =>
+      SubscriptionRef.update(networkStatusRef, (previous) => ({
+        isConnected: patch.isConnected ?? previous.isConnected,
+        timestampMs: Date.now(),
+        devtools: {
+          latchClosed: patch.latchClosed ?? previous.devtools.latchClosed,
+        },
+      }))
+
+    if (syncBackend !== undefined) {
+      yield* syncBackend.isConnected.changes.pipe(
+        Stream.tap((isConnected) => updateNetworkStatus({ isConnected })),
+        Stream.runDrain,
+        Effect.interruptible,
+        Effect.tapCauseLogPretty,
+        Effect.forkScoped,
+      )
+    }
+
+    if (devtoolsContext.enabled === true) {
+      yield* devtoolsContext.syncBackendLatchState.changes.pipe(
+        Stream.tap(({ latchClosed }) => updateNetworkStatus({ latchClosed })),
+        Stream.runDrain,
+        Effect.interruptible,
+        Effect.tapCauseLogPretty,
+        Effect.forkScoped,
+      )
+    }
+
+    return Subscribable.fromSubscriptionRef(networkStatusRef)
+  })

package/src/leader-thread/materialize-event.ts

@@ -1,16 +1,17 @@
 import { isDevEnv, LS_DEV, shouldNeverHappen } from '@livestore/utils'
 import { Effect, Option, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
-import { type SqliteDb, UnexpectedError } from '../adapter-types.ts'
+import { MaterializeError, MaterializerHashMismatchError, type SqliteDb } from '../adapter-types.ts'
 import { getExecStatementsFromMaterializer, hashMaterializerResults } from '../materializer-helper.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
-import { EventSequenceNumber, getEventDef, SystemTables } from '../schema/mod.ts'
+import { EventSequenceNumber, resolveEventDef, SystemTables, UNKNOWN_EVENT_SCHEMA_HASH } from '../schema/mod.ts'
 import { insertRow } from '../sql-queries/index.ts'
 import { sql } from '../util.ts'
 import { execSql, execSqlPrepared } from './connection.ts'
 import * as Eventlog from './eventlog.ts'
 import type { MaterializeEvent } from './types.ts'
 
+// TODO refactor `makeMaterializeEvent` to not return an Effect for the constructor as it's not needed
 export const makeMaterializeEvent = ({
   schema,
   dbState,
@@ -19,7 +20,7 @@ export const makeMaterializeEvent = ({
   schema: LiveStoreSchema
   dbState: SqliteDb
   dbEventlog: SqliteDb
-}): Effect.Effect<MaterializeEvent, UnexpectedError> =>
+}): Effect.Effect<MaterializeEvent> =>
   Effect.gen(function* () {
     const eventDefSchemaHashMap = new Map(
       // TODO Running `Schema.hash` can be a bottleneck for larger schemas. There is an opportunity to run this
@@ -32,8 +33,34 @@ export const makeMaterializeEvent = ({
       Effect.gen(function* () {
         const skipEventlog = options?.skipEventlog ?? false
 
-        const eventName = eventEncoded.name
-        const { eventDef, materializer } = getEventDef(schema, eventName)
+        const resolution = yield* resolveEventDef(schema, {
+          operation: '@livestore/common:leader-thread:materializeEvent',
+          event: eventEncoded,
+        })
+
+        if (resolution._tag === 'unknown') {
+          // Unknown events still enter the eventlog so newer clients can replay
+          // them once they learn the schema. We skip materialization to keep the
+          // local state consistent with the knowledge of the current client.
+          if (skipEventlog === false) {
+            yield* Eventlog.insertIntoEventlog(
+              eventEncoded,
+              dbEventlog,
+              UNKNOWN_EVENT_SCHEMA_HASH,
+              eventEncoded.clientId,
+              eventEncoded.sessionId,
+            )
+          }
+
+          dbState.debug.head = eventEncoded.seqNum
+
+          return {
+            sessionChangeset: { _tag: 'no-op' as const },
+            hash: Option.none(),
+          }
+        }
+
+        const { eventDef, materializer } = resolution
 
         const execArgsArr = getExecStatementsFromMaterializer({
           eventDef,
@@ -49,10 +76,7 @@ export const makeMaterializeEvent = ({
           eventEncoded.meta.materializerHashSession._tag === 'Some' &&
           eventEncoded.meta.materializerHashSession.value !== materializerHash.value
         ) {
-          yield* UnexpectedError.make({
-            cause: `Materializer hash mismatch detected for event "${eventEncoded.name}".`,
-            note: `Please make sure your event materializer is a pure function without side effects.`,
-          })
+          return yield* MaterializerHashMismatchError.make({ eventName: eventEncoded.name })
         }
 
         // NOTE we might want to bring this back if we want to debug no-op events
@@ -126,11 +150,12 @@ export const makeMaterializeEvent = ({
           hash: materializerHash,
         }
       }).pipe(
+        Effect.mapError((cause) => MaterializeError.make({ cause })),
         Effect.withSpan(`@livestore/common:leader-thread:materializeEvent`, {
           attributes: {
             eventName: eventEncoded.name,
             eventNum: eventEncoded.seqNum,
-            'span.label': `${EventSequenceNumber.toString(eventEncoded.seqNum)} ${eventEncoded.name}`,
+            'span.label': `${EventSequenceNumber.Client.toString(eventEncoded.seqNum)} ${eventEncoded.name}`,
           },
         }),
         // Effect.logDuration('@livestore/common:leader-thread:materializeEvent'),
@@ -144,7 +169,7 @@ export const rollback = ({
 }: {
   dbState: SqliteDb
   dbEventlog: SqliteDb
-  eventNumsToRollback: EventSequenceNumber.EventSequenceNumber[]
+  eventNumsToRollback: EventSequenceNumber.Client.Composite[]
 }) =>
   Effect.gen(function* () {
     const rollbackEvents = dbState
@@ -160,7 +185,7 @@ export const rollback = ({
         changeset: _.changeset,
         debug: _.debug,
       }))
-      .toSorted((a, b) => EventSequenceNumber.compare(a.seqNum, b.seqNum))
+      .toSorted((a, b) => EventSequenceNumber.Client.compare(a.seqNum, b.seqNum))
 
     // Apply changesets in reverse order
     for (let i = rollbackEvents.length - 1; i >= 0; i--) {

package/src/leader-thread/recreate-db.ts

@@ -2,8 +2,16 @@ import { casesHandled } from '@livestore/utils'
 import { Effect, Queue } from '@livestore/utils/effect'
 
 import type { MigrationsReport } from '../defs.ts'
-import type { BootStatus, MigrationHooks, SqliteDb, SqliteError } from '../index.ts'
-import { migrateDb, rematerializeFromEventlog, UnexpectedError } from '../index.ts'
+import {
+  type BootStatus,
+  type MaterializeError,
+  type MigrationHooks,
+  migrateDb,
+  rematerializeFromEventlog,
+  type SqliteDb,
+  type SqliteError,
+  UnknownError,
+} from '../index.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { configureConnection } from './connection.ts'
 import type { MaterializeEvent } from './types.ts'
@@ -20,7 +28,7 @@ export const recreateDb = ({
   schema: LiveStoreSchema
   bootStatusQueue: Queue.Queue<BootStatus>
   materializeEvent: MaterializeEvent
-}): Effect.Effect<{ migrationsReport: MigrationsReport }, UnexpectedError | SqliteError> =>
+}): Effect.Effect<{ migrationsReport: MigrationsReport }, UnknownError | MaterializeError | SqliteError> =>
   Effect.gen(function* () {
     const migrationOptions = schema.state.sqlite.migrations
     let migrationsReport: MigrationsReport
@@ -40,7 +48,7 @@ export const recreateDb = ({
 
     const initDb = (hooks: Partial<MigrationHooks> | undefined) =>
       Effect.gen(function* () {
-        yield* Effect.tryAll(() => hooks?.init?.(tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.init?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         const migrationsReport = yield* migrateDb({
           db: tmpDb,
@@ -49,7 +57,7 @@ export const recreateDb = ({
             Queue.offer(bootStatusQueue, { stage: 'migrating', progress: { done, total } }),
         })
 
-        yield* Effect.tryAll(() => hooks?.pre?.(tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.pre?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         return { migrationsReport, tmpDb }
       })
@@ -70,7 +78,7 @@ export const recreateDb = ({
             Queue.offer(bootStatusQueue, { stage: 'rehydrating', progress: { done, total } }),
         })
 
-        yield* Effect.tryAll(() => hooks?.post?.(initResult.tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.post?.(initResult.tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         break
       }
@@ -80,7 +88,7 @@ export const recreateDb = ({
         migrationsReport = { migrations: [] }
 
         const newDbData = yield* Effect.tryAll(() => migrationOptions.migrate(oldDbData)).pipe(
-          UnexpectedError.mapToUnexpectedError,
+          UnknownError.mapToUnknownError,
         )
 
         tmpDb.import(newDbData)

package/src/leader-thread/shutdown-channel.ts

@@ -1,9 +1,23 @@
 import type { WebChannel } from '@livestore/utils/effect'
 import { Schema } from '@livestore/utils/effect'
 
-import { IntentionalShutdownCause, SyncError, UnexpectedError } from '../index.ts'
+import {
+  IntentionalShutdownCause,
+  InvalidPullError,
+  InvalidPushError,
+  IsOfflineError,
+  MaterializeError,
+  UnknownError,
+} from '../index.ts'
 
-export class All extends Schema.Union(IntentionalShutdownCause, UnexpectedError, SyncError) {}
+export class All extends Schema.Union(
+  IntentionalShutdownCause,
+  UnknownError,
+  IsOfflineError,
+  InvalidPushError,
+  InvalidPullError,
+  MaterializeError,
+) {}
 
 /**
  * Used internally by an adapter to shutdown gracefully.

package/src/leader-thread/types.ts

@@ -13,7 +13,7 @@ import { Context, Schema } from '@livestore/utils/effect'
 import type { MeshNode } from '@livestore/webmesh'
 
 import type { MigrationsReport } from '../defs.ts'
-import type { SqliteError } from '../errors.ts'
+import type { MaterializeError } from '../errors.ts'
 import type {
   BootStatus,
   Devtools,
@@ -22,7 +22,7 @@ import type {
   PersistenceInfo,
   SqliteDb,
   SyncBackend,
-  UnexpectedError,
+  UnknownError,
 } from '../index.ts'
 import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '../schema/mod.ts'
 import type * as SyncState from '../sync/syncstate.ts'
@@ -43,7 +43,7 @@ export const InitialSyncOptions = Schema.Union(InitialSyncOptionsSkip, InitialSy
 export type InitialSyncOptions = typeof InitialSyncOptions.Type
 
 export type InitialSyncInfo = Option.Option<{
-  cursor: EventSequenceNumber.EventSequenceNumber
+  eventSequenceNumber: EventSequenceNumber.Global.Type
   metadata: Option.Option<Schema.JsonValue>
 }>
 
@@ -66,7 +66,7 @@ export type DevtoolsOptions =
           persistenceInfo: PersistenceInfoPair
           mode: 'proxy' | 'direct'
         },
-        UnexpectedError,
+        UnknownError,
         Scope.Scope | HttpClient.HttpClient | LeaderThreadCtx
       >
     }
@@ -96,13 +96,13 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
     // TODO we should find a more elegant way to handle cases which need this ref for their implementation
     shutdownStateSubRef: SubscriptionRef.SubscriptionRef<ShutdownState>
     shutdownChannel: ShutdownChannel
-    eventSchema: LiveStoreEvent.ForEventDefRecord<any>
+    eventSchema: LiveStoreEvent.ForEventDef.ForRecord<any>
     devtools: DevtoolsContext
-    syncBackend: SyncBackend | undefined
+    syncBackend: SyncBackend.SyncBackend | undefined
     syncProcessor: LeaderSyncProcessor
     materializeEvent: MaterializeEvent
     initialState: {
-      leaderHead: EventSequenceNumber.EventSequenceNumber
+      leaderHead: EventSequenceNumber.Client.Composite
       migrationsReport: MigrationsReport
     }
     /**
@@ -111,11 +111,12 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
      * This is currently separated from `.devtools` as it also needs to work when devtools are disabled
      */
     extraIncomingMessagesQueue: Queue.Queue<Devtools.Leader.MessageToApp>
+    networkStatus: Subscribable.Subscribable<SyncBackend.NetworkStatus>
   }
 >() {}
 
 export type MaterializeEvent = (
-  eventEncoded: LiveStoreEvent.EncodedWithMeta,
+  eventEncoded: LiveStoreEvent.Client.EncodedWithMeta,
   options?: {
     /** Needed for rematerializeFromEventlog */
     skipEventlog?: boolean
@@ -125,31 +126,32 @@ export type MaterializeEvent = (
     sessionChangeset: { _tag: 'sessionChangeset'; data: Uint8Array<ArrayBuffer>; debug: any } | { _tag: 'no-op' }
     hash: Option.Option<number>
   },
-  SqliteError | UnexpectedError
+  MaterializeError
 >
 
 export type InitialBlockingSyncContext = {
   blockingDeferred: Deferred.Deferred<void> | undefined
-  update: (_: { remaining: number; processed: number }) => Effect.Effect<void>
+  update: (_: { pageInfo: SyncBackend.PullResPageInfo; processed: number }) => Effect.Effect<void>
 }
 
 export interface LeaderSyncProcessor {
   /** Used by client sessions to subscribe to upstream sync state changes */
   pull: (args: {
-    cursor: EventSequenceNumber.EventSequenceNumber
-  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }, UnexpectedError>
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }, UnknownError>
   /** The `pullQueue` API can be used instead of `pull` when more convenient */
   pullQueue: (args: {
-    cursor: EventSequenceNumber.EventSequenceNumber
-  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, UnexpectedError, Scope.Scope>
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, UnknownError, Scope.Scope>
 
   /** Used by client sessions to push events to the leader thread */
   push: (
     /** `batch` needs to follow the same rules as `batch` in `SyncBackend.push` */
-    batch: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
+    batch: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
     options?: {
       /**
        * If true, the effect will only finish when the local push has been processed (i.e. succeeded or was rejected).
+       * `true` doesn't mean the events have been pushed to the sync backend.
        * @default false
        */
       waitForProcessing?: boolean
@@ -158,14 +160,14 @@ export interface LeaderSyncProcessor {
 
   /** Currently only used by devtools which don't provide their own event numbers */
   pushPartial: (args: {
-    event: LiveStoreEvent.PartialAnyEncoded
+    event: LiveStoreEvent.Input.Encoded
     clientId: string
     sessionId: string
-  }) => Effect.Effect<void, UnexpectedError>
+  }) => Effect.Effect<void, UnknownError>
 
   boot: Effect.Effect<
-    { initialLeaderHead: EventSequenceNumber.EventSequenceNumber },
-    UnexpectedError,
+    { initialLeaderHead: EventSequenceNumber.Client.Composite },
+    UnknownError,
     LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
   >
   syncState: Subscribable.Subscribable<SyncState.SyncState>