@livestore/common 0.4.0-dev.0 → 0.4.0-dev.10

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

@@ -1,13 +1,29 @@
-import { shouldNeverHappen } from '@livestore/utils'
+import { omitUndefineds, 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 {
+  Deferred,
+  Effect,
+  KeyValueStore,
+  Layer,
+  PlatformError,
+  Queue,
+  Stream,
+  Subscribable,
+  SubscriptionRef,
+} from '@livestore/utils/effect'
+import {
+  type BootStatus,
+  type MakeSqliteDb,
+  type MaterializerHashMismatchError,
+  type SqliteDb,
+  type SqliteError,
+  UnexpectedError,
+} 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 +33,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,
@@ -71,10 +88,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: syncPayload }).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 +138,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 +176,7 @@ export const makeLeaderThreadLayer = ({
         }
       : { enabled: false as const }
 
-    const materializeEvent = yield* makeMaterializeEvent({ schema, dbState, dbEventlog })
+    const networkStatus = yield* makeNetworkStatusSubscribable({ syncBackend, devtoolsContext })
 
     const ctx = {
       schema,
@@ -131,6 +194,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 +205,7 @@ export const makeLeaderThreadLayer = ({
     const layer = Layer.succeed(LeaderThreadCtx, ctx)
 
     ctx.initialState = yield* bootLeaderThread({
-      dbStateMissing,
+      migrationsReport,
       initialBlockingSyncContext,
       devtoolsOptions,
     }).pipe(Effect.provide(layer))
@@ -244,12 +308,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 +322,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 +335,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,
+  UnexpectedError | 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 +371,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,6 +150,7 @@ export const makeMaterializeEvent = ({
           hash: materializerHash,
         }
       }).pipe(
+        Effect.mapError((cause) => MaterializeError.make({ cause })),
         Effect.withSpan(`@livestore/common:leader-thread:materializeEvent`, {
           attributes: {
             eventName: eventEncoded.name,

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,
+  UnexpectedError,
+} 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 }, UnexpectedError | MaterializeError | SqliteError> =>
   Effect.gen(function* () {
     const migrationOptions = schema.state.sqlite.migrations
     let migrationsReport: MigrationsReport

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,
+  UnexpectedError,
+} from '../index.ts'
 
-export class All extends Schema.Union(IntentionalShutdownCause, UnexpectedError, SyncError) {}
+export class All extends Schema.Union(
+  IntentionalShutdownCause,
+  UnexpectedError,
+  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,
@@ -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.GlobalEventSequenceNumber
   metadata: Option.Option<Schema.JsonValue>
 }>
 
@@ -98,7 +98,7 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
     shutdownChannel: ShutdownChannel
     eventSchema: LiveStoreEvent.ForEventDefRecord<any>
     devtools: DevtoolsContext
-    syncBackend: SyncBackend | undefined
+    syncBackend: SyncBackend.SyncBackend | undefined
     syncProcessor: LeaderSyncProcessor
     materializeEvent: MaterializeEvent
     initialState: {
@@ -111,6 +111,7 @@ 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>
   }
 >() {}
 
@@ -125,12 +126,12 @@ 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 {
@@ -150,6 +151,7 @@ export interface LeaderSyncProcessor {
     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

package/src/materializer-helper.ts

@@ -5,7 +5,7 @@ import type { SqliteDb } from './adapter-types.ts'
 import { SessionIdSymbol } from './adapter-types.ts'
 import type { EventDef, Materializer, MaterializerContextQuery, MaterializerResult } from './schema/EventDef.ts'
 import type * as LiveStoreEvent from './schema/LiveStoreEvent.ts'
-import { getEventDef, type LiveStoreSchema } from './schema/schema.ts'
+import type { LiveStoreSchema } from './schema/schema.ts'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import { isQueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import { getResultSchema } from './schema/state/sqlite/query-builder/impl.ts'
@@ -31,8 +31,13 @@ export const getExecStatementsFromMaterializer = ({
   bindValues: PreparedBindValues
   writeTables: ReadonlySet<string> | undefined
 }> => {
-  const eventArgsDecoded =
-    event.decoded === undefined ? Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args) : event.decoded.args
+  const eventDecoded =
+    event.decoded === undefined
+      ? {
+          ...event.encoded!,
+          args: Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args),
+        }
+      : event.decoded
 
   const eventArgsEncoded = isNil(event.decoded?.args)
     ? undefined
@@ -58,11 +63,12 @@ export const getExecStatementsFromMaterializer = ({
   }
 
   const statementResults = fromMaterializerResult(
-    materializer(eventArgsDecoded, {
+    materializer(eventDecoded.args, {
       eventDef,
       query,
       // TODO properly implement this
       currentFacts: new Map(),
+      event: eventDecoded,
     }),
   )
 
@@ -81,7 +87,18 @@ export const makeMaterializerHash =
   ({ schema, dbState }: { schema: LiveStoreSchema; dbState: SqliteDb }) =>
   (event: LiveStoreEvent.AnyEncoded): Option.Option<number> => {
     if (isDevEnv()) {
-      const { eventDef, materializer } = getEventDef(schema, event.name)
+      // Hashing is only needed during dev-mode diagnostics. Skip work entirely for
+      // unknown events (no definition/materializer) so we do not introduce noisy
+      // warnings while still returning `Option.none()` to disable hash checks.
+      const eventDef = schema.eventsDefsMap.get(event.name)
+      const materializer = schema.state.materializers.get(event.name)
+      if (eventDef === undefined || materializer === undefined) {
+        return Option.none()
+      }
+      // For known events we replay the materializer with the encoded payload and
+      // hash the resulting SQL statements. This lets us cheaply detect
+      // side-effects or logic drift between leader/client materializers without
+      // mutating the underlying state.
       const materializerResults = getExecStatementsFromMaterializer({
         eventDef,
         materializer,

package/src/rematerialize-from-eventlog.ts

@@ -4,7 +4,7 @@ import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
 import { type SqliteDb, UnexpectedError } from './adapter-types.ts'
 import type { MaterializeEvent } from './leader-thread/mod.ts'
 import type { EventDef, LiveStoreSchema } from './schema/mod.ts'
-import { EventSequenceNumber, getEventDef, LiveStoreEvent, SystemTables } from './schema/mod.ts'
+import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from './schema/mod.ts'
 import type { PreparedBindValues } from './util.ts'
 import { sql } from './util.ts'
 
@@ -31,18 +31,45 @@ export const rematerializeFromEventlog = ({
 
     const processEvent = (row: SystemTables.EventlogMetaRow) =>
       Effect.gen(function* () {
-        const eventDef = getEventDef(schema, row.name)
+        const args = JSON.parse(row.argsJson)
+        const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
+          name: row.name,
+          args,
+          seqNum: {
+            global: row.seqNumGlobal,
+            client: row.seqNumClient,
+            rebaseGeneration: row.seqNumRebaseGeneration,
+          },
+          parentSeqNum: {
+            global: row.parentSeqNumGlobal,
+            client: row.parentSeqNumClient,
+            rebaseGeneration: row.parentSeqNumRebaseGeneration,
+          },
+          clientId: row.clientId,
+          sessionId: row.sessionId,
+        })
+
+        const resolution = yield* resolveEventDef(schema, {
+          operation: '@livestore/common:rematerializeFromEventlog:processEvent',
+          event: eventEncoded,
+        }).pipe(UnexpectedError.mapToUnexpectedError)
+
+        if (resolution._tag === 'unknown') {
+          // Old snapshots can contain newer events. Skip until the runtime has
+          // been updated; the event stays in the log for future replays.
+          return
+        }
 
-        if (hashEventDef(eventDef.eventDef) !== row.schemaHash) {
+        const { eventDef } = resolution
+
+        if (hashEventDef(eventDef) !== row.schemaHash) {
           yield* Effect.logWarning(
             `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
           )
         }
 
-        const args = JSON.parse(row.argsJson)
-
         // Checking whether the schema has changed in an incompatible way
-        yield* Schema.decodeUnknown(eventDef.eventDef.schema)(args).pipe(
+        yield* Schema.decodeUnknown(eventDef.schema)(args).pipe(
           Effect.mapError((cause) =>
             UnexpectedError.make({
               cause,
@@ -55,23 +82,6 @@ This likely means the schema has changed in an incompatible way.
           ),
         )
 
-        const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
-          seqNum: {
-            global: row.seqNumGlobal,
-            client: row.seqNumClient,
-            rebaseGeneration: row.seqNumRebaseGeneration,
-          },
-          parentSeqNum: {
-            global: row.parentSeqNumGlobal,
-            client: row.parentSeqNumClient,
-            rebaseGeneration: row.parentSeqNumRebaseGeneration,
-          },
-          name: row.name,
-          args,
-          clientId: row.clientId,
-          sessionId: row.sessionId,
-        })
-
         yield* materializeEvent(eventEncoded, { skipEventlog: true })
       }).pipe(Effect.withSpan(`@livestore/common:rematerializeFromEventlog:processEvent`))
 

package/src/schema/EventDef.ts

@@ -4,6 +4,7 @@ import { Schema } from '@livestore/utils/effect'
 
 import type { BindValues } from '../sql-queries/sql-queries.ts'
 import type { ParamsObject } from '../util.ts'
+import type * as LiveStoreEvent from './LiveStoreEvent.ts'
 import type { QueryBuilder } from './state/sqlite/query-builder/mod.ts'
 
 export type EventDefMap = {
@@ -191,6 +192,8 @@ export type Materializer<TEventDef extends EventDef.AnyWithoutFn = EventDef.AnyW
     eventDef: TEventDef
     /** Can be used to query the current state */
     query: MaterializerContextQuery
+    /** The full LiveStore event with clientId, sessionId, etc. */
+    event: LiveStoreEvent.AnyDecoded
   },
 ) => SingleOrReadonlyArray<MaterializerResult>
 

package/src/schema/LiveStoreEvent.ts

@@ -283,5 +283,4 @@ export const isEqualEncoded = (a: AnyEncoded, b: AnyEncoded) =>
   a.name === b.name &&
   a.clientId === b.clientId &&
   a.sessionId === b.sessionId &&
-  // TODO use schema equality here
-  JSON.stringify(a.args) === JSON.stringify(b.args)
+  JSON.stringify(a.args) === JSON.stringify(b.args) // TODO use schema equality here

package/src/schema/mod.ts

@@ -7,3 +7,5 @@ export * as State from './state/mod.ts'
 export { SqliteAst, SqliteDsl } from './state/sqlite/db-schema/mod.ts'
 export * from './state/sqlite/schema-helpers.ts'
 export * as SystemTables from './state/sqlite/system-tables.ts'
+export type { UnknownEvents } from './unknown-events.ts'
+export { normalizeUnknownEventHandling, resolveEventDef } from './unknown-events.ts'