@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

package/src/schema/EventSequenceNumber.test.ts

@@ -1,17 +1,18 @@
-import { Vitest } from '@livestore/utils-dev/node-vitest'
 import { expect } from 'vitest'
 
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
 import { EventSequenceNumber } from './mod.ts'
 
 Vitest.describe('EventSequenceNumber', () => {
   Vitest.test('nextPair (no rebase)', () => {
-    const e_0_0 = EventSequenceNumber.make({ global: 0, client: 0 })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: false }).seqNum).toStrictEqual({
+    const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
       rebaseGeneration: 0,
     })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true }).seqNum).toStrictEqual({
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: true }).seqNum).toStrictEqual({
       global: 0,
       client: 1,
       rebaseGeneration: 0,
@@ -19,65 +20,83 @@ Vitest.describe('EventSequenceNumber', () => {
   })
 
   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({
+    const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
+    expect(
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: false, rebaseGeneration: 1 }).seqNum,
+    ).toStrictEqual({
       global: 1,
       client: 0,
-      rebaseGeneration: 0,
+      rebaseGeneration: 1,
     })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true, rebaseGeneration: 1 }).seqNum).toStrictEqual({
+    expect(
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: 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({
+    const e_0_0_g1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 2 })
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0_g1, isClientOnly: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
-      rebaseGeneration: 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',
-    )
+    expect(
+      EventSequenceNumber.Client.toString(EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })),
+    ).toBe('e0')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+      ),
+    ).toBe('e0r1')
+    expect(
+      EventSequenceNumber.Client.toString(EventSequenceNumber.Client.Composite.make({ global: 0, client: 1 })),
+    ).toBe('e0.1')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 }),
+      ),
+    ).toBe('e0.1r1')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.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.Client.fromString('e0')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 }),
+    )
+    expect(EventSequenceNumber.Client.fromString('e0r1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+    )
+    expect(EventSequenceNumber.Client.fromString('e0.1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 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.Client.fromString('e0.1r1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 }),
     )
-    expect(EventSequenceNumber.fromString('e5+3r2')).toStrictEqual(
-      EventSequenceNumber.make({ global: 5, client: 3, rebaseGeneration: 2 }),
+    expect(EventSequenceNumber.Client.fromString('e5.3r2')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 5, client: 3, rebaseGeneration: 2 }),
     )
 
     // Error cases
-    expect(() => EventSequenceNumber.fromString('0')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('0')).toThrow(
       'Invalid event sequence number string: must start with "e"',
     )
-    expect(() => EventSequenceNumber.fromString('eabc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('eabc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
-    expect(() => EventSequenceNumber.fromString('e0+abc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('e0.abc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
-    expect(() => EventSequenceNumber.fromString('e0rabc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('e0rabc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
   })
@@ -93,37 +112,37 @@ Vitest.describe('EventSequenceNumber', () => {
     ]
 
     for (const testCase of testCases) {
-      const original = EventSequenceNumber.make(testCase)
-      const str = EventSequenceNumber.toString(original)
-      const parsed = EventSequenceNumber.fromString(str)
+      const original = EventSequenceNumber.Client.Composite.make(testCase)
+      const str = EventSequenceNumber.Client.toString(original)
+      const parsed = EventSequenceNumber.Client.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 })
+    const e_0_0_r0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 0 })
+    const e_0_0_r1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 })
+    const e_0_1_r0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 0 })
+    const e_0_1_r1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 })
+    const e_1_0_r0 = EventSequenceNumber.Client.Composite.make({ global: 1, client: 0, rebaseGeneration: 0 })
+    const e_1_1_r0 = EventSequenceNumber.Client.Composite.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
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_1_0_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.compare(e_1_0_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.Client.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
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_1_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_1_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.Client.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)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_0_r1)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.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)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_0_r0)).toBe(0)
+    expect(EventSequenceNumber.Client.compare(e_1_1_r0, e_1_1_r0)).toBe(0)
   })
 })

package/src/schema/LiveStoreEvent/client.test.ts

