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

package/src/schema/EventSequenceNumber.test.ts

@@ -5,13 +5,13 @@ 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 +19,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 +111,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.ts

@@ -0,0 +1,221 @@
+import { 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 => ({
+    ...this,
+    seqNum: this.seqNum.global,
+    parentSeqNum: this.parentSeqNum.global,
+  })
+}
+
+/**
+ * Structural equality check for client events. Compares seqNum (global + client),
+ * name, clientId, sessionId, and args. The `meta` field is ignored.
+ */
+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 &&
+  JSON.stringify(a.args) === JSON.stringify(b.args) // TODO use schema equality here
+
+/**
+ * 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]
+>

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,
+}).annotations({ 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),
+})

package/src/schema/LiveStoreEvent/input.ts

@@ -0,0 +1,63 @@
+import { Schema } from '@livestore/utils/effect'
+
+import type { EventDef, EventDefRecord } from '../EventDef/mod.ts'
+import type { LiveStoreSchema } from '../schema.ts'
+import type * as ForEventDef from './for-event-def.ts'
+
+/**
+ * Effect Schema for validating/decoding input events with encoded args.
+ * @example
+ * ```ts
+ * import { Schema } from '@effect/schema'
+ * const decoded = Schema.decodeUnknownSync(LiveStoreEvent.Input.Encoded)(rawEvent)
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+}).annotations({ title: 'LiveStoreEvent.Input.Encoded' })
+
+/** Event without sequence numbers, with decoded (native TypeScript) args. */
+export type Decoded = ForEventDef.InputDecoded<EventDef.Any>
+
+/** Event without sequence numbers, with encoded (serialized) args. */
+export type Encoded = ForEventDef.InputEncoded<EventDef.Any>
+
+/** Union of all input event types for a given schema (type-safe event discrimination). */
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: ForEventDef.InputDecoded<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+/** Effect Schema union of all event types in an EventDefRecord (input format, no sequence numbers). */
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord]
+>
+
+/**
+ * Creates an Effect Schema union for all event types in a schema (input format, no sequence numbers).
+ * @example
+ * ```ts
+ * const inputSchema = LiveStoreEvent.Input.makeSchema(schema)
+ * const event = Schema.decodeUnknownSync(inputSchema)(rawEvent)
+ * ```
+ */
+export const makeSchema = <TSchema extends LiveStoreSchema>(schema: TSchema): ForRecord<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    ...[...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+      }),
+    ),
+  ).annotations({ title: 'LiveStoreEvent.Input' }) as any

package/src/schema/LiveStoreEvent/mod.ts

@@ -0,0 +1,4 @@
+export * as Client from './client.ts'
+export * as ForEventDef from './for-event-def.ts'
+export * as Global from './global.ts'
+export * as Input from './input.ts'

package/src/schema/events.ts

@@ -1 +1 @@
-export { clientOnly, defineEvent, synced } from './EventDef.ts'
+export { clientOnly, defineEvent, synced } from './EventDef/mod.ts'

package/src/schema/mod.ts

@@ -1,9 +1,11 @@
-export * from './EventDef.ts'
-export * as EventSequenceNumber from './EventSequenceNumber.ts'
+export * from './EventDef/mod.ts'
+export * as EventSequenceNumber from './EventSequenceNumber/mod.ts'
 export * as Events from './events.ts'
-export * as LiveStoreEvent from './LiveStoreEvent.ts'
+export * as LiveStoreEvent from './LiveStoreEvent/mod.ts'
 export * from './schema.ts'
 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 * as SystemTables from './state/sqlite/system-tables/mod.ts'
+export type { UnknownEvents } from './unknown-events.ts'
+export { normalizeUnknownEventHandling, resolveEventDef } from './unknown-events.ts'