@livestore/common 0.4.0-dev.9 → 0.4.0

package/src/schema/EventSequenceNumber/global.ts

@@ -0,0 +1,19 @@
+import { Brand, Schema as S } from '@livestore/utils/effect'
+
+/** Branded integer type for global sequence numbers assigned by the sync backend. */
+export type Type = Brand.Branded<number, 'GlobalEventSequenceNumber'>
+
+const GlobalBrand = Brand.nominal<Type>()
+
+/** Effect Schema for encoding/decoding global sequence numbers. */
+export const Schema = S.fromBrand(GlobalBrand)(S.Int)
+
+/**
+ * Creates a branded global sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const seqNum = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export const make = GlobalBrand

package/src/schema/EventSequenceNumber/mod.ts

@@ -0,0 +1,37 @@
+/**
+ * Client sequence numbers track events created locally before sync confirmation.
+ * Also contains the Composite type combining global and client sequence numbers with a rebase
+ * generation to fully identify an event's position in the eventlog.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * // Client sequence number
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ *
+ * // Composite sequence number
+ * const composite: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0,
+ * }
+ * ```
+ */
+export * as Client from './client.ts'
+
+/**
+ * Global sequence numbers are assigned by the sync backend and represent
+ * the canonical ordering of events across all clients. They are monotonically
+ * increasing integers that establish the authoritative event timeline.
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * const globalSeq = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export * as Global from './global.ts'

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, isClient: 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, isClient: 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, isClient: 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, 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({
+    const e_0_0_g1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 2 })
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0_g1, isClient: 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,129 @@
+import { expect } from 'vitest'
+
+import { Option, Schema } from '@livestore/utils/effect'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+import { EncodedWithMeta, isEqualEncoded, type Encoded } 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 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' } 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,235 @@
+import { deepEqual, memoizeByRef } from '@livestore/utils'
+import { Option, Schema } 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,
+}).annotations({ 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,
+}).annotations({ 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.Schema<Uint8Array<ArrayBuffer>>,
+        debug: Schema.Any.pipe(Schema.optional),
+      }),
+      Schema.TaggedStruct('no-op', {}),
+      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(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      }),
+      decoding: () => ({
+        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,
+    isClient,
+    rebaseGeneration,
+  }: {
+    parentSeqNum: EventSequenceNumber.Client.Composite
+    isClient: boolean
+    rebaseGeneration: number
+  }) =>
+    new EncodedWithMeta({
+      ...this,
+      ...EventSequenceNumber.Client.nextPair({ seqNum: parentSeqNum, isClient, rebaseGeneration }),
+    })
+
+  static fromGlobal = (
+    event: Global.Encoded,
+    meta: {
+      syncMetadata: Option.Option<Schema.JsonValue>
+      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,
+      }),
+    ),
+  ).annotations({ 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: Schema.Schema.Type<TEventDef['schema']>
+}
+
+/** 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: Schema.Schema.Encoded<TEventDef['schema']>
+}
+
+/** 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: Schema.Schema.Type<TEventDef['schema']>
+  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: Schema.Schema.Encoded<TEventDef['schema']>
+  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.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord]
+>