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

package/src/schema-management/migrations.ts

@@ -1,20 +1,51 @@
+/**
+ * AUTOMATIC HASH-BASED SCHEMA MIGRATIONS
+ *
+ * This module implements automatic schema versioning using hash-based change detection.
+ *
+ * ⚠️  CRITICAL DISTINCTION:
+ * - STATE TABLES (safe to modify): Changes trigger rematerialization from eventlog
+ * - EVENTLOG TABLES (NEVER modify): Changes cause data loss - need manual versioning!
+ *
+ * How it works:
+ * 1. Each table's schema is hashed using SqliteAst.hash()
+ * 2. Hashes are stored in SCHEMA_META_TABLE after successful migrations
+ * 3. On app start, current schema hashes are compared with stored hashes
+ * 4. Mismatches trigger migrations:
+ *    - State tables: Recreated and repopulated from eventlog (safe, no data loss)
+ *    - Eventlog tables: Uses 'create-if-not-exists' (UNSAFE - causes data loss!)
+ *
+ * State Table Changes (SAFE):
+ * - User-defined tables are rebuilt from eventlog
+ * - System tables (schemaMetaTable, etc.) are recreated
+ * - Data preserved through rematerializeFromEventlog()
+ *
+ * Eventlog Table Changes (UNSAFE):
+ * - eventlogMetaTable, syncStatusTable changes cause "soft reset"
+ * - Old table becomes inaccessible (but remains in DB)
+ * - No automatic migration - effectively data loss
+ * - TODO: Implement proper EVENTLOG_PERSISTENCE_FORMAT_VERSION system
+ *
+ * See system-tables/state-tables.ts and system-tables/eventlog-tables.ts for detailed documentation on each table type.
+ */
+
 import { memoizeByStringifyArgs } from '@livestore/utils'
 import { Effect } from '@livestore/utils/effect'
 
 import type { SqliteDb } from '../adapter-types.ts'
 import type { MigrationsReport, MigrationsReportEntry } from '../defs.ts'
-import type { UnexpectedError } from '../errors.ts'
+import type { UnknownError } from '../errors.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { makeColumnSpec } from '../schema/state/sqlite/column-spec.ts'
 import { SqliteAst } from '../schema/state/sqlite/db-schema/mod.ts'
-import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables.ts'
+import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables/state-tables.ts'
 import {
   isStateSystemTable,
   SCHEMA_EVENT_DEFS_META_TABLE,
   SCHEMA_META_TABLE,
   schemaEventDefsMetaTable,
   stateSystemTables,
-} from '../schema/state/sqlite/system-tables.ts'
+} from '../schema/state/sqlite/system-tables/state-tables.ts'
 import { sql } from '../util.ts'
 import type { SchemaManager } from './common.ts'
 import { dbExecute, dbSelect } from './common.ts'
@@ -56,7 +87,7 @@ export const migrateDb = ({
   db: SqliteDb
   schema: LiveStoreSchema
   onProgress?: (opts: { done: number; total: number }) => Effect.Effect<void>
-}): Effect.Effect<MigrationsReport, UnexpectedError> =>
+}): Effect.Effect<MigrationsReport, UnknownError> =>
   Effect.gen(function* () {
     for (const tableDef of stateSystemTables) {
       yield* migrateTable({
@@ -137,10 +168,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) {
@@ -170,5 +201,7 @@ 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.map((col) => `'${col}'`).join(', ')})`
+  return sql`create ${uniqueStr} index if not exists "${index.name}" on "${tableName}" (${index.columns
+    .map((col) => `"${col}"`)
+    .join(', ')})`
 }

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

@@ -1,7 +1,7 @@
 import { Effect, Schema } from '@livestore/utils/effect'
 
-import { UnexpectedError } from '../adapter-types.ts'
-import type { EventDef } from '../schema/EventDef.ts'
+import { UnknownError } from '../adapter-types.ts'
+import type { EventDef } from '../schema/EventDef/mod.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import type { EventDefInfo, SchemaManager } from './common.ts'
 
@@ -15,7 +15,7 @@ export const validateSchema = (schema: LiveStoreSchema, schemaManager: SchemaMan
     )
 
     if (missingEventDefs.length > 0) {
-      return yield* new UnexpectedError({
+      return yield* new UnknownError({
         cause: `Missing mutation definitions: ${missingEventDefs.map((info) => info.eventName).join(', ')}`,
       })
     }

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

@@ -247,7 +247,15 @@ export const createTable = ({
     .map(([columnName, _]) => columnName)
   const columnDefStrs = Object.entries(table.columns).map(([columnName, columnDef]) => {
     const nullModifier = columnDef.nullable === true ? '' : 'NOT NULL'
-    const defaultModifier = columnDef.default._tag === 'None' ? '' : `DEFAULT ${columnDef.default.value}`
+    const defaultModifier = (() => {
+      if (columnDef.default._tag === 'None') return ''
+      const defaultValue = columnDef.default.value
+      if (typeof defaultValue === 'function') return ''
+      if (defaultValue && typeof defaultValue === 'object' && 'sql' in defaultValue) {
+        return `DEFAULT ${defaultValue.sql}`
+      }
+      return `DEFAULT ${defaultValue}`
+    })()
     return sql`${columnName} ${columnDef.columnType} ${nullModifier} ${defaultModifier}`
   })
 

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

@@ -1,3 +1,4 @@
+import { omitUndefineds } from '@livestore/utils'
 import type { SqliteDsl } from '../schema/state/sqlite/db-schema/mod.ts'
 import type { BindValues } from './sql-queries.ts'
 import * as SqlQueries from './sql-queries.ts'
@@ -16,7 +17,7 @@ export const makeSqlQueryBuilder = <TSchema extends SqliteDsl.DbSchema>(schema:
     limit?: number
   }): [string, BindValues, TTableName] => {
     const columns = schema[tableName]!.columns
-    const [stmt, bindValues] = SqlQueries.findManyRows({ columns, tableName, where, limit })
+    const [stmt, bindValues] = SqlQueries.findManyRows({ columns, tableName, where, ...omitUndefineds({ limit }) })
     return [stmt, bindValues, tableName]
   }
 

package/src/sqlite-types.ts

@@ -1,5 +1,5 @@
 import { type Effect, Schema } from '@livestore/utils/effect'
-import type { SqliteError, UnexpectedError } from './errors.ts'
+import type { SqliteError, UnknownError } from './errors.ts'
 import type { EventSequenceNumber } from './schema/mod.ts'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import type { PreparedBindValues } from './util.ts'
@@ -33,7 +33,7 @@ export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
   makeChangeset: (data: Uint8Array<ArrayBuffer>) => SqliteDbChangeset
 }
 
-export type SqliteDebugInfo = { head: EventSequenceNumber.EventSequenceNumber }
+export type SqliteDebugInfo = { head: EventSequenceNumber.Client.Composite }
 
 // TODO refactor this helper type. It's quite cumbersome to use and should be revisited.
 export type MakeSqliteDb<
@@ -46,7 +46,7 @@ export type MakeSqliteDb<
   TMetadata extends TMetadata_ & { _tag: TInput['_tag'] } = TMetadata_ & { _tag: TInput['_tag'] },
 >(
   input: TInput,
-) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnexpectedError, R>
+) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnknownError, R>
 
 export interface PreparedStatement {
   execute(bindValues: PreparedBindValues | undefined, options?: { onRowsChanged?: (rowsChanged: number) => void }): void

package/src/sync/ClientSessionSyncProcessor.ts

@@ -13,12 +13,13 @@ import {
   Stream,
   Subscribable,
 } from '@livestore/utils/effect'
-import * as otel from '@opentelemetry/api'
+import type * as otel from '@opentelemetry/api'
 
-import { type ClientSession, SyncError, type UnexpectedError } from '../adapter-types.ts'
-import * as EventSequenceNumber from '../schema/EventSequenceNumber.ts'
-import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
-import { getEventDef, type LiveStoreSchema } from '../schema/mod.ts'
+import { type ClientSession, UnknownError } from '../adapter-types.ts'
+import type { MaterializeError } from '../errors.ts'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber/mod.ts'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
+import type { LiveStoreSchema } from '../schema/mod.ts'
 import * as SyncState from './syncstate.ts'
 
 /**
@@ -51,16 +52,19 @@ export const makeClientSessionSyncProcessor = ({
   clientSession: ClientSession
   runtime: Runtime.Runtime<Scope.Scope>
   materializeEvent: (
-    eventDecoded: LiveStoreEvent.AnyDecoded,
-    options: { otelContext: otel.Context; withChangeset: boolean; materializerHashLeader: Option.Option<number> },
-  ) => {
-    writeTables: Set<string>
-    sessionChangeset:
-      | { _tag: 'sessionChangeset'; data: Uint8Array<ArrayBuffer>; debug: any }
-      | { _tag: 'no-op' }
-      | { _tag: 'unset' }
-    materializerHash: Option.Option<number>
-  }
+    eventEncoded: LiveStoreEvent.Client.EncodedWithMeta,
+    options: { withChangeset: boolean; materializerHashLeader: Option.Option<number> },
+  ) => Effect.Effect<
+    {
+      writeTables: Set<string>
+      sessionChangeset:
+        | { _tag: 'sessionChangeset'; data: Uint8Array<ArrayBuffer>; debug: any }
+        | { _tag: 'no-op' }
+        | { _tag: 'unset' }
+      materializerHash: Option.Option<number>
+    },
+    MaterializeError
+  >
   rollback: (changeset: Uint8Array<ArrayBuffer>) => void
   refreshTables: (tables: Set<string>) => void
   span: otel.Span
@@ -74,7 +78,7 @@ export const makeClientSessionSyncProcessor = ({
    */
   confirmUnsavedChanges: boolean
 }): ClientSessionSyncProcessor => {
-  const eventSchema = LiveStoreEvent.makeEventDefSchemaMemo(schema)
+  const eventSchema = LiveStoreEvent.Client.makeSchemaMemo(schema)
 
   const simSleep = <TKey extends keyof ClientSessionSyncProcessorSimulationParams>(
     key: TKey,
@@ -91,26 +95,30 @@ export const makeClientSessionSyncProcessor = ({
     }),
   }
 
-  /** Only used for debugging / observability, it's not relied upon for correctness of the sync processor. */
+  /** Only used for debugging / observability / testing, it's not relied upon for correctness of the sync processor. */
   const syncStateUpdateQueue = Queue.unbounded<SyncState.SyncState>().pipe(Effect.runSync)
-  const isClientEvent = (eventEncoded: LiveStoreEvent.EncodedWithMeta) =>
-    getEventDef(schema, eventEncoded.name).eventDef.options.clientOnly
+  const isClientEvent = (eventEncoded: LiveStoreEvent.Client.EncodedWithMeta) =>
+    schema.eventsDefsMap.get(eventEncoded.name)?.options.clientOnly ?? false
 
   /** 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 leaderPushQueue = BucketQueue.make<LiveStoreEvent.Client.EncodedWithMeta>().pipe(Effect.runSync)
 
-  const push: ClientSessionSyncProcessor['push'] = (batch, { otelContext }) => {
+  const push: ClientSessionSyncProcessor['push'] = Effect.fn('client-session-sync-processor:push')(function* (batch) {
     // TODO validate batch
 
     let baseEventSequenceNumber = syncStateRef.current.localHead
     const encodedEventDefs = batch.map(({ name, args }) => {
-      const eventDef = getEventDef(schema, name)
-      const nextNumPair = EventSequenceNumber.nextPair({
+      const eventDef = schema.eventsDefsMap.get(name)
+      if (eventDef === undefined) {
+        return shouldNeverHappen(`No event definition found for \`${name}\`.`)
+      }
+      const nextNumPair = EventSequenceNumber.Client.nextPair({
         seqNum: baseEventSequenceNumber,
-        isClient: eventDef.eventDef.options.clientOnly,
+        isClient: eventDef.options.clientOnly,
+        rebaseGeneration: baseEventSequenceNumber.rebaseGeneration,
       })
       baseEventSequenceNumber = nextNumPair.seqNum
-      return new LiveStoreEvent.EncodedWithMeta(
+      return new LiveStoreEvent.Client.EncodedWithMeta(
         Schema.encodeUnknownSync(eventSchema)({
           name,
           args,
@@ -125,36 +133,38 @@ export const makeClientSessionSyncProcessor = ({
       syncState: syncStateRef.current,
       payload: { _tag: 'local-push', newEvents: encodedEventDefs },
       isClientEvent,
-      isEqualEvent: LiveStoreEvent.isEqualEncoded,
+      isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
     })
 
-    if (mergeResult._tag === 'unexpected-error') {
-      return shouldNeverHappen('Unexpected error in client-session-sync-processor', mergeResult.message)
-    }
-
-    span.addEvent('local-push', {
+    yield* Effect.annotateCurrentSpan({
       batchSize: encodedEventDefs.length,
-      mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+      mergeResultTag: mergeResult._tag,
+      eventCounts: encodedEventDefs.reduce<Record<string, number>>((acc, event) => {
+        acc[event.name] = (acc[event.name] ?? 0) + 1
+        return acc
+      }, {}),
+      ...(TRACE_VERBOSE && { mergeResult: JSON.stringify(mergeResult) }),
     })
 
+    if (mergeResult._tag === 'unknown-error') {
+      return shouldNeverHappen('Unknown error in client-session-sync-processor', mergeResult.message)
+    }
+
     if (mergeResult._tag !== 'advance') {
       return shouldNeverHappen(`Expected advance, got ${mergeResult._tag}`)
     }
 
     syncStateRef.current = mergeResult.newSyncState
-    syncStateUpdateQueue.offer(mergeResult.newSyncState).pipe(Effect.runSync)
+    yield* syncStateUpdateQueue.offer(mergeResult.newSyncState)
 
     // Materialize events to state
     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 {
         writeTables: newWriteTables,
         sessionChangeset,
         materializerHash,
-      } = materializeEvent(decodedEventDef, {
-        otelContext,
+      } = yield* materializeEvent(event, {
         withChangeset: true,
         materializerHashLeader: Option.none(),
       })
@@ -167,10 +177,10 @@ export const makeClientSessionSyncProcessor = ({
 
     // Trigger push to leader
     // console.debug('pushToLeader', encodedEventDefs.length, ...encodedEventDefs.map((_) => _.toJSON()))
-    BucketQueue.offerAll(leaderPushQueue, encodedEventDefs).pipe(Effect.runSync)
+    yield* BucketQueue.offerAll(leaderPushQueue, encodedEventDefs)
 
     return { writeTables }
-  }
+  })
 
   const debugInfo = {
     rebaseCount: 0,
@@ -178,8 +188,6 @@ export const makeClientSessionSyncProcessor = ({
     rejectCount: 0,
   }
 
-  const otelContext = otel.trace.setSpan(otel.context.active(), span)
-
   const boot: ClientSessionSyncProcessor['boot'] = Effect.gen(function* () {
     if (confirmUnsavedChanges && typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
       const onBeforeUnload = (event: BeforeUnloadEvent) => {
@@ -225,17 +233,16 @@ export const makeClientSessionSyncProcessor = ({
             syncState: syncStateRef.current,
             payload,
             isClientEvent,
-            isEqualEvent: LiveStoreEvent.isEqualEncoded,
+            isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
           })
 
-          if (mergeResult._tag === 'unexpected-error') {
-            return yield* new SyncError({ cause: mergeResult.message })
+          if (mergeResult._tag === 'unknown-error') {
+            return yield* new UnknownError({ cause: mergeResult.message })
           } else if (mergeResult._tag === 'reject') {
             return shouldNeverHappen('Unexpected reject in client-session-sync-processor', mergeResult)
           }
 
           syncStateRef.current = mergeResult.newSyncState
-          yield* syncStateUpdateQueue.offer(mergeResult.newSyncState)
 
           if (mergeResult._tag === 'rebase') {
             span.addEvent('merge:pull:rebase', {
@@ -244,7 +251,6 @@ export const makeClientSessionSyncProcessor = ({
               newEventsCount: mergeResult.newEvents.length,
               rollbackCount: mergeResult.rollbackEvents.length,
               res: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-              rebaseGeneration: mergeResult.newSyncState.localHead.rebaseGeneration,
             })
 
             debugInfo.rebaseCount++
@@ -294,18 +300,19 @@ export const makeClientSessionSyncProcessor = ({
             debugInfo.advanceCount++
           }
 
-          if (mergeResult.newEvents.length === 0) return
+          if (mergeResult.newEvents.length === 0) {
+            // If there are no new events, we need to update the sync state as well
+            yield* syncStateUpdateQueue.offer(mergeResult.newSyncState)
+            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 {
               writeTables: newWriteTables,
               sessionChangeset,
               materializerHash,
-            } = materializeEvent(decodedEventDef, {
-              otelContext,
+            } = yield* materializeEvent(event, {
               withChangeset: true,
               materializerHashLeader: event.meta.materializerHashLeader,
             })
@@ -318,6 +325,9 @@ export const makeClientSessionSyncProcessor = ({
           }
 
           refreshTables(writeTables)
+
+          // We're only triggering the sync state update after all events have been materialized
+          yield* syncStateUpdateQueue.offer(mergeResult.newSyncState)
         }).pipe(
           Effect.tapCauseLogPretty,
           Effect.catchAllCause((cause) => clientSession.shutdown(Exit.failCause(cause))),
@@ -363,12 +373,9 @@ export const makeClientSessionSyncProcessor = ({
 
 export interface ClientSessionSyncProcessor {
   push: (
-    batch: ReadonlyArray<LiveStoreEvent.PartialAnyDecoded>,
-    options: { otelContext: otel.Context },
-  ) => {
-    writeTables: Set<string>
-  }
-  boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
+    batch: ReadonlyArray<LiveStoreEvent.Input.Decoded>,
+  ) => Effect.Effect<{ writeTables: Set<string> }, MaterializeError>
+  boot: Effect.Effect<void, UnknownError, Scope.Scope>
   /**
    * Only used for debugging / observability.
    */
@@ -388,11 +395,11 @@ const SIMULATION_ENABLED = true
 // Warning: High values for the simulation params can lead to very long test runs since those get multiplied with the number of events
 export const ClientSessionSyncProcessorSimulationParams = Schema.Struct({
   pull: Schema.Struct({
-    '1_before_leader_push_fiber_interrupt': Schema.Int.pipe(Schema.between(0, 25)),
-    '2_before_leader_push_queue_clear': Schema.Int.pipe(Schema.between(0, 25)),
-    '3_before_rebase_rollback': Schema.Int.pipe(Schema.between(0, 25)),
-    '4_before_leader_push_queue_offer': Schema.Int.pipe(Schema.between(0, 25)),
-    '5_before_leader_push_fiber_run': Schema.Int.pipe(Schema.between(0, 25)),
+    '1_before_leader_push_fiber_interrupt': Schema.Int.pipe(Schema.between(0, 15)),
+    '2_before_leader_push_queue_clear': Schema.Int.pipe(Schema.between(0, 15)),
+    '3_before_rebase_rollback': Schema.Int.pipe(Schema.between(0, 15)),
+    '4_before_leader_push_queue_offer': Schema.Int.pipe(Schema.between(0, 15)),
+    '5_before_leader_push_fiber_run': Schema.Int.pipe(Schema.between(0, 15)),
   }),
 })
 type ClientSessionSyncProcessorSimulationParams = typeof ClientSessionSyncProcessorSimulationParams.Type

package/src/sync/errors.ts

@@ -0,0 +1,38 @@
+import { Schema } from '@livestore/utils/effect'
+import { UnknownError } from '../errors.ts'
+import { EventSequenceNumber } from '../schema/mod.ts'
+
+export class IsOfflineError extends Schema.TaggedError<IsOfflineError>()('IsOfflineError', {
+  cause: Schema.Defect,
+}) {}
+
+/** Unique ID generated by the backend when its created. Used to check whether the backend identity has changed. */
+export const BackendId = Schema.String.annotations({ title: '@livestore/sync-cf:BackendId' })
+
+export class BackendIdMismatchError extends Schema.TaggedError<BackendIdMismatchError>()('BackendIdMismatchError', {
+  expected: BackendId,
+  received: BackendId,
+}) {}
+
+export class ServerAheadError extends Schema.TaggedError<ServerAheadError>()('ServerAheadError', {
+  minimumExpectedNum: EventSequenceNumber.Global.Schema,
+  providedNum: EventSequenceNumber.Global.Schema,
+}) {}
+
+export class InvalidPushError extends Schema.TaggedError<InvalidPushError>()('InvalidPushError', {
+  cause: Schema.Union(UnknownError, ServerAheadError, BackendIdMismatchError),
+}) {}
+
+export class InvalidPullError extends Schema.TaggedError<InvalidPullError>()('InvalidPullError', {
+  cause: Schema.Defect,
+}) {}
+
+export class LeaderAheadError extends Schema.TaggedError<LeaderAheadError>()('LeaderAheadError', {
+  minimumExpectedNum: EventSequenceNumber.Client.Composite,
+  providedNum: EventSequenceNumber.Client.Composite,
+  /** Generation number the client session should use for subsequent pushes */
+  // nextGeneration: Schema.Number,
+}) {}
+
+export const SyncError = Schema.Union(InvalidPushError, InvalidPullError)
+export type SyncError = typeof SyncError.Type

package/src/sync/index.ts

@@ -1,3 +1,6 @@
 export * from './ClientSessionSyncProcessor.ts'
+export * from './mock-sync-backend.ts'
 export * from './sync.ts'
+export { NetworkStatus } from './sync-backend.ts'
+export * from './transport-chunking.ts'
 export * from './validate-push-payload.ts'

package/src/sync/mock-sync-backend.ts

@@ -0,0 +1,184 @@
+import type { Schema, Scope } from '@livestore/utils/effect'
+import { Effect, Mailbox, Option, Queue, Stream, SubscriptionRef } from '@livestore/utils/effect'
+import { UnknownError } from '../errors.ts'
+import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
+import { InvalidPushError } from './errors.ts'
+import * as SyncBackend from './sync-backend.ts'
+import { validatePushPayload } from './validate-push-payload.ts'
+
+export interface MockSyncBackend {
+  pushedEvents: Stream.Stream<LiveStoreEvent.Global.Encoded>
+  connect: Effect.Effect<void>
+  disconnect: Effect.Effect<void>
+  makeSyncBackend: Effect.Effect<SyncBackend.SyncBackend, UnknownError, Scope.Scope>
+  advance: (...batch: LiveStoreEvent.Global.Encoded[]) => Effect.Effect<void>
+  /** Fail the next N push calls with an InvalidPushError (or custom error) */
+  failNextPushes: (
+    count: number,
+    error?: (batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>,
+  ) => Effect.Effect<void>
+}
+
+export interface MockSyncBackendOptions {
+  /** Chunk size for non-live pulls; defaults to 100 */
+  nonLiveChunkSize?: number
+  /** Initial connected state; defaults to false */
+  startConnected?: boolean
+  // TODO add a "flaky" mode to simulate transient network / server failures for pull/push
+}
+
+export const makeMockSyncBackend = (
+  options?: MockSyncBackendOptions,
+): Effect.Effect<MockSyncBackend, UnknownError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const syncEventSequenceNumberRef = { current: EventSequenceNumber.Client.ROOT.global }
+    const syncPullQueue = yield* Queue.unbounded<LiveStoreEvent.Global.Encoded>()
+    const pushedEventsQueue = yield* Mailbox.make<LiveStoreEvent.Global.Encoded>()
+    const syncIsConnectedRef = yield* SubscriptionRef.make(options?.startConnected ?? false)
+    const allEventsRef: { current: LiveStoreEvent.Global.Encoded[] } = { current: [] }
+
+    const span = yield* Effect.currentSpan.pipe(Effect.orDie)
+
+    const semaphore = yield* Effect.makeSemaphore(1)
+
+    // TODO improve the API and implementation of simulating errors
+    const failCounterRef = yield* SubscriptionRef.make(0)
+    const failEffectRef = yield* SubscriptionRef.make<
+      ((batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>) | undefined
+    >(undefined)
+
+    const makeSyncBackend = Effect.gen(function* () {
+      const nonLiveChunkSize = Math.max(1, options?.nonLiveChunkSize ?? 100)
+
+      // TODO consider making offline state actively error pull/push.
+      // Currently, offline only reflects in `isConnected`, while operations still succeed,
+      // mirroring how some real providers behave during transient disconnects.
+      return SyncBackend.of<Schema.JsonValue>({
+        isConnected: syncIsConnectedRef,
+        connect: SubscriptionRef.set(syncIsConnectedRef, true),
+        ping: Effect.void,
+        pull: (cursor, options) =>
+          (options?.live
+            ? Stream.concat(
+                Stream.make(SyncBackend.pullResItemEmpty()),
+                Stream.fromQueue(syncPullQueue).pipe(
+                  Stream.chunks,
+                  Stream.map((chunk) => ({
+                    batch: [...chunk].map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+                    pageInfo: SyncBackend.pageInfoNoMore,
+                  })),
+                ),
+              )
+            : Stream.fromEffect(
+                Effect.sync(() => {
+                  const lastSeen = cursor.pipe(
+                    Option.match({
+                      onNone: () => EventSequenceNumber.Client.ROOT.global,
+                      onSome: (_) => _.eventSequenceNumber,
+                    }),
+                  )
+                  // All events with seqNum greater than lastSeen
+                  const slice = allEventsRef.current.filter((e) => e.seqNum > lastSeen)
+                  // Split into configured chunk size
+                  const chunks: { events: LiveStoreEvent.Global.Encoded[]; remaining: number }[] = []
+                  for (let i = 0; i < slice.length; i += nonLiveChunkSize) {
+                    const end = Math.min(i + nonLiveChunkSize, slice.length)
+                    const remaining = Math.max(slice.length - end, 0)
+                    chunks.push({ events: slice.slice(i, end), remaining })
+                  }
+                  if (chunks.length === 0) {
+                    chunks.push({ events: [], remaining: 0 })
+                  }
+                  return chunks
+                }),
+              ).pipe(
+                Stream.flatMap((chunks) =>
+                  Stream.fromIterable(chunks).pipe(
+                    Stream.map(({ events, remaining }) => ({
+                      batch: events.map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+                      pageInfo: remaining > 0 ? SyncBackend.pageInfoMoreKnown(remaining) : SyncBackend.pageInfoNoMore,
+                    })),
+                  ),
+                ),
+              )
+          ).pipe(Stream.withSpan('MockSyncBackend:pull', { parent: span })),
+        push: (batch) =>
+          Effect.gen(function* () {
+            yield* validatePushPayload(batch, syncEventSequenceNumberRef.current)
+
+            const remaining = yield* SubscriptionRef.get(failCounterRef)
+            if (remaining > 0) {
+              const maybeFail = yield* SubscriptionRef.get(failEffectRef)
+              // decrement counter first
+              yield* SubscriptionRef.set(failCounterRef, remaining - 1)
+              if (maybeFail) {
+                return yield* maybeFail(batch)
+              }
+              return yield* new InvalidPushError({
+                cause: new UnknownError({ cause: new Error('MockSyncBackend: simulated push failure') }),
+              })
+            }
+
+            yield* Effect.sleep(10).pipe(Effect.withSpan('MockSyncBackend:push:sleep')) // Simulate network latency
+
+            yield* pushedEventsQueue.offerAll(batch)
+            yield* syncPullQueue.offerAll(batch)
+            allEventsRef.current = allEventsRef.current.concat(batch)
+
+            syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
+          }).pipe(
+            Effect.withSpan('MockSyncBackend:push', {
+              parent: span,
+              attributes: {
+                nums: batch.map((_) => _.seqNum),
+              },
+            }),
+            semaphore.withPermits(1),
+          ),
+        metadata: {
+          name: '@livestore/mock-sync',
+          description: 'Just a mock sync backend',
+        },
+        supports: {
+          pullPageInfoKnown: true,
+          pullLive: true,
+        },
+      })
+    })
+
+    const advance = (...batch: LiveStoreEvent.Global.Encoded[]) =>
+      Effect.gen(function* () {
+        syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
+        allEventsRef.current = allEventsRef.current.concat(batch)
+        yield* syncPullQueue.offerAll(batch)
+      }).pipe(
+        Effect.withSpan('MockSyncBackend:advance', {
+          parent: span,
+          attributes: { nums: batch.map((_) => _.seqNum) },
+        }),
+        semaphore.withPermits(1),
+      )
+
+    const connect = SubscriptionRef.set(syncIsConnectedRef, true)
+    const disconnect = SubscriptionRef.set(syncIsConnectedRef, false)
+
+    const failNextPushes = (
+      count: number,
+      error?: (batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>,
+    ) =>
+      Effect.gen(function* () {
+        yield* SubscriptionRef.set(failCounterRef, count)
+        yield* SubscriptionRef.set(failEffectRef, error)
+      })
+
+    return {
+      syncEventSequenceNumberRef,
+      syncPullQueue,
+      pushedEvents: Mailbox.toStream(pushedEventsQueue),
+      connect,
+      disconnect,
+      makeSyncBackend,
+      advance,
+      failNextPushes,
+    }
+  }).pipe(Effect.withSpanScoped('MockSyncBackend'))