@livestore/common 0.2.0 → 0.3.0-dev.1

package/src/schema/MutationEvent.ts

@@ -0,0 +1,161 @@
+import { memoizeByRef } from '@livestore/utils'
+import type { Deferred } from '@livestore/utils/effect'
+import { Schema } from '@livestore/utils/effect'
+
+import * as EventId from './EventId.js'
+import type { MutationDef, MutationDefRecord } from './mutations.js'
+import type { LiveStoreSchema } from './schema.js'
+
+export type MutationEventPartial<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Type<TMutationsDef['schema']>
+}
+
+export type MutationEventPartialEncoded<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Encoded<TMutationsDef['schema']>
+}
+
+export type MutationEvent<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Type<TMutationsDef['schema']>
+  id: EventId.EventId
+  parentId: EventId.EventId
+}
+
+export type MutationEventEncoded<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Encoded<TMutationsDef['schema']>
+  id: EventId.EventId
+  parentId: EventId.EventId
+}
+
+export type Any = MutationEvent<MutationDef.Any>
+export type AnyEncoded = MutationEventEncoded<MutationDef.Any>
+
+export type PartialAny = MutationEventPartial<MutationDef.Any>
+export type PartialAnyEncoded = MutationEventPartialEncoded<MutationDef.Any>
+
+export type PartialForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_MutationDefMapType']]: MutationEventPartial<TSchema['_MutationDefMapType'][K]>
+}[keyof TSchema['_MutationDefMapType']]
+
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_MutationDefMapType']]: MutationEvent<TSchema['_MutationDefMapType'][K]>
+}[keyof TSchema['_MutationDefMapType']]
+
+export const isPartialMutationEvent = (mutationEvent: Any | PartialAny): mutationEvent is PartialAny =>
+  'id' in mutationEvent === false && 'parentId' in mutationEvent === false
+
+export type ForMutationDefRecord<TMutationsDefRecord extends MutationDefRecord> = Schema.Schema<
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
+      id: EventId.EventId
+      parentId: EventId.EventId
+    }
+  }[keyof TMutationsDefRecord],
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
+      id: EventId.EventId
+      parentId: EventId.EventId
+    }
+  }[keyof TMutationsDefRecord]
+>
+
+export type MutationEventPartialSchema<TMutationsDefRecord extends MutationDefRecord> = Schema.Schema<
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
+    }
+  }[keyof TMutationsDefRecord],
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
+    }
+  }[keyof TMutationsDefRecord]
+>
+
+export const makeMutationEventSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): ForMutationDefRecord<TSchema['_MutationDefMapType']> =>
+  Schema.Union(
+    ...[...schema.mutations.values()].map((def) =>
+      Schema.Struct({
+        mutation: Schema.Literal(def.name),
+        args: def.schema,
+        id: EventId.EventId,
+        parentId: EventId.EventId,
+      }),
+    ),
+  ).annotations({ title: 'MutationEvent' }) as any
+
+export const makeMutationEventPartialSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): MutationEventPartialSchema<TSchema['_MutationDefMapType']> =>
+  Schema.Union(
+    ...[...schema.mutations.values()].map((def) =>
+      Schema.Struct({
+        mutation: Schema.Literal(def.name),
+        args: def.schema,
+      }),
+    ),
+  ).annotations({ title: 'MutationEventSchemaPartial' }) as any
+
+export const makeMutationEventSchemaMemo = memoizeByRef(makeMutationEventSchema)
+
+export const Any = Schema.Struct({
+  mutation: Schema.String,
+  args: Schema.Any,
+  id: EventId.EventId,
+  parentId: EventId.EventId,
+}).annotations({ title: 'MutationEvent.Any' })
+
+export const DecodedAny = Schema.typeSchema(Any).annotations({
+  title: 'MutationEvent.DecodedAny',
+})
+
+export const EncodedAny = Schema.encodedSchema(Any).annotations({
+  title: 'MutationEvent.EncodedAny',
+})
+
+/** Equivalent to EncodedAny but with a meta field and some convenience methods */
+export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('MutationEvent.EncodedWithMeta')({
+  mutation: Schema.String,
+  args: Schema.Any,
+  id: EventId.EventId,
+  parentId: EventId.EventId,
+  meta: Schema.optionalWith(
+    Schema.Any as Schema.Schema<{ deferred?: Deferred.Deferred<void>; sessionChangeset?: Uint8Array }>,
+    { default: () => ({}) },
+  ),
+}) {
+  toJSON = (): any => {
+    // Only used for logging/debugging
+    // - More readable way to print the id + parentId
+    // - not including `meta`
+    return {
+      id: `(${this.id.global},${this.id.local}) → (${this.parentId.global},${this.parentId.local})`,
+      mutation: this.mutation,
+      args: this.args,
+    }
+  }
+
+  rebase = (parentId: EventId.EventId, isLocal: boolean) =>
+    new EncodedWithMeta({
+      ...this,
+      ...EventId.nextPair(this.id, isLocal),
+    })
+}
+
+export const isEqualEncoded = (a: AnyEncoded, b: AnyEncoded) =>
+  a.id.global === b.id.global &&
+  a.id.local === b.id.local &&
+  a.mutation === b.mutation &&
+  // TODO use schema equality here
+  JSON.stringify(a.args) === JSON.stringify(b.args)

package/src/schema/mod.ts

@@ -0,0 +1,7 @@
+export * from './system-tables.js'
+export * as DbSchema from './table-def.js'
+export * from './mutations.js'
+export * from './schema-helpers.js'
+export * from './schema.js'
+export * as MutationEvent from './MutationEvent.js'
+export * as EventId from './EventId.js'

package/src/schema/mutations.ts

@@ -1,9 +1,7 @@
-import { memoizeByRef } from '@livestore/utils'
 import { Schema } from '@livestore/utils/effect'
 
-import { EventId } from '../adapter-types.js'
 import type { BindValues } from '../sql-queries/sql-queries.js'
-import type { LiveStoreSchema } from './index.js'
+import type * as EventId from './EventId.js'
 
 export type MutationDefMap = Map<string | 'livestore.RawSql', MutationDef.Any>
 export type MutationDefRecord = {
@@ -57,7 +55,7 @@ export type MutationDef<TName extends string, TFrom, TTo> = {
     mutation: TName
     args: TTo
     // TODO remove/clean up after sync-next is fully implemented
-    id?: EventId
+    id?: EventId.EventId
   }
 }
 
@@ -102,6 +100,8 @@ export const defineFacts = <
 ): TRecord => record
 
 export type DefineMutationOptions<TTo> = {
+  // TODO actually implement this
+  onError?: (error: any) => void
   historyId?: string
   /** Warning: This feature is not fully implemented yet */
   facts?: (
@@ -133,7 +133,7 @@ export const defineMutation = <TName extends string, TFrom, TTo>(
   const makePartialEvent = (
     args: TTo,
     options?: {
-      id?: EventId
+      id?: EventId.EventId
     },
   ) => ({ mutation: name, args, ...options })
 
@@ -190,124 +190,3 @@ export const rawSqlMutation = defineMutation(
 
 export type RawSqlMutation = typeof rawSqlMutation
 export type RawSqlMutationEvent = ReturnType<typeof rawSqlMutation>
-
-export type MutationEventPartial<TMutationsDef extends MutationDef.Any> = {
-  mutation: TMutationsDef['name']
-  args: Schema.Schema.Type<TMutationsDef['schema']>
-}
-
-export type MutationEventPartialEncoded<TMutationsDef extends MutationDef.Any> = {
-  mutation: TMutationsDef['name']
-  args: Schema.Schema.Encoded<TMutationsDef['schema']>
-}
-
-export type MutationEvent<TMutationsDef extends MutationDef.Any> = {
-  mutation: TMutationsDef['name']
-  args: Schema.Schema.Type<TMutationsDef['schema']>
-  id: EventId
-  parentId: EventId
-}
-
-export type MutationEventEncoded<TMutationsDef extends MutationDef.Any> = {
-  mutation: TMutationsDef['name']
-  args: Schema.Schema.Encoded<TMutationsDef['schema']>
-  id: EventId
-  parentId: EventId
-}
-
-export namespace MutationEvent {
-  export type Any = MutationEvent<MutationDef.Any>
-  export type AnyEncoded = MutationEventEncoded<MutationDef.Any>
-
-  export type PartialAny = MutationEventPartial<MutationDef.Any>
-  export type PartialAnyEncoded = MutationEventPartialEncoded<MutationDef.Any>
-
-  export type PartialForSchema<TSchema extends LiveStoreSchema> = {
-    [K in keyof TSchema['_MutationDefMapType']]: MutationEventPartial<TSchema['_MutationDefMapType'][K]>
-  }[keyof TSchema['_MutationDefMapType']]
-
-  export type ForSchema<TSchema extends LiveStoreSchema> = {
-    [K in keyof TSchema['_MutationDefMapType']]: MutationEvent<TSchema['_MutationDefMapType'][K]>
-  }[keyof TSchema['_MutationDefMapType']]
-}
-
-export const isPartialMutationEvent = (
-  mutationEvent: MutationEvent.Any | MutationEvent.PartialAny,
-): mutationEvent is MutationEvent.PartialAny => 'id' in mutationEvent === false && 'parentId' in mutationEvent === false
-
-export type MutationEventSchema<TMutationsDefRecord extends MutationDefRecord> = Schema.Schema<
-  {
-    [K in keyof TMutationsDefRecord]: {
-      mutation: K
-      args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
-      id: EventId
-      parentId: EventId
-    }
-  }[keyof TMutationsDefRecord],
-  {
-    [K in keyof TMutationsDefRecord]: {
-      mutation: K
-      args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
-      id: EventId
-      parentId: EventId
-    }
-  }[keyof TMutationsDefRecord]
->
-
-export type MutationEventPartialSchema<TMutationsDefRecord extends MutationDefRecord> = Schema.Schema<
-  {
-    [K in keyof TMutationsDefRecord]: {
-      mutation: K
-      args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
-    }
-  }[keyof TMutationsDefRecord],
-  {
-    [K in keyof TMutationsDefRecord]: {
-      mutation: K
-      args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
-    }
-  }[keyof TMutationsDefRecord]
->
-
-export const makeMutationEventSchema = <TSchema extends LiveStoreSchema>(
-  schema: TSchema,
-): MutationEventSchema<TSchema['_MutationDefMapType']> =>
-  Schema.Union(
-    ...[...schema.mutations.values()].map((def) =>
-      Schema.Struct({
-        mutation: Schema.Literal(def.name),
-        args: def.schema,
-        id: EventId,
-        parentId: EventId,
-      }),
-    ),
-  ).annotations({ title: 'MutationEventSchema' }) as any
-
-export const makeMutationEventPartialSchema = <TSchema extends LiveStoreSchema>(
-  schema: TSchema,
-): MutationEventPartialSchema<TSchema['_MutationDefMapType']> =>
-  Schema.Union(
-    ...[...schema.mutations.values()].map((def) =>
-      Schema.Struct({
-        mutation: Schema.Literal(def.name),
-        args: def.schema,
-      }),
-    ),
-  ).annotations({ title: 'MutationEventSchemaPartial' }) as any
-
-export const makeMutationEventSchemaMemo = memoizeByRef(makeMutationEventSchema)
-
-export const mutationEventSchemaAny = Schema.Struct({
-  mutation: Schema.String,
-  args: Schema.Any,
-  id: EventId,
-  parentId: EventId,
-}).annotations({ title: 'MutationEventSchema.Any' })
-
-export const mutationEventSchemaDecodedAny = Schema.typeSchema(mutationEventSchemaAny).annotations({
-  title: 'MutationEventSchema.DecodedAny',
-})
-
-export const mutationEventSchemaEncodedAny = Schema.encodedSchema(mutationEventSchemaAny).annotations({
-  title: 'MutationEventSchema.EncodedAny',
-})

package/src/schema/{index.ts → schema.ts}

@@ -15,11 +15,6 @@ import { systemTables } from './system-tables.js'
 import type { TableDef, TableDefBase } from './table-def.js'
 import { tableHasDerivedMutations } from './table-def.js'
 
-export * from './system-tables.js'
-export * as DbSchema from './table-def.js'
-export * from './mutations.js'
-export * from './schema-helpers.js'
-
 export const LiveStoreSchemaSymbol = Symbol.for('livestore.LiveStoreSchema')
 export type LiveStoreSchemaSymbol = typeof LiveStoreSchemaSymbol
 

package/src/schema/system-tables.ts

@@ -45,9 +45,13 @@ export const SESSION_CHANGESET_META_TABLE = '__livestore_session_changeset'
 export const sessionChangesetMetaTable = table(
   SESSION_CHANGESET_META_TABLE,
   {
-    idGlobal: SqliteDsl.integer({ primaryKey: true }),
-    idLocal: SqliteDsl.integer({ primaryKey: true }),
+    // TODO bring back primary key
+    idGlobal: SqliteDsl.integer({}),
+    idLocal: SqliteDsl.integer({}),
+    // idGlobal: SqliteDsl.integer({ primaryKey: true }),
+    // idLocal: SqliteDsl.integer({ primaryKey: true }),
     changeset: SqliteDsl.blob({}),
+    debug: SqliteDsl.json({ nullable: true }),
   },
   { disableAutomaticIdColumn: true },
 )
@@ -73,12 +77,21 @@ export const mutationLogMetaTable = table(
     mutation: SqliteDsl.text({}),
     argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
     schemaHash: SqliteDsl.integer({}),
-    /** ISO date format */
-    createdAt: SqliteDsl.text({}),
-    syncStatus: SqliteDsl.text({ schema: SyncStatus }),
     syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
   },
   { disableAutomaticIdColumn: true, indexes: [] },
 )
 
 export type MutationLogMetaRow = FromTable.RowDecoded<typeof mutationLogMetaTable>
+
+export const SYNC_STATUS_TABLE = '__livestore_sync_status'
+
+export const syncStatusTable = table(
+  SYNC_STATUS_TABLE,
+  {
+    head: SqliteDsl.integer({ primaryKey: true }),
+  },
+  { disableAutomaticIdColumn: true },
+)
+
+export type SyncStatusRow = FromTable.RowDecoded<typeof syncStatusTable>

package/src/schema-management/migrations.ts

@@ -3,7 +3,7 @@ import { memoizeByStringifyArgs } from '@livestore/utils'
 import { Effect, Schema as EffectSchema } from '@livestore/utils/effect'
 
 import type { SynchronousDatabase } from '../adapter-types.js'
-import type { LiveStoreSchema } from '../schema/index.js'
+import type { LiveStoreSchema } from '../schema/mod.js'
 import type { SchemaMetaRow, SchemaMutationsMetaRow } from '../schema/system-tables.js'
 import {
   SCHEMA_META_TABLE,
@@ -151,7 +151,14 @@ export const migrateTable = ({
         { tableName, schemaHash, updatedAt },
       )
     }
-  }).pipe(Effect.withSpan('@livestore/common:migrateTable', { attributes: { tableName: tableAst.name } }))
+  }).pipe(
+    Effect.withSpan('@livestore/common:migrateTable', {
+      attributes: {
+        'span.label': tableAst.name,
+        tableName: tableAst.name,
+      },
+    }),
+  )
 
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
   const uniqueStr = index.unique ? 'UNIQUE' : ''

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

@@ -1,7 +1,7 @@
 import { Effect, Schema } from '@livestore/utils/effect'
 
 import { UnexpectedError } from '../adapter-types.js'
-import type { LiveStoreSchema } from '../schema/index.js'
+import type { LiveStoreSchema } from '../schema/mod.js'
 import type { MutationDef } from '../schema/mutations.js'
 import type { MutationDefInfo, SchemaManager } from './common.js'
 

package/src/sync/client-session-sync-processor.ts

@@ -0,0 +1,207 @@
+import { LS_DEV, shouldNeverHappen, TRACE_VERBOSE } from '@livestore/utils'
+import type { Scope } from '@livestore/utils/effect'
+import { Effect, Schema, Stream } from '@livestore/utils/effect'
+import * as otel from '@opentelemetry/api'
+
+import type { Coordinator, UnexpectedError } from '../adapter-types.js'
+import * as EventId from '../schema/EventId.js'
+import { type LiveStoreSchema } from '../schema/mod.js'
+import * as MutationEvent from '../schema/MutationEvent.js'
+import type { SyncState } from './syncstate.js'
+import { updateSyncState } from './syncstate.js'
+
+/**
+ * Rebase behaviour:
+ * - We continously pull mutations 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 mutations on top of the leader's head.
+ * - The goal is to never block the UI, so we'll interrupt rebasing if a new mutations 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
+ */
+export const makeClientSessionSyncProcessor = ({
+  schema,
+  initialLeaderHead,
+  pushToLeader,
+  pullFromLeader,
+  applyMutation,
+  rollback,
+  refreshTables,
+  span,
+}: {
+  schema: LiveStoreSchema
+  initialLeaderHead: EventId.EventId
+  pushToLeader: (batch: ReadonlyArray<MutationEvent.AnyEncoded>) => void
+  pullFromLeader: Coordinator['mutations']['pull']
+  applyMutation: (
+    mutationEventDecoded: MutationEvent.PartialAny,
+    options: { otelContext: otel.Context; withChangeset: boolean },
+  ) => {
+    writeTables: Set<string>
+    sessionChangeset: Uint8Array | undefined
+  }
+  rollback: (changeset: Uint8Array) => void
+  refreshTables: (tables: Set<string>) => void
+  // rebaseBehaviour: 'auto-rebase' | 'manual-rebase'
+  span: otel.Span
+}): ClientSessionSyncProcessor => {
+  const mutationEventSchema = MutationEvent.makeMutationEventSchemaMemo(schema)
+
+  const syncStateRef = {
+    current: {
+      localHead: initialLeaderHead,
+      upstreamHead: initialLeaderHead,
+      pending: [],
+      // TODO init rollbackTail from leader to be ready for backend rebasing
+      rollbackTail: [],
+    } as SyncState,
+  }
+
+  const isLocalEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) => {
+    const mutationDef = schema.mutations.get(mutationEventEncoded.mutation)!
+    return mutationDef.options.localOnly
+  }
+
+  const push: ClientSessionSyncProcessor['push'] = (batch, { otelContext }) => {
+    // TODO validate batch
+
+    let baseEventId = syncStateRef.current.localHead
+    const encodedMutationEvents = batch.map((mutationEvent) => {
+      const mutationDef = schema.mutations.get(mutationEvent.mutation)!
+      const nextIdPair = EventId.nextPair(baseEventId, mutationDef.options.localOnly)
+      baseEventId = nextIdPair.id
+      return new MutationEvent.EncodedWithMeta(
+        Schema.encodeUnknownSync(mutationEventSchema)({ ...mutationEvent, ...nextIdPair }),
+      )
+    })
+
+    const updateResult = updateSyncState({
+      syncState: syncStateRef.current,
+      payload: { _tag: 'local-push', newEvents: encodedMutationEvents },
+      isLocalEvent,
+      isEqualEvent: MutationEvent.isEqualEncoded,
+    })
+
+    span.addEvent('local-push', {
+      batchSize: encodedMutationEvents.length,
+      updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+    })
+
+    if (updateResult._tag !== 'advance') {
+      return shouldNeverHappen(`Expected advance, got ${updateResult._tag}`)
+    }
+
+    syncStateRef.current = updateResult.newSyncState
+
+    const writeTables = new Set<string>()
+    for (const mutationEvent of updateResult.newEvents) {
+      // TODO avoid encoding and decoding here again
+      const decodedMutationEvent = Schema.decodeSync(mutationEventSchema)(mutationEvent)
+      const res = applyMutation(decodedMutationEvent, { otelContext, withChangeset: true })
+      for (const table of res.writeTables) {
+        writeTables.add(table)
+      }
+      mutationEvent.meta.sessionChangeset = res.sessionChangeset
+    }
+
+    pushToLeader(encodedMutationEvents)
+
+    return { writeTables }
+  }
+
+  const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+  const boot: ClientSessionSyncProcessor['boot'] = Effect.gen(function* () {
+    yield* pullFromLeader.pipe(
+      Stream.tap(({ payload, remaining }) =>
+        Effect.gen(function* () {
+          // console.log('pulled payload from leader', { payload, remaining })
+
+          const updateResult = updateSyncState({
+            syncState: syncStateRef.current,
+            payload,
+            isLocalEvent,
+            isEqualEvent: MutationEvent.isEqualEncoded,
+          })
+
+          if (updateResult._tag === 'reject') {
+            debugger
+            throw new Error('TODO: implement reject in client-session-sync-queue for pull')
+          }
+
+          syncStateRef.current = updateResult.newSyncState
+
+          if (updateResult._tag === 'rebase') {
+            span.addEvent('pull:rebase', {
+              payloadTag: payload._tag,
+              payload: TRACE_VERBOSE ? JSON.stringify(payload) : undefined,
+              newEventsCount: updateResult.newEvents.length,
+              rollbackCount: updateResult.eventsToRollback.length,
+              res: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+              remaining,
+            })
+            if (LS_DEV) {
+              console.debug(
+                'pull:rebase: rollback',
+                updateResult.eventsToRollback.length,
+                ...updateResult.eventsToRollback.map((_) => _.toJSON()),
+              )
+            }
+
+            for (let i = updateResult.eventsToRollback.length - 1; i >= 0; i--) {
+              const event = updateResult.eventsToRollback[i]!
+              if (event.meta.sessionChangeset) {
+                rollback(event.meta.sessionChangeset)
+                event.meta.sessionChangeset = undefined
+              }
+            }
+          } else {
+            span.addEvent('pull:advance', {
+              payloadTag: payload._tag,
+              payload: TRACE_VERBOSE ? JSON.stringify(payload) : undefined,
+              newEventsCount: updateResult.newEvents.length,
+              res: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+              remaining,
+            })
+          }
+
+          if (updateResult.newEvents.length === 0) return
+
+          const writeTables = new Set<string>()
+          for (const mutationEvent of updateResult.newEvents) {
+            const decodedMutationEvent = Schema.decodeSync(mutationEventSchema)(mutationEvent)
+            const res = applyMutation(decodedMutationEvent, { otelContext, withChangeset: true })
+            for (const table of res.writeTables) {
+              writeTables.add(table)
+            }
+
+            mutationEvent.meta.sessionChangeset = res.sessionChangeset
+          }
+
+          refreshTables(writeTables)
+        }),
+      ),
+      Stream.runDrain,
+      Effect.tapCauseLogPretty,
+      Effect.forkScoped,
+    )
+  })
+
+  return {
+    push,
+    boot,
+    syncStateRef,
+  } satisfies ClientSessionSyncProcessor
+}
+
+export interface ClientSessionSyncProcessor {
+  push: (
+    batch: ReadonlyArray<MutationEvent.PartialAny>,
+    options: { otelContext: otel.Context },
+  ) => {
+    writeTables: Set<string>
+  }
+  boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
+
+  syncStateRef: { current: SyncState }
+}

package/src/sync/index.ts

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

package/src/sync/next/compact-events.ts

@@ -1,7 +1,8 @@
 import { replacesFacts } from './facts.js'
 import { graphologyDag } from './graphology_.js'
-import type { HistoryDag } from './history-dag.js'
-import { emptyHistoryDag, eventIdToString } from './history-dag.js'
+import { eventIdToString } from './history-dag.js'
+import type { HistoryDag } from './history-dag-common.js'
+import { emptyHistoryDag } from './history-dag-common.js'
 
 /**
  * Idea:

package/src/sync/next/facts.ts

@@ -1,6 +1,6 @@
 import { notYetImplemented } from '@livestore/utils'
 
-import type { EventId } from '../../adapter-types.js'
+import type * as EventId from '../../schema/EventId.js'
 import type {
   FactsCallback,
   MutationEventFactInput,
@@ -9,9 +9,12 @@ import type {
   MutationEventFactsSnapshot,
 } from '../../schema/mutations.js'
 import { graphologyDag } from './graphology_.js'
-import { EMPTY_FACT_VALUE, type HistoryDag, type HistoryDagNode } from './history-dag.js'
+import { EMPTY_FACT_VALUE, type HistoryDag, type HistoryDagNode } from './history-dag-common.js'
 
-export const factsSnapshotForEvents = (events: HistoryDagNode[], endEventId: EventId): MutationEventFactsSnapshot => {
+export const factsSnapshotForEvents = (
+  events: HistoryDagNode[],
+  endEventId: EventId.EventId,
+): MutationEventFactsSnapshot => {
   const facts = new Map<string, any>()
 
   for (const event of events) {
@@ -25,7 +28,10 @@ export const factsSnapshotForEvents = (events: HistoryDagNode[], endEventId: Eve
   return facts
 }
 
-export const factsSnapshotForDag = (dag: HistoryDag, endEventId: EventId | undefined): MutationEventFactsSnapshot => {
+export const factsSnapshotForDag = (
+  dag: HistoryDag,
+  endEventId: EventId.EventId | undefined,
+): MutationEventFactsSnapshot => {
   const facts = new Map<string, any>()
 
   const orderedEventIdStrs = graphologyDag.topologicalSort(dag)
@@ -221,7 +227,7 @@ export const getFactsGroupForMutationArgs = ({
   return facts
 }
 
-export const compareEventIds = (a: EventId, b: EventId) => {
+export const compareEventIds = (a: EventId.EventId, b: EventId.EventId) => {
   if (a.global !== b.global) {
     return a.global - b.global
   }