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

package/src/sync/syncstate.ts

@@ -1,8 +1,8 @@
 import { casesHandled, LS_DEV, shouldNeverHappen } from '@livestore/utils'
 import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
-import * as EventSequenceNumber from '../schema/EventSequenceNumber.ts'
-import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber/mod.ts'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
 
 /**
  * SyncState represents the current sync state of a sync node relative to an upstream node.
@@ -15,7 +15,7 @@ import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
  *                 +------------------------+
  *               ▼                       ▼
  *        Upstream Head             Local Head
- *             (1,0)     (1,1), (1,2), (2,0)
+ *              e1        e1.1, e1.2, e2
  * ```
  *
  * **Pending Events**: Events awaiting acknowledgment from the upstream.
@@ -31,7 +31,7 @@ import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
  * Invariants:
  * 1. **Chain Continuity**: Each event must reference its immediate parent.
  * 2. **Head Ordering**: Upstream Head ≤ Local Head.
- * 3. **Event number sequence**: Must follow the pattern (1,0)→(1,1)→(1,2)→(2,0).
+ * 3. **Event number sequence**: Must follow the pattern e1→e1.1→e1.2→e2.
  *
  * A few further notes to help form an intuition:
  * - The goal is to keep the pending events as small as possible (i.e. to have synced with the next upstream node)
@@ -42,16 +42,16 @@ import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
  * handling cases such as upstream rebase, advance and local push.
  */
 export class SyncState extends Schema.Class<SyncState>('SyncState')({
-  pending: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  pending: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   /** What this node expects the next upstream node to have as its own local head */
-  upstreamHead: EventSequenceNumber.EventSequenceNumber,
+  upstreamHead: EventSequenceNumber.Client.Composite,
   /** Equivalent to `pending.at(-1)?.id` if there are pending events */
-  localHead: EventSequenceNumber.EventSequenceNumber,
+  localHead: EventSequenceNumber.Client.Composite,
 }) {
   toJSON = (): any => ({
     pending: this.pending.map((e) => e.toJSON()),
-    upstreamHead: EventSequenceNumber.toString(this.upstreamHead),
-    localHead: EventSequenceNumber.toString(this.localHead),
+    upstreamHead: EventSequenceNumber.Client.toString(this.upstreamHead),
+    localHead: EventSequenceNumber.Client.toString(this.localHead),
   })
 }
 
@@ -60,17 +60,17 @@ export class SyncState extends Schema.Class<SyncState>('SyncState')({
  */
 export class PayloadUpstreamRebase extends Schema.TaggedStruct('upstream-rebase', {
   /** Events which need to be rolled back */
-  rollbackEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  rollbackEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   /** Events which need to be applied after the rollback (already rebased by the upstream node) */
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
 }) {}
 
 export class PayloadUpstreamAdvance extends Schema.TaggedStruct('upstream-advance', {
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
 }) {}
 
 export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
 }) {}
 
 export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {}
@@ -109,9 +109,9 @@ export class MergeContext extends Schema.Class<MergeContext>('MergeContext')({
 export class MergeResultAdvance extends Schema.Class<MergeResultAdvance>('MergeResultAdvance')({
   _tag: Schema.Literal('advance'),
   newSyncState: SyncState,
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   /** Events which were previously pending but are now confirmed */
-  confirmedEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  confirmedEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
@@ -128,9 +128,9 @@ export class MergeResultAdvance extends Schema.Class<MergeResultAdvance>('MergeR
 export class MergeResultRebase extends Schema.Class<MergeResultRebase>('MergeResultRebase')({
   _tag: Schema.Literal('rebase'),
   newSyncState: SyncState,
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   /** Events which need to be rolled back */
-  rollbackEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
+  rollbackEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
@@ -147,20 +147,20 @@ export class MergeResultRebase extends Schema.Class<MergeResultRebase>('MergeRes
 export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeResultReject')({
   _tag: Schema.Literal('reject'),
   /** The minimum id that the new events must have */
-  expectedMinimumId: EventSequenceNumber.EventSequenceNumber,
+  expectedMinimumId: EventSequenceNumber.Client.Composite,
   mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
     return {
       _tag: this._tag,
-      expectedMinimumId: EventSequenceNumber.toString(this.expectedMinimumId),
+      expectedMinimumId: EventSequenceNumber.Client.toString(this.expectedMinimumId),
       mergeContext: this.mergeContext.toJSON(),
     }
   }
 }
 
-export class MergeResultUnexpectedError extends Schema.Class<MergeResultUnexpectedError>('MergeResultUnexpectedError')({
-  _tag: Schema.Literal('unexpected-error'),
+export class MergeResultUnknownError extends Schema.Class<MergeResultUnknownError>('MergeResultUnknownError')({
+  _tag: Schema.Literal('unknown-error'),
   message: Schema.String,
 }) {}
 
@@ -168,7 +168,7 @@ export class MergeResult extends Schema.Union(
   MergeResultAdvance,
   MergeResultRebase,
   MergeResultReject,
-  MergeResultUnexpectedError,
+  MergeResultUnknownError,
 ) {}
 
 export const payloadFromMergeResult = (
@@ -187,13 +187,13 @@ export const payloadFromMergeResult = (
     Match.exhaustive,
   )
 
-const unexpectedError = (message: string): MergeResultUnexpectedError => {
+const unknownError = (message: string): MergeResultUnknownError => {
   if (LS_DEV) {
     // biome-ignore lint/suspicious/noDebugger: debug
     debugger
   }
 
-  return MergeResultUnexpectedError.make({ _tag: 'unexpected-error', message })
+  return MergeResultUnknownError.make({ _tag: 'unknown-error', message })
 }
 
 // TODO Idea: call merge recursively through hierarchy levels
@@ -212,8 +212,8 @@ export const merge = ({
 }: {
   syncState: SyncState
   payload: typeof Payload.Type
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
-  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
+  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
   /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
   ignoreClientEvents?: boolean
 }): typeof MergeResult.Type => {
@@ -271,20 +271,20 @@ export const merge = ({
 
       // Validate that newEvents are sorted in ascending order by eventNum
       for (let i = 1; i < payload.newEvents.length; i++) {
-        if (EventSequenceNumber.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
-          return unexpectedError(
-            `Events must be sorted in ascending order by event number. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+        if (EventSequenceNumber.Client.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
+          return unknownError(
+            `Events must be sorted in ascending order by event number. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
           )
         }
       }
 
       // Validate that incoming events are larger than upstream head
       if (
-        EventSequenceNumber.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) ||
-        EventSequenceNumber.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum)
+        EventSequenceNumber.Client.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) ||
+        EventSequenceNumber.Client.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum)
       ) {
-        return unexpectedError(
-          `Incoming events must be greater than upstream head. Expected greater than: ${EventSequenceNumber.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+        return unknownError(
+          `Incoming events must be greater than upstream head. Expected greater than: ${EventSequenceNumber.Client.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
         )
       }
 
@@ -336,7 +336,7 @@ export const merge = ({
               pending: pendingRemaining,
               upstreamHead: newUpstreamHead,
               localHead:
-                pendingRemaining.at(-1)?.seqNum ?? EventSequenceNumber.max(syncState.localHead, newUpstreamHead),
+                pendingRemaining.at(-1)?.seqNum ?? EventSequenceNumber.Client.max(syncState.localHead, newUpstreamHead),
             }),
             newEvents,
             confirmedEvents: pendingMatching,
@@ -392,10 +392,10 @@ export const merge = ({
 
       const newEventsFirst = payload.newEvents.at(0)!
       const invalidEventSequenceNumber =
-        EventSequenceNumber.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
+        EventSequenceNumber.Client.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
 
       if (invalidEventSequenceNumber) {
-        const expectedMinimumId = EventSequenceNumber.nextPair({
+        const expectedMinimumId = EventSequenceNumber.Client.nextPair({
           seqNum: syncState.localHead,
           isClient: true,
         }).seqNum
@@ -407,13 +407,20 @@ export const merge = ({
           }),
         )
       } else {
+        const nonClientEvents = ignoreClientEvents
+          ? payload.newEvents.filter((event) => !isClientEvent(event))
+          : payload.newEvents
+        const newPending = [...syncState.pending, ...nonClientEvents]
+        const newLocalHead =
+          newPending.at(-1)?.seqNum ?? EventSequenceNumber.Client.max(syncState.localHead, syncState.upstreamHead)
+
         return validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
-              pending: [...syncState.pending, ...payload.newEvents],
+              pending: newPending,
               upstreamHead: syncState.upstreamHead,
-              localHead: payload.newEvents.at(-1)!.seqNum,
+              localHead: newLocalHead,
             }),
             newEvents: payload.newEvents,
             confirmedEvents: [],
@@ -440,10 +447,10 @@ export const findDivergencePoint = ({
   isClientEvent,
   ignoreClientEvents,
 }: {
-  existingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  incomingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
+  existingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  incomingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
   ignoreClientEvents: boolean
 }): number => {
   if (ignoreClientEvents) {
@@ -461,7 +468,7 @@ export const findDivergencePoint = ({
     const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientEvents]!.seqNum
     // Now find the divergence point in the original array
     return existingEvents.findIndex((event) =>
-      EventSequenceNumber.isEqual(event.seqNum, divergencePointEventSequenceNumber),
+      EventSequenceNumber.Client.isEqual(event.seqNum, divergencePointEventSequenceNumber),
     )
   }
 
@@ -477,10 +484,10 @@ const rebaseEvents = ({
   baseEventSequenceNumber,
   isClientEvent,
 }: {
-  events: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  baseEventSequenceNumber: EventSequenceNumber.EventSequenceNumber
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
-}): ReadonlyArray<LiveStoreEvent.EncodedWithMeta> => {
+  events: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  baseEventSequenceNumber: EventSequenceNumber.Client.Composite
+  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+}): ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta> => {
   let prevEventSequenceNumber = baseEventSequenceNumber
   const rebaseGeneration = baseEventSequenceNumber.rebaseGeneration + 1
   return events.map((event) => {
@@ -506,9 +513,11 @@ const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
 
 const validatePayload = (payload: typeof Payload.Type) => {
   for (let i = 1; i < payload.newEvents.length; i++) {
-    if (EventSequenceNumber.isGreaterThanOrEqual(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
-      return unexpectedError(
-        `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+    if (
+      EventSequenceNumber.Client.isGreaterThanOrEqual(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)
+    ) {
+      return unknownError(
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
       )
     }
   }
@@ -520,9 +529,9 @@ const validateSyncState = (syncState: SyncState) => {
     const nextEvent = syncState.pending[i + 1]
     if (nextEvent === undefined) break // Reached end of chain
 
-    if (EventSequenceNumber.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum)) {
+    if (EventSequenceNumber.Client.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum)) {
       shouldNeverHappen(
-        `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
         {
           event,
           nextEvent,
@@ -535,7 +544,7 @@ const validateSyncState = (syncState: SyncState) => {
     if (globalIdHasIncreased) {
       if (nextEvent.seqNum.client !== 0) {
         shouldNeverHappen(
-          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.toString(nextEvent.seqNum)})`,
+          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.Client.toString(nextEvent.seqNum)})`,
           syncState.pending,
           {
             event,
@@ -545,7 +554,7 @@ const validateSyncState = (syncState: SyncState) => {
       }
     } else {
       // Otherwise, the parentSeqNum must be the same as the previous event's id
-      if (EventSequenceNumber.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
+      if (EventSequenceNumber.Client.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
         shouldNeverHappen('Events must be linked in a continuous chain via the parentSeqNum', syncState.pending, {
           event,
           nextEvent,
@@ -556,12 +565,14 @@ const validateSyncState = (syncState: SyncState) => {
 }
 
 const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
-  if (mergeResult._tag === 'unexpected-error' || mergeResult._tag === 'reject') return mergeResult
+  if (mergeResult._tag === 'unknown-error' || mergeResult._tag === 'reject') return mergeResult
 
   validateSyncState(mergeResult.newSyncState)
 
   // Ensure local head is always greater than or equal to upstream head
-  if (EventSequenceNumber.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)) {
+  if (
+    EventSequenceNumber.Client.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)
+  ) {
     shouldNeverHappen('Local head must be greater than or equal to upstream head', {
       localHead: mergeResult.newSyncState.localHead,
       upstreamHead: mergeResult.newSyncState.upstreamHead,
@@ -570,7 +581,7 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
 
   // Ensure new local head is greater than or equal to the previous local head
   if (
-    EventSequenceNumber.isGreaterThanOrEqual(
+    EventSequenceNumber.Client.isGreaterThanOrEqual(
       mergeResult.newSyncState.localHead,
       mergeResult.mergeContext.syncState.localHead,
     ) === false
@@ -583,7 +594,7 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
 
   // Ensure new upstream head is greater than or equal to the previous upstream head
   if (
-    EventSequenceNumber.isGreaterThanOrEqual(
+    EventSequenceNumber.Client.isGreaterThanOrEqual(
       mergeResult.newSyncState.upstreamHead,
       mergeResult.mergeContext.syncState.upstreamHead,
     ) === false

package/src/sync/transport-chunking.ts

@@ -0,0 +1,90 @@
+import { Chunk, Effect, Schema } from '@livestore/utils/effect'
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Configuration describing how to break a chunk into smaller payload-safe chunks.
+ */
+export interface ChunkingOptions<A> {
+  /** Maximum number of items that may appear in any emitted chunk. */
+  readonly maxItems: number
+  /** Maximum encoded byte size allowed for any emitted chunk. */
+  readonly maxBytes: number
+  /**
+   * Callback that produces a JSON-serialisable structure whose byte size should
+   * fit within {@link maxBytes}. This lets callers control framing overhead.
+   */
+  readonly encode: (items: ReadonlyArray<A>) => unknown
+  /**
+   * Optional custom measurement function. When provided it overrides the
+   * default {@link JSON.stringify}-based measurement logic.
+   */
+  readonly measure?: (items: ReadonlyArray<A>) => number
+}
+
+/**
+ * Derives a function that splits an input chunk into sub-chunks confined by
+ * both item count and encoded byte size limits. Designed for transports with
+ * strict frame caps (e.g. Cloudflare hibernated WebSockets).
+ */
+export class OversizeChunkItemError extends Schema.TaggedError<OversizeChunkItemError>()('OversizeChunkItemError', {
+  size: Schema.Number,
+  maxBytes: Schema.Number,
+}) {}
+
+export const splitChunkBySize =
+  <A>(options: ChunkingOptions<A>) =>
+  (chunk: Chunk.Chunk<A>): Effect.Effect<Chunk.Chunk<Chunk.Chunk<A>>, OversizeChunkItemError> =>
+    Effect.gen(function* () {
+      const maxItems = Math.max(1, options.maxItems)
+      const maxBytes = Math.max(1, options.maxBytes)
+      const encode = options.encode
+      const measure = options.measure
+
+      const computeSize = (items: ReadonlyArray<A>) => {
+        if (measure !== undefined) {
+          return measure(items)
+        }
+
+        const encoded = encode(items)
+        return textEncoder.encode(JSON.stringify(encoded)).byteLength
+      }
+
+      const items = Chunk.toReadonlyArray(chunk)
+      if (items.length === 0) {
+        return Chunk.fromIterable<Chunk.Chunk<A>>([])
+      }
+
+      const result: Array<Chunk.Chunk<A>> = []
+      let current: Array<A> = []
+
+      const flushCurrent = () => {
+        if (current.length > 0) {
+          result.push(Chunk.fromIterable(current))
+          current = []
+        }
+      }
+
+      for (const item of items) {
+        current.push(item)
+        const exceedsLimit = current.length > maxItems || computeSize(current) > maxBytes
+
+        if (exceedsLimit) {
+          // remove the item we just added and emit the previous chunk if it exists
+          const last = current.pop()!
+          flushCurrent()
+
+          if (last !== undefined) {
+            current = [last]
+            const singleItemTooLarge = computeSize(current) > maxBytes
+            if (singleItemTooLarge || current.length > maxItems) {
+              return yield* new OversizeChunkItemError({ size: computeSize([last]), maxBytes })
+            }
+          }
+        }
+      }
+
+      flushCurrent()
+
+      return Chunk.fromIterable(result)
+    })

package/src/sync/validate-push-payload.ts

@@ -1,21 +1,20 @@
 import { Effect } from '@livestore/utils/effect'
 
-import type { EventSequenceNumber, LiveStoreEvent } from '../schema/mod.ts'
-import { InvalidPushError } from './sync.ts'
+import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
+import { InvalidPushError, ServerAheadError } from './sync.ts'
 
 // TODO proper batch validation
 export const validatePushPayload = (
-  batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>,
-  currentEventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber,
+  batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+  currentEventSequenceNumber: EventSequenceNumber.Global.Type,
 ) =>
   Effect.gen(function* () {
     if (batch[0]!.seqNum <= currentEventSequenceNumber) {
       return yield* InvalidPushError.make({
-        reason: {
-          _tag: 'ServerAhead',
-          minimumExpectedNum: currentEventSequenceNumber + 1,
-          providedNum: batch[0]!.seqNum,
-        },
+        cause: new ServerAheadError({
+          minimumExpectedNum: EventSequenceNumber.Global.make(currentEventSequenceNumber + 1),
+          providedNum: EventSequenceNumber.Global.make(batch[0]!.seqNum),
+        }),
       })
     }
   })

package/src/testing/event-factory.ts

@@ -0,0 +1,131 @@
+/**
+ * Helpers for synthesizing LiveStore events in tests while keeping track of
+ * sequence numbers, parent pointers, and authoring client identity. Inspired
+ * by the effect-based schema utilities, the factory exposes a namespaced API
+ * where each event definition maps to a helper with `next`, `advanceTo`, and
+ * `setParent` functions that share a single sequence stream.
+ *
+ * @example
+ * ```ts
+ * import { EventFactory } from '@livestore/common/testing'
+ * import { events } from './schema'
+ *
+ * const eventFactory = EventFactory.makeFactory(events)({
+ *   client: EventFactory.clientIdentity('test-client'),
+ *   startSeq: 1,
+ *   initialParent: 'root',
+ * })
+ *
+ * const bootstrap = eventFactory.todoCreated.next({
+ *   id: 'todo-1',
+ *   text: 'write tests',
+ *   completed: false,
+ * })
+ *
+ * eventFactory.todoCreated.advanceTo(42)
+ * const branched = eventFactory.todoUpdated.next({
+ *   id: 'todo-1',
+ *   text: 'ship feature',
+ *   completed: true,
+ * })
+ * ```
+ */
+
+import { Schema } from '@livestore/utils/effect'
+
+import type { EventDef } from '../schema/EventDef/mod.ts'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber/mod.ts'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
+
+export interface ClientIdentity {
+  clientId: string
+  sessionId: string
+}
+
+export const clientIdentity = (label: string, session = `${label}-session`): ClientIdentity => ({
+  clientId: label,
+  sessionId: session,
+})
+
+export type SequenceValue = 'root' | number
+
+type EventFactoriesArgs<TDefs extends Record<string, EventDef.Any>> = {
+  [K in keyof TDefs]: Parameters<TDefs[K]>[0]
+}
+
+type EventFactories<TDefs extends Record<string, EventDef.Any>, TResult> = {
+  [K in keyof TDefs]: {
+    next: (args: EventFactoriesArgs<TDefs>[K]) => TResult
+    advanceTo: (seq: number, parent?: SequenceValue) => void
+    setParent: (parent: SequenceValue) => void
+    current: () => { seq: number; parent: SequenceValue }
+  }
+}
+
+export interface EventFactoriesConfig {
+  client: ClientIdentity
+  /**
+   * @default 1
+   */
+  startSeq?: number
+  /**
+   * @default 0 (root)
+   */
+  initialParent?: SequenceValue
+}
+
+export const makeFactory =
+  <TDefs extends Record<string, EventDef.Any>>(eventDefs: TDefs) =>
+  ({
+    client,
+    startSeq = 1,
+    initialParent = 'root',
+  }: EventFactoriesConfig): EventFactories<TDefs, LiveStoreEvent.Global.Encoded> => {
+    let nextSeq = startSeq
+    let parentRef: SequenceValue = initialParent
+
+    const advanceTo = (seq: number, parent: SequenceValue = 'root') => {
+      nextSeq = seq
+      parentRef = parent
+    }
+
+    const setParent = (parent: SequenceValue) => {
+      parentRef = parent
+    }
+
+    const current = () => ({ seq: nextSeq, parent: parentRef })
+
+    const factories: Partial<EventFactories<TDefs, LiveStoreEvent.Global.Encoded>> = {}
+
+    for (const [name, eventDef] of Object.entries(eventDefs) as [keyof TDefs, TDefs[keyof TDefs]][]) {
+      const next = (args: EventFactoriesArgs<TDefs>[typeof name]) => {
+        const decoded = eventDef(args)
+        const encodedArgs = Schema.encodeSync(eventDef.schema)(decoded.args)
+        const encoded = eventDef.encoded(encodedArgs)
+
+        const event = LiveStoreEvent.Global.Encoded.make({
+          name: encoded.name,
+          args: encoded.args,
+          seqNum: EventSequenceNumber.Global.make(nextSeq),
+          parentSeqNum:
+            parentRef === 'root' ? EventSequenceNumber.Client.ROOT.global : EventSequenceNumber.Global.make(parentRef),
+          clientId: client.clientId,
+          sessionId: client.sessionId,
+        })
+
+        parentRef = nextSeq
+        nextSeq = nextSeq + 1
+
+        return event
+      }
+
+      factories[name] = {
+        next,
+        advanceTo,
+        setParent,
+        current,
+      } as EventFactories<TDefs, LiveStoreEvent.Global.Encoded>[typeof name]
+    }
+
+    return factories as EventFactories<TDefs, LiveStoreEvent.Global.Encoded>
+  }

package/src/testing/mod.ts

@@ -0,0 +1 @@
+export * as EventFactory from './event-factory.ts'

package/src/version.ts

@@ -2,13 +2,23 @@
 // import packageJson from '../package.json' with { type: 'json' }
 // export const liveStoreVersion = packageJson.version
 
-export const liveStoreVersion = '0.4.0-dev.2' as const
+export const liveStoreVersion = '0.4.0-dev.21' as const
 
 /**
- * This version number is incremented whenever the internal storage format changes in a breaking way.
- * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
+ * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.
  *
- * While LiveStore is in beta, this might happen more frequently.
- * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
+ * Used to generate database file names (e.g., `eventlog@6.db`, `state@6.db`) across all client adapters.
+ *
+ * Bump required when:
+ * - Modifying eventlog system tables (eventlogMetaTable, syncStatusTable) in schema/state/sqlite/system-tables/eventlog-tables.ts
+ * - Changing columns, types, constraints, or indexes in eventlog tables
+ *
+ * Bump NOT required when:
+ * - Modifying STATE table schemas (auto-migrated via hash-based detection and rebuilt from eventlog)
+ * - Changing query patterns or client-side implementation details
+ *
+ * ⚠️  CRITICAL: Eventlog changes without bumping this version cause permanent data loss!
+ *
+ * Impact: Version changes trigger a "soft reset" - old data becomes inaccessible but remains on disk.
  */
-export const liveStoreStorageFormatVersion = 5
+export const liveStoreStorageFormatVersion = 6