@livestore/common 0.3.1-dev.0 → 0.3.2-dev.0

package/src/leader-thread/types.ts

@@ -12,13 +12,13 @@ import type {
 import { Context, Schema } from '@livestore/utils/effect'
 import type { MeshNode } from '@livestore/webmesh'
 
-import type { LeaderPullCursor, SqliteError } from '../adapter-types.js'
+import type { MigrationsReport } from '../defs.js'
+import type { SqliteError } from '../errors.js'
 import type {
   BootStatus,
   Devtools,
   LeaderAheadError,
   MakeSqliteDb,
-  MigrationsReport,
   PersistenceInfo,
   SqliteDb,
   SyncBackend,
@@ -121,7 +121,10 @@ export type MaterializeEvent = (
     skipEventlog?: boolean
   },
 ) => Effect.Effect<
-  { sessionChangeset: { _tag: 'sessionChangeset'; data: Uint8Array; debug: any } | { _tag: 'no-op' } },
+  {
+    sessionChangeset: { _tag: 'sessionChangeset'; data: Uint8Array; debug: any } | { _tag: 'no-op' }
+    hash: Option.Option<number>
+  },
   SqliteError | UnexpectedError
 >
 
@@ -133,16 +136,12 @@ export type InitialBlockingSyncContext = {
 export interface LeaderSyncProcessor {
   /** Used by client sessions to subscribe to upstream sync state changes */
   pull: (args: {
-    cursor: LeaderPullCursor
-  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type; mergeCounter: number }, UnexpectedError>
+    cursor: EventSequenceNumber.EventSequenceNumber
+  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }, UnexpectedError>
   /** The `pullQueue` API can be used instead of `pull` when more convenient */
   pullQueue: (args: {
-    cursor: LeaderPullCursor
-  }) => Effect.Effect<
-    Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type; mergeCounter: number }>,
-    UnexpectedError,
-    Scope.Scope
-  >
+    cursor: EventSequenceNumber.EventSequenceNumber
+  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, UnexpectedError, Scope.Scope>
 
   /** Used by client sessions to push events to the leader thread */
   push: (
@@ -170,5 +169,4 @@ export interface LeaderSyncProcessor {
     LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
   >
   syncState: Subscribable.Subscribable<SyncState.SyncState>
-  getMergeCounter: () => number
 }

package/src/make-client-session.ts

@@ -39,7 +39,7 @@ export const makeClientSession = <R>({
   sessionId: string
   isLeader: boolean
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
-  leaderThread: ClientSessionLeaderThreadProxy
+  leaderThread: ClientSessionLeaderThreadProxy.ClientSessionLeaderThreadProxy
   sqliteDb: SqliteDb
   connectWebmeshNode: (args: {
     webmeshNode: Webmesh.MeshNode
@@ -133,4 +133,4 @@ export const makeClientSession = <R>({
       shutdown,
       debugInstanceId,
     } satisfies ClientSession
-  })
+  }).pipe(Effect.withSpan('@livestore/common:make-client-session'))

package/src/materializer-helper.ts

@@ -1,26 +1,27 @@
-import { isNil, isReadonlyArray } from '@livestore/utils'
-import { Schema } from '@livestore/utils/effect'
+import { isDevEnv, isNil, isReadonlyArray } from '@livestore/utils'
+import { Hash, Option, Schema } from '@livestore/utils/effect'
 
 import type { SqliteDb } from './adapter-types.js'
 import { SessionIdSymbol } from './adapter-types.js'
 import type { EventDef, Materializer, MaterializerContextQuery, MaterializerResult } from './schema/EventDef.js'
 import type * as LiveStoreEvent from './schema/LiveStoreEvent.js'
+import { getEventDef, type LiveStoreSchema } from './schema/schema.js'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.js'
 import { isQueryBuilder } from './schema/state/sqlite/query-builder/api.js'
 import { getResultSchema } from './schema/state/sqlite/query-builder/impl.js'
-import { type BindValues } from './sql-queries/sql-queries.js'
+import type { BindValues } from './sql-queries/sql-queries.js'
 import type { ParamsObject, PreparedBindValues } from './util.js'
 import { prepareBindValues } from './util.js'
 
-export const getExecArgsFromEvent = ({
+export const getExecStatementsFromMaterializer = ({
   eventDef,
   materializer,
-  db,
+  dbState,
   event,
 }: {
   eventDef: EventDef.AnyWithoutFn
   materializer: Materializer
-  db: SqliteDb
+  dbState: SqliteDb
   /** Both encoded and decoded events are supported to reduce the number of times we need to decode/encode */
   event:
     | {
@@ -53,25 +54,25 @@ export const getExecArgsFromEvent = ({
   ) => {
     if (isQueryBuilder(rawQueryOrQueryBuilder)) {
       const { query, bindValues } = rawQueryOrQueryBuilder.asSql()
-      const rawResults = db.select(query, prepareBindValues(bindValues, query))
+      const rawResults = dbState.select(query, prepareBindValues(bindValues, query))
       const resultSchema = getResultSchema(rawQueryOrQueryBuilder)
       return Schema.decodeSync(resultSchema)(rawResults)
     } else {
       const { query, bindValues } = rawQueryOrQueryBuilder
-      return db.select(query, prepareBindValues(bindValues, query))
+      return dbState.select(query, prepareBindValues(bindValues, query))
     }
   }
 
-  const res = materializer(eventArgsDecoded, {
-    eventDef,
-    query,
-    // TODO properly implement this
-    currentFacts: new Map(),
-  })
-
-  const statementRes = mapMaterializerResult(res)
+  const statementResults = fromMaterializerResult(
+    materializer(eventArgsDecoded, {
+      eventDef,
+      query,
+      // TODO properly implement this
+      currentFacts: new Map(),
+    }),
+  )
 
-  return statementRes.map((statementRes) => {
+  return statementResults.map((statementRes) => {
     const statementSql = statementRes.sql
 
     const bindValues = typeof statementRes === 'string' ? eventArgsEncoded : statementRes.bindValues
@@ -82,7 +83,32 @@ export const getExecArgsFromEvent = ({
   })
 }
 
-const mapMaterializerResult = (
+export const makeMaterializerHash =
+  ({ schema, dbState }: { schema: LiveStoreSchema; dbState: SqliteDb }) =>
+  (event: LiveStoreEvent.AnyEncodedGlobal): Option.Option<number> => {
+    if (isDevEnv()) {
+      const { eventDef, materializer } = getEventDef(schema, event.name)
+      const materializerResults = getExecStatementsFromMaterializer({
+        eventDef,
+        materializer,
+        dbState,
+        event: { decoded: undefined, encoded: event },
+      })
+      return Option.some(Hash.string(JSON.stringify(materializerResults)))
+    }
+
+    return Option.none()
+  }
+
+export const hashMaterializerResults = (
+  materializerResults: ReadonlyArray<{
+    statementSql: string
+    bindValues: PreparedBindValues
+    writeTables: ReadonlySet<string> | undefined
+  }>,
+) => Hash.string(JSON.stringify(materializerResults))
+
+const fromMaterializerResult = (
   materializerResult: MaterializerResult | ReadonlyArray<MaterializerResult>,
 ): ReadonlyArray<{
   sql: string
@@ -90,7 +116,7 @@ const mapMaterializerResult = (
   writeTables: ReadonlySet<string> | undefined
 }> => {
   if (isReadonlyArray(materializerResult)) {
-    return materializerResult.flatMap(mapMaterializerResult)
+    return materializerResult.flatMap(fromMaterializerResult)
   }
   if (isQueryBuilder(materializerResult)) {
     const { query, bindValues } = materializerResult.asSql()

package/src/rematerialize-from-eventlog.ts

@@ -27,13 +27,13 @@ export const rematerializeFromEventlog = ({
       `SELECT COUNT(*) AS count FROM ${SystemTables.EVENTLOG_META_TABLE}`,
     )[0]!.count
 
-    const hashEvent = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
+    const hashEventDef = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
 
     const processEvent = (row: SystemTables.EventlogMetaRow) =>
       Effect.gen(function* () {
         const eventDef = getEventDef(schema, row.name)
 
-        if (hashEvent(eventDef.eventDef) !== row.schemaHash) {
+        if (hashEventDef(eventDef.eventDef) !== row.schemaHash) {
           yield* Effect.logWarning(
             `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
           )
@@ -56,8 +56,16 @@ This likely means the schema has changed in an incompatible way.
         )
 
         const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
-          seqNum: { global: row.seqNumGlobal, client: row.seqNumClient },
-          parentSeqNum: { global: row.parentSeqNumGlobal, client: row.parentSeqNumClient },
+          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,

package/src/schema/EventDef.ts

@@ -27,12 +27,20 @@ export type EventDef<TName extends string, TType, TEncoded = TType, TDerived ext
     derived: TDerived
   }
 
-  /** Helper function to construct a partial mutation event */
-  (args: TType): {
+  /** Helper function to construct a partial event */
+  (
+    args: TType,
+  ): {
     name: TName
     args: TType
   }
 
+  /** Helper function to construct a partial encoded event */
+  encoded: (args: TEncoded) => {
+    name: TName
+    args: TEncoded
+  }
+
   readonly Event: {
     name: TName
     args: TType
@@ -123,6 +131,10 @@ export const defineEvent = <TName extends string, TType, TEncoded = TType, TDeri
 
   Object.defineProperty(makePartialEvent, 'name', { value: name })
   Object.defineProperty(makePartialEvent, 'schema', { value: schema })
+  Object.defineProperty(makePartialEvent, 'encoded', {
+    value: (args: TEncoded) => ({ name: name, args }),
+  })
+
   Object.defineProperty(makePartialEvent, 'options', {
     value: {
       clientOnly: options?.clientOnly ?? false,
@@ -184,14 +196,14 @@ export type Materializer<TEventDef extends EventDef.AnyWithoutFn = EventDef.AnyW
 ) => SingleOrReadonlyArray<MaterializerResult>
 
 export const defineMaterializer = <TEventDef extends EventDef.AnyWithoutFn>(
-  eventDef: TEventDef,
+  _eventDef: TEventDef,
   materializer: Materializer<TEventDef>,
 ): Materializer<TEventDef> => {
   return materializer
 }
 
 export const materializers = <TInputRecord extends Record<string, EventDef.AnyWithoutFn>>(
-  eventDefRecord: TInputRecord,
+  _eventDefRecord: TInputRecord,
   handlers: {
     [TEventName in TInputRecord[keyof TInputRecord]['name'] as Extract<
       TInputRecord[keyof TInputRecord],

package/src/schema/EventSequenceNumber.test.ts

@@ -4,9 +4,126 @@ import { expect } from 'vitest'
 import { EventSequenceNumber } from './mod.js'
 
 Vitest.describe('EventSequenceNumber', () => {
-  Vitest.test('nextPair', () => {
+  Vitest.test('nextPair (no rebase)', () => {
     const e_0_0 = EventSequenceNumber.make({ global: 0, client: 0 })
-    expect(EventSequenceNumber.nextPair(e_0_0, false).seqNum).toStrictEqual({ global: 1, client: 0 })
-    expect(EventSequenceNumber.nextPair(e_0_0, true).seqNum).toStrictEqual({ global: 0, client: 1 })
+    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: false }).seqNum).toStrictEqual({
+      global: 1,
+      client: 0,
+      rebaseGeneration: 0,
+    })
+    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true }).seqNum).toStrictEqual({
+      global: 0,
+      client: 1,
+      rebaseGeneration: 0,
+    })
+  })
+
+  Vitest.test('nextPair (rebase)', () => {
+    const e_0_0 = EventSequenceNumber.make({ global: 0, client: 0 })
+    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: false, rebaseGeneration: 1 }).seqNum).toStrictEqual({
+      global: 1,
+      client: 0,
+      rebaseGeneration: 1,
+    })
+    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true, rebaseGeneration: 1 }).seqNum).toStrictEqual({
+      global: 0,
+      client: 1,
+      rebaseGeneration: 1,
+    })
+
+    const e_0_0_g1 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 2 })
+    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0_g1, isClient: false }).seqNum).toStrictEqual({
+      global: 1,
+      client: 0,
+      rebaseGeneration: 2,
+    })
+  })
+
+  Vitest.test('toString', () => {
+    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 0 }))).toBe('e0')
+    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 }))).toBe(
+      'e0r1',
+    )
+    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 1 }))).toBe('e0+1')
+    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 }))).toBe(
+      'e0+1r1',
+    )
+    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 5, client: 3, rebaseGeneration: 2 }))).toBe(
+      'e5+3r2',
+    )
+  })
+
+  Vitest.test('fromString', () => {
+    // Basic cases
+    expect(EventSequenceNumber.fromString('e0')).toStrictEqual(EventSequenceNumber.make({ global: 0, client: 0 }))
+    expect(EventSequenceNumber.fromString('e0r1')).toStrictEqual(
+      EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+    )
+    expect(EventSequenceNumber.fromString('e0+1')).toStrictEqual(EventSequenceNumber.make({ global: 0, client: 1 }))
+    expect(EventSequenceNumber.fromString('e0+1r1')).toStrictEqual(
+      EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 }),
+    )
+    expect(EventSequenceNumber.fromString('e5+3r2')).toStrictEqual(
+      EventSequenceNumber.make({ global: 5, client: 3, rebaseGeneration: 2 }),
+    )
+
+    // Error cases
+    expect(() => EventSequenceNumber.fromString('0')).toThrow(
+      'Invalid event sequence number string: must start with "e"',
+    )
+    expect(() => EventSequenceNumber.fromString('eabc')).toThrow(
+      'Invalid event sequence number string: invalid number format',
+    )
+    expect(() => EventSequenceNumber.fromString('e0+abc')).toThrow(
+      'Invalid event sequence number string: invalid number format',
+    )
+    expect(() => EventSequenceNumber.fromString('e0rabc')).toThrow(
+      'Invalid event sequence number string: invalid number format',
+    )
+  })
+
+  Vitest.test('toString/fromString roundtrip', () => {
+    const testCases = [
+      { global: 0, client: 0, rebaseGeneration: 0 },
+      { global: 0, client: 0, rebaseGeneration: 1 },
+      { global: 0, client: 1, rebaseGeneration: 0 },
+      { global: 0, client: 1, rebaseGeneration: 1 },
+      { global: 5, client: 3, rebaseGeneration: 2 },
+      { global: 100, client: 50, rebaseGeneration: 10 },
+    ]
+
+    for (const testCase of testCases) {
+      const original = EventSequenceNumber.make(testCase)
+      const str = EventSequenceNumber.toString(original)
+      const parsed = EventSequenceNumber.fromString(str)
+      expect(parsed).toStrictEqual(original)
+    }
+  })
+
+  Vitest.test('compare', () => {
+    const e_0_0_r0 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 0 })
+    const e_0_0_r1 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 })
+    const e_0_1_r0 = EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 0 })
+    const e_0_1_r1 = EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 })
+    const e_1_0_r0 = EventSequenceNumber.make({ global: 1, client: 0, rebaseGeneration: 0 })
+    const e_1_1_r0 = EventSequenceNumber.make({ global: 1, client: 1, rebaseGeneration: 0 })
+
+    // Global comparison (strongest level)
+    expect(EventSequenceNumber.compare(e_0_0_r0, e_1_0_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.compare(e_1_0_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.compare(e_0_1_r1, e_1_0_r0)).toBeLessThan(0) // global overrides client and rebase
+
+    // Client comparison (second level)
+    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_1_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.compare(e_0_1_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.compare(e_0_0_r1, e_0_1_r0)).toBeLessThan(0) // client overrides rebase
+
+    // Rebase generation comparison (weakest level)
+    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_0_r1)).toBeLessThan(0)
+    expect(EventSequenceNumber.compare(e_0_0_r1, e_0_0_r0)).toBeGreaterThan(0)
+
+    // Equal comparison
+    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_0_r0)).toBe(0)
+    expect(EventSequenceNumber.compare(e_1_1_r0, e_1_1_r0)).toBe(0)
   })
 })

package/src/schema/EventSequenceNumber.ts

@@ -10,6 +10,8 @@ export const GlobalEventSequenceNumber = Schema.fromBrand(globalEventSequenceNum
 
 export const clientDefault = 0 as any as ClientEventSequenceNumber
 
+export const rebaseGenerationDefault = 0
+
 /**
  * LiveStore event sequence number value consisting of a globally unique event sequence number
  * and a client sequence number.
@@ -20,16 +22,17 @@ export type EventSequenceNumber = {
   global: GlobalEventSequenceNumber
   client: ClientEventSequenceNumber
   /**
-   * TODO add generation number in favour of LEADER_MERGE_COUNTER_TABLE
+   * Generation integer that is incremented whenever the client rebased.
+   * Starts from and resets to 0 for each global sequence number.
    */
-  // generation: number
+  rebaseGeneration: number
 }
 
-// export const EventSequenceNumber = Schema.Struct({})
-// export const EventSequenceNumber = Schema.Struct({})
-// export const ClientEventSequenceNumber = Schema.Struct({})
-// export const GlobalEventSequenceNumber = Schema.Struct({})
+export type EventSequenceNumberInput =
+  | EventSequenceNumber
+  | (Omit<typeof EventSequenceNumber.Encoded, 'rebaseGeneration'> & { rebaseGeneration?: number })
 
+// TODO adjust name to `ClientEventSequenceNumber`
 /**
  * NOTE: Client mutation events with a non-0 client id, won't be synced to the sync backend.
  */
@@ -40,36 +43,83 @@ export const EventSequenceNumber = Schema.Struct({
 
   // TODO also provide a way to see "confirmation level" of event (e.g. confirmed by leader/sync backend)
 
-  // TODO: actually add this field
   // Client only
-  // generation: Schema.Number.pipe(Schema.optional),
-}).annotations({ title: 'LiveStore.EventSequenceNumber' })
+  rebaseGeneration: Schema.Int,
+}).annotations({
+  title: 'LiveStore.EventSequenceNumber',
+  pretty: () => (seqNum) => toString(seqNum),
+})
 
 /**
  * Compare two event sequence numbers i.e. checks if the first event sequence number is less than the second.
+ * Comparison hierarchy: global > client > rebaseGeneration
  */
 export const compare = (a: EventSequenceNumber, b: EventSequenceNumber) => {
   if (a.global !== b.global) {
     return a.global - b.global
   }
-  return a.client - b.client
+  if (a.client !== b.client) {
+    return a.client - b.client
+  }
+  return a.rebaseGeneration - b.rebaseGeneration
 }
 
 /**
  * Convert an event sequence number to a string representation.
  */
-export const toString = (seqNum: EventSequenceNumber) =>
-  seqNum.client === 0 ? `e${seqNum.global}` : `e${seqNum.global}+${seqNum.client}`
+export const toString = (seqNum: EventSequenceNumber) => {
+  const rebaseGenerationStr = seqNum.rebaseGeneration > 0 ? `r${seqNum.rebaseGeneration}` : ''
+  return seqNum.client === 0
+    ? `e${seqNum.global}${rebaseGenerationStr}`
+    : `e${seqNum.global}+${seqNum.client}${rebaseGenerationStr}`
+}
 
 /**
  * Convert a string representation of an event sequence number to an event sequence number.
+ * Parses strings in the format: e{global}[+{client}][r{rebaseGeneration}]
+ * Examples: "e0", "e0r1", "e0+1", "e0+1r1"
  */
 export const fromString = (str: string): EventSequenceNumber => {
-  const [global, client] = str.slice(1, -1).split(',').map(Number)
-  if (global === undefined || client === undefined) {
-    throw new Error('Invalid event sequence number string')
+  if (!str.startsWith('e')) {
+    throw new Error('Invalid event sequence number string: must start with "e"')
+  }
+
+  // Remove the 'e' prefix
+  const remaining = str.slice(1)
+
+  // Parse rebase generation if present
+  let rebaseGeneration = rebaseGenerationDefault
+  let withoutRebase = remaining
+  const rebaseMatch = remaining.match(/r(\d+)$/)
+  if (rebaseMatch !== null) {
+    rebaseGeneration = Number.parseInt(rebaseMatch[1]!, 10)
+    withoutRebase = remaining.slice(0, -rebaseMatch[0].length)
+  }
+
+  // Parse global and client parts
+  const parts = withoutRebase.split('+')
+
+  // Validate that parts contain only digits (and possibly empty for client)
+  if (parts[0] === '' || !/^\d+$/.test(parts[0]!)) {
+    throw new Error('Invalid event sequence number string: invalid number format')
+  }
+
+  if (parts.length > 1 && parts[1] !== undefined && (parts[1] === '' || !/^\d+$/.test(parts[1]))) {
+    throw new Error('Invalid event sequence number string: invalid number format')
+  }
+
+  const global = Number.parseInt(parts[0]!, 10)
+  const client = parts.length > 1 && parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0
+
+  if (Number.isNaN(global) || Number.isNaN(client) || Number.isNaN(rebaseGeneration)) {
+    throw new TypeError('Invalid event sequence number string: invalid number format')
+  }
+
+  return {
+    global: global as any as GlobalEventSequenceNumber,
+    client: client as any as ClientEventSequenceNumber,
+    rebaseGeneration,
   }
-  return { global, client } as EventSequenceNumber
 }
 
 export const isEqual = (a: EventSequenceNumber, b: EventSequenceNumber) =>
@@ -80,6 +130,7 @@ export type EventSequenceNumberPair = { seqNum: EventSequenceNumber; parentSeqNu
 export const ROOT = {
   global: 0 as any as GlobalEventSequenceNumber,
   client: clientDefault,
+  rebaseGeneration: rebaseGenerationDefault,
 } satisfies EventSequenceNumber
 
 export const isGreaterThan = (a: EventSequenceNumber, b: EventSequenceNumber) => {
@@ -101,21 +152,42 @@ export const diff = (a: EventSequenceNumber, b: EventSequenceNumber) => {
   }
 }
 
-export const make = (seqNum: EventSequenceNumber | typeof EventSequenceNumber.Encoded): EventSequenceNumber => {
-  return Schema.is(EventSequenceNumber)(seqNum) ? seqNum : Schema.decodeSync(EventSequenceNumber)(seqNum)
+export const make = (seqNum: EventSequenceNumberInput): EventSequenceNumber => {
+  return Schema.is(EventSequenceNumber)(seqNum)
+    ? seqNum
+    : Schema.decodeSync(EventSequenceNumber)({
+        ...seqNum,
+        rebaseGeneration: seqNum.rebaseGeneration ?? rebaseGenerationDefault,
+      })
 }
 
-export const nextPair = (seqNum: EventSequenceNumber, isLocal: boolean): EventSequenceNumberPair => {
-  if (isLocal) {
+export const nextPair = ({
+  seqNum,
+  isClient,
+  rebaseGeneration,
+}: {
+  seqNum: EventSequenceNumber
+  isClient: boolean
+  rebaseGeneration?: number
+}): EventSequenceNumberPair => {
+  if (isClient) {
     return {
-      seqNum: { global: seqNum.global, client: (seqNum.client + 1) as any as ClientEventSequenceNumber },
+      seqNum: {
+        global: seqNum.global,
+        client: (seqNum.client + 1) as any as ClientEventSequenceNumber,
+        rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+      },
       parentSeqNum: seqNum,
     }
   }
 
   return {
-    seqNum: { global: (seqNum.global + 1) as any as GlobalEventSequenceNumber, client: clientDefault },
+    seqNum: {
+      global: (seqNum.global + 1) as any as GlobalEventSequenceNumber,
+      client: clientDefault,
+      rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+    },
     // NOTE we always point to `client: 0` for non-clientOnly events
-    parentSeqNum: { global: seqNum.global, client: clientDefault },
+    parentSeqNum: { global: seqNum.global, client: clientDefault, rebaseGeneration: seqNum.rebaseGeneration },
   }
 }

package/src/schema/LiveStoreEvent.ts

@@ -171,12 +171,25 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEve
       Schema.TaggedStruct('unset', {}),
     ),
     syncMetadata: Schema.Option(Schema.JsonValue),
+    /** Used to detect if the materializer is side effecting (during dev) */
+    materializerHashLeader: Schema.Option(Schema.Number),
+    materializerHashSession: Schema.Option(Schema.Number),
   }).pipe(
     Schema.mutable,
     Schema.optional,
     Schema.withDefaults({
-      constructor: () => ({ sessionChangeset: { _tag: 'unset' as const }, syncMetadata: Option.none() }),
-      decoding: () => ({ sessionChangeset: { _tag: 'unset' as const }, syncMetadata: Option.none() }),
+      constructor: () => ({
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      }),
+      decoding: () => ({
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      }),
     }),
   ),
 }) {
@@ -208,18 +221,46 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEve
    *          +---- global number
    * Client num is ommitted for global events
    */
-  rebase = (parentSeqNum: EventSequenceNumber.EventSequenceNumber, isClient: boolean) =>
+  rebase = ({
+    parentSeqNum,
+    isClient,
+    rebaseGeneration,
+  }: {
+    parentSeqNum: EventSequenceNumber.EventSequenceNumber
+    isClient: boolean
+    rebaseGeneration: number
+  }) =>
     new EncodedWithMeta({
       ...this,
-      ...EventSequenceNumber.nextPair(parentSeqNum, isClient),
+      ...EventSequenceNumber.nextPair({ seqNum: parentSeqNum, isClient, rebaseGeneration }),
     })
 
-  static fromGlobal = (event: AnyEncodedGlobal, syncMetadata: Option.Option<Schema.JsonValue>) =>
+  static fromGlobal = (
+    event: AnyEncodedGlobal,
+    meta: {
+      syncMetadata: Option.Option<Schema.JsonValue>
+      materializerHashLeader: Option.Option<number>
+      materializerHashSession: Option.Option<number>
+    },
+  ) =>
     new EncodedWithMeta({
       ...event,
-      seqNum: { global: event.seqNum, client: EventSequenceNumber.clientDefault },
-      parentSeqNum: { global: event.parentSeqNum, client: EventSequenceNumber.clientDefault },
-      meta: { sessionChangeset: { _tag: 'unset' as const }, syncMetadata },
+      seqNum: {
+        global: event.seqNum,
+        client: EventSequenceNumber.clientDefault,
+        rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
+      },
+      parentSeqNum: {
+        global: event.parentSeqNum,
+        client: EventSequenceNumber.clientDefault,
+        rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
+      },
+      meta: {
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: meta.syncMetadata,
+        materializerHashLeader: meta.materializerHashLeader,
+        materializerHashSession: meta.materializerHashSession,
+      },
     })
 
   toGlobal = (): AnyEncodedGlobal => ({