@@ -0,0 +1,142 @@
+import { expect } from 'vitest'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Option, Schema } from '@livestore/utils/effect'
+
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+import { type Encoded, EncodedWithMeta, isEqualEncoded } from './client.ts'
+
+Vitest.describe('EncodedWithMeta', () => {
+  Vitest.test('toGlobal() produces numeric seqNums through JSON.stringify', () => {
+    const event = new EncodedWithMeta({
+      name: 'test-v1',
+      args: { id: '1' },
+      seqNum: EventSequenceNumber.Client.Composite.make({ global: 5, client: 0 }),
+      parentSeqNum: EventSequenceNumber.Client.Composite.make({ global: 4, client: 0 }),
+      clientId: 'client-1',
+      sessionId: 'session-1',
+      meta: {
+        sessionChangeset: { _tag: 'unset' },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      },
+    })
+
+    const global = event.toGlobal()
+    const parsed = JSON.parse(JSON.stringify(global))
+
+    expect(parsed.seqNum).toBe(5)
+    expect(parsed.parentSeqNum).toBe(4)
+  })
+})
+
+Vitest.describe('isEqualEncoded', () => {
+  const makeEncodedEvent = (args: unknown): Encoded => ({
+    name: 'testEvent-v1',
+    args,
+    seqNum: EventSequenceNumber.Client.Composite.make({ global: 1, client: 0 }),
+    parentSeqNum: EventSequenceNumber.Client.Composite.make(EventSequenceNumber.Client.ROOT),
+    clientId: 'client-1',
+    sessionId: 'session-1',
+  })
+
+  Vitest.it('should consider events with identical args as equal', () => {
+    const a = makeEncodedEvent({ id: 'abc', text: 'hello' })
+    const b = makeEncodedEvent({ id: 'abc', text: 'hello' })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different key order in args as equal', () => {
+    const a = makeEncodedEvent({ b: 2, a: 1 })
+    const b = makeEncodedEvent({ a: 1, b: 2 })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different key order in nested args as equal', () => {
+    const a = makeEncodedEvent({ outer: { b: 2, a: 1 }, x: 'y' })
+    const b = makeEncodedEvent({ x: 'y', outer: { a: 1, b: 2 } })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different args values as not equal', () => {
+    const a = makeEncodedEvent({ id: 'abc' })
+    const b = makeEncodedEvent({ id: 'def' })
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+
+  Vitest.it('should consider events with different args keys as not equal', () => {
+    const a = makeEncodedEvent({ a: 1 })
+    const b = makeEncodedEvent({ b: 1 })
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+
+  Vitest.it('should handle null args', () => {
+    const a = makeEncodedEvent(null)
+    const b = makeEncodedEvent(null)
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should handle array args', () => {
+    const a = makeEncodedEvent([1, 2, 3])
+    const b = makeEncodedEvent([1, 2, 3])
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should handle empty object args', () => {
+    const a = makeEncodedEvent({})
+    const b = makeEncodedEvent({})
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different names as not equal', () => {
+    const a = { ...makeEncodedEvent({ id: 'abc' }), name: 'eventA' }
+    const b = { ...makeEncodedEvent({ id: 'abc' }), name: 'eventB' }
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+
+  Vitest.it('should consider events with undefined-valued and missing keys as equal', () => {
+    const a = makeEncodedEvent({ id: 'abc', flag: undefined })
+    const b = makeEncodedEvent({ id: 'abc' })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with nested undefined-valued and missing keys as equal', () => {
+    const a = makeEncodedEvent({ outer: { x: 1, y: undefined } })
+    const b = makeEncodedEvent({ outer: { x: 1 } })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it(
+    'should consider Effect Schema UndefinedOr-encoded args with explicit undefined equal to their JSON-roundtripped form',
+    () => {
+      const argsSchema = Schema.Struct({
+        id: Schema.String,
+        flag: Schema.UndefinedOr(Schema.Boolean),
+      })
+      const localArgs = Schema.encodeUnknownSync(argsSchema)({ id: 'abc', flag: undefined } as any)
+      const wireArgs = JSON.parse(JSON.stringify(localArgs))
+      expect(isEqualEncoded(makeEncodedEvent(localArgs), makeEncodedEvent(wireArgs))).toBe(true)
+    },
+  )
+
+  Vitest.it('should consider Effect Schema optionalKey-encoded args equal to their JSON-roundtripped form', () => {
+    const argsSchema = Schema.Struct({
+      id: Schema.String,
+      label: Schema.optionalKey(Schema.String),
+    })
+    const localArgs = Schema.encodeUnknownSync(argsSchema)({ id: 'abc' } as any)
+    const wireArgs = JSON.parse(JSON.stringify(localArgs))
+    expect(isEqualEncoded(makeEncodedEvent(localArgs), makeEncodedEvent(wireArgs))).toBe(true)
+  })
+
+  Vitest.it('should consider Effect Schema loose-optional encoded args equal to their JSON-roundtripped form', () => {
+    const argsSchema = Schema.Struct({
+      id: Schema.String,
+      label: Schema.optional(Schema.String),
+    })
+    const localArgs = Schema.encodeUnknownSync(argsSchema)({ id: 'abc', label: undefined } as any)
+    const wireArgs = JSON.parse(JSON.stringify(localArgs))
+    expect(isEqualEncoded(makeEncodedEvent(localArgs), makeEncodedEvent(wireArgs))).toBe(true)
+  })
+})

package/src/schema/LiveStoreEvent/client.ts

@@ -0,0 +1,236 @@
+import { deepEqual, memoizeByRef } from '@livestore/utils'
+import { Effect, Option, Schema, Struct } from '@livestore/utils/effect'
+
+import type { EventDef } from '../EventDef/mod.ts'
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+import type { LiveStoreSchema } from '../schema.ts'
+import type * as ForEventDef from './for-event-def.ts'
+import type * as Global from './global.ts'
+
+/** Effect Schema for client events with decoded args. */
+export const Decoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotate({ title: 'LiveStoreEvent.Client.Decoded' })
+
+/**
+ * Effect Schema for client events with encoded args.
+ * @example
+ * ```ts
+ * // Confirmed event (client=0)
+ * const event: LiveStoreEvent.Client.Encoded = {
+ *   name: 'todoCreated-v1',
+ *   args: { id: 'abc', text: 'Buy milk' },
+ *   seqNum: { global: 5, client: 0, rebaseGeneration: 0 },
+ *   parentSeqNum: { global: 4, client: 0, rebaseGeneration: 0 },
+ *   clientId: 'client-xyz',
+ *   sessionId: 'session-123'
+ * }
+ *
+ * // Pending local event (client=1, not yet synced)
+ * const pending: LiveStoreEvent.Client.Encoded = {
+ *   ...event,
+ *   seqNum: { global: 5, client: 1, rebaseGeneration: 0 },  // e5.1
+ * }
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotate({ title: 'LiveStoreEvent.Client.Encoded' })
+
+/** Event with composite sequence numbers and decoded (native TypeScript) args. */
+export type Decoded = ForEventDef.Decoded<EventDef.Any>
+
+/** Event with composite sequence numbers and encoded (serialized) args. */
+export type Encoded = ForEventDef.Encoded<EventDef.Any>
+
+/** Union of all client event types for a given schema (type-safe event discrimination). */
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: ForEventDef.Decoded<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+/**
+ * Internal event representation with metadata for sync processing.
+ * Includes changeset data and materializer hashes for conflict detection and rebasing.
+ *
+ * Note: This class is exported for internal use. The preferred access is via `LiveStoreEvent.Client.EncodedWithMeta`.
+ */
+export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEvent.Client.EncodedWithMeta')({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+  // TODO get rid of `meta` again by cleaning up the usage implementations
+  meta: Schema.Struct({
+    sessionChangeset: Schema.Union([
+      Schema.TaggedStruct('sessionChangeset', {
+        data: Schema.Uint8Array as any as Schema.Codec<Uint8Array<ArrayBuffer>>,
+        debug: Schema.Any.pipe(Schema.optional),
+      }),
+      Schema.TaggedStruct('no-op', {}),
+      Schema.TaggedStruct('unset', {}),
+    ]),
+    syncMetadata: Schema.Option(Schema.Json),
+    /** Used to detect if the materializer is side effecting (during dev) */
+    materializerHashLeader: Schema.Option(Schema.Finite),
+    materializerHashSession: Schema.Option(Schema.Finite),
+  })
+    .mapFields(Struct.map(Schema.mutableKey))
+    .pipe(
+      Schema.withDecodingDefaultType(
+        Effect.succeed({
+          sessionChangeset: { _tag: 'unset' as const },
+          syncMetadata: Option.none(),
+          materializerHashLeader: Option.none(),
+          materializerHashSession: Option.none(),
+        }),
+      ),
+      Schema.withConstructorDefault(
+        Effect.succeed({
+          sessionChangeset: { _tag: 'unset' as const },
+          syncMetadata: Option.none(),
+          materializerHashLeader: Option.none(),
+          materializerHashSession: Option.none(),
+        }),
+      ),
+    ),
+}) {
+  toJSON = (): any => {
+    // Only used for logging/debugging
+    // - More readable way to print the seqNum + parentSeqNum
+    // - not including `meta`, `clientId`, `sessionId`
+    return {
+      seqNum: `${EventSequenceNumber.Client.toString(this.seqNum)} → ${EventSequenceNumber.Client.toString(this.parentSeqNum)} (${this.clientId}, ${this.sessionId})`,
+      name: this.name,
+      args: this.args,
+    }
+  }
+
+  /**
+   * Example: (global event)
+   * For event e2 → e1 which should be rebased on event e3 → e2
+   * the resulting event num will be e4 → e3
+   *
+   * Example: (client event)
+   * For event e2.1 → e2 which should be rebased on event e3 → e2
+   * the resulting event num will be e3.1 → e3
+   *
+   * Syntax: e2.2 → e2.1
+   *          ^ ^    ^ ^
+   *          | |    | +- client parent number
+   *          | |    +--- global parent number
+   *          | +-- client number
+   *          +---- global number
+   * Client num is omitted for global events
+   */
+  rebase = ({
+    parentSeqNum,
+    isClientOnly,
+    rebaseGeneration,
+  }: {
+    parentSeqNum: EventSequenceNumber.Client.Composite
+    isClientOnly: boolean
+    rebaseGeneration: number
+  }) =>
+    new EncodedWithMeta({
+      ...this,
+      ...EventSequenceNumber.Client.nextPair({ seqNum: parentSeqNum, isClientOnly, rebaseGeneration }),
+    })
+
+  static fromGlobal = (
+    event: Global.Encoded,
+    meta: {
+      syncMetadata: Option.Option<Schema.Json>
+      materializerHashLeader: Option.Option<number>
+      materializerHashSession: Option.Option<number>
+    },
+  ) =>
+    new EncodedWithMeta({
+      ...event,
+      seqNum: {
+        global: event.seqNum,
+        client: EventSequenceNumber.Client.DEFAULT,
+        rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
+      },
+      parentSeqNum: {
+        global: event.parentSeqNum,
+        client: EventSequenceNumber.Client.DEFAULT,
+        rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
+      },
+      meta: {
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: meta.syncMetadata,
+        materializerHashLeader: meta.materializerHashLeader,
+        materializerHashSession: meta.materializerHashSession,
+      },
+    })
+
+  toGlobal = (): Global.Encoded => ({
+    name: this.name,
+    args: this.args,
+    seqNum: this.seqNum.global,
+    parentSeqNum: this.parentSeqNum.global,
+    clientId: this.clientId,
+    sessionId: this.sessionId,
+  })
+}
+
+/**
+ * Structural equality check for client events. Compares seqNum (global + client),
+ * name, clientId, sessionId, and args. The `meta` field is ignored.
+ *
+ * Args are compared in their JSON-canonical form: locally-encoded events with
+ * `Schema.UndefinedOr` (or loose `Schema.optional`) fields produce
+ * `{ ..., flag: undefined }`, but JSON wire transport drops the key. Without
+ * canonicalizing, the local pending event compares unequal to its
+ * wire-roundtripped counterpart and the sync merge falsely takes the rebase
+ * path, surfacing as `MaterializerHashMismatchError` for state-dependent
+ * materializers.
+ */
+export const isEqualEncoded = (a: Encoded, b: Encoded) =>
+  a.seqNum.global === b.seqNum.global &&
+  a.seqNum.client === b.seqNum.client &&
+  a.name === b.name &&
+  a.clientId === b.clientId &&
+  a.sessionId === b.sessionId &&
+  deepEqual(canonicalizeArgs(a.args), canonicalizeArgs(b.args)) // TODO use schema equality here
+
+const canonicalizeArgs = (args: unknown): unknown => (args === undefined ? args : JSON.parse(JSON.stringify(args)))
+
+/**
+ * Creates an Effect Schema union for all event types in a schema (with composite sequence numbers).
+ * @example
+ * ```ts
+ * const eventSchema = LiveStoreEvent.Client.makeSchema(schema)
+ * const event = Schema.decodeUnknownSync(eventSchema)(rawEvent)
+ * ```
+ */
+export const makeSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): ForEventDef.ForRecord<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    [...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+        seqNum: EventSequenceNumber.Client.Composite,
+        parentSeqNum: EventSequenceNumber.Client.Composite,
+        clientId: Schema.String,
+        sessionId: Schema.String,
+      }),
+    ),
+  ).annotate({ title: 'LiveStoreEvent.Client' }) as any
+
+/** Memoized `makeSchema` - caches the generated schema by reference. */
+export const makeSchemaMemo = memoizeByRef(makeSchema)

package/src/schema/LiveStoreEvent/for-event-def.ts

@@ -0,0 +1,60 @@
+import type { Schema } from '@livestore/utils/effect'
+
+import type { EventDef, EventDefRecord } from '../EventDef/mod.ts'
+import type * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+
+/** Event without sequence numbers, with decoded (native TypeScript) args. Used as input to `store.commit()`. */
+export type InputDecoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: TEventDef['schema']['Type']
+}
+
+/** Event without sequence numbers, with encoded (serialized) args. Used as input to `store.commit()`. */
+export type InputEncoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: TEventDef['schema']['Encoded']
+}
+
+/** Full event with composite sequence numbers and decoded args. Includes clientId/sessionId for sync. */
+export type Decoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: TEventDef['schema']['Type']
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+}
+
+/** Full event with composite sequence numbers and encoded args. Includes clientId/sessionId for sync. */
+export type Encoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: TEventDef['schema']['Encoded']
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+}
+
+/** Effect Schema union of all event types in an EventDefRecord (with composite sequence numbers). */
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Codec<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: TEventDefRecord[K]['schema']['Type']
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: TEventDefRecord[K]['schema']['Encoded']
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord]
+>

package/src/schema/LiveStoreEvent/global.ts

@@ -0,0 +1,45 @@
+import { Schema } from '@livestore/utils/effect'
+
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+
+/**
+ * Effect Schema for global events with integer sequence numbers.
+ * @example
+ * ```ts
+ * const event: LiveStoreEvent.Global.Encoded = {
+ *   name: 'todoCreated-v1',
+ *   args: { id: 'abc', text: 'Buy milk' },
+ *   seqNum: 5,       // This event's position in the global log
+ *   parentSeqNum: 4, // Points to the previous event
+ *   clientId: 'client-xyz',
+ *   sessionId: 'session-123'
+ * }
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Global.Schema,
+  parentSeqNum: EventSequenceNumber.Global.Schema,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotate({ title: 'LiveStoreEvent.Global.Encoded' })
+
+/** Event with integer sequence numbers for sync backend wire format. */
+export type Encoded = typeof Encoded.Type
+
+/** Converts a Global event to Client format by expanding integer seqNums to composite form. */
+export const toClientEncoded = (
+  event: Encoded,
+): {
+  name: string
+  args: any
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+} => ({
+  ...event,
+  seqNum: EventSequenceNumber.Client.fromGlobal(event.seqNum),
+  parentSeqNum: EventSequenceNumber.Client.fromGlobal(event.parentSeqNum),
+})