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

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 { casesHandled } from '@livestore/utils'
+import { Effect, 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,40 +42,40 @@ 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),
   })
 }
 
 /**
  * This payload propagates a rebase from the upstream node
  */
-export class PayloadUpstreamRebase extends Schema.TaggedStruct('upstream-rebase', {
+export const PayloadUpstreamRebase = 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),
-}) {}
+export const PayloadUpstreamAdvance = Schema.TaggedStruct('upstream-advance', {
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
+})
 
-export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
-  newEvents: Schema.Array(LiveStoreEvent.EncodedWithMeta),
-}) {}
+export const PayloadLocalPush = Schema.TaggedStruct('local-push', {
+  newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
+})
 
-export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {}
+export const Payload = Schema.Union([PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush])
 
-export class PayloadUpstream extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance) {}
+export const PayloadUpstream = Schema.Union([PayloadUpstreamRebase, PayloadUpstreamAdvance])
 
 /** Only used for debugging purposes */
 export class MergeContext extends Schema.Class<MergeContext>('MergeContext')({
@@ -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,32 +147,22 @@ 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'),
-  message: Schema.String,
-}) {}
-
-export class MergeResult extends Schema.Union(
-  MergeResultAdvance,
-  MergeResultRebase,
-  MergeResultReject,
-  MergeResultUnexpectedError,
-) {}
+export const MergeResult = Schema.Union([MergeResultAdvance, MergeResultRebase, MergeResultReject])
 
 export const payloadFromMergeResult = (
-  mergeResult: typeof MergeResultAdvance.Type | typeof MergeResultRebase.Type,
+  mergeResult: MergeResultAdvance | MergeResultRebase,
 ): typeof PayloadUpstream.Type =>
   Match.value(mergeResult).pipe(
     Match.tag('advance', (result) => ({
@@ -187,15 +177,6 @@ export const payloadFromMergeResult = (
     Match.exhaustive,
   )
 
-const unexpectedError = (message: string): MergeResultUnexpectedError => {
-  if (LS_DEV) {
-    // biome-ignore lint/suspicious/noDebugger: debug
-    debugger
-  }
-
-  return MergeResultUnexpectedError.make({ _tag: 'unexpected-error', message })
-}
-
 // TODO Idea: call merge recursively through hierarchy levels
 /*
 Idea: have a map that maps from `globalEventSequenceNumber` to Array<ClientEvents>
@@ -203,22 +184,37 @@ The same applies to even further hierarchy levels
 
 TODO: possibly even keep the client events in a separate table in the client leader
 */
-export const merge = ({
+export const merge = Effect.fnUntraced(function* ({
   syncState,
   payload,
-  isClientEvent,
+  isClientOnlyEvent,
   isEqualEvent,
-  ignoreClientEvents = false,
+  ignoreClientOnlyEvents = false,
 }: {
   syncState: SyncState
   payload: typeof Payload.Type
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
-  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
-  /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
-  ignoreClientEvents?: boolean
-}): typeof MergeResult.Type => {
-  validateSyncState(syncState)
-  validatePayload(payload)
+  /**
+   * `LiveStoreEvent.Client.EncodedWithMeta` does not carry the event definition's
+   * `clientOnly` flag. The caller supplies this schema-aware predicate so `merge`
+   * can preserve the correct sequence-number shape when rebasing: client-only
+   * events advance the client component, synced events advance the global component.
+   */
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  /**
+   * Pending events are confirmed by comparing their logical encoded identity with
+   * upstream events. This is caller-supplied because comparing encoded args may
+   * require event-schema knowledge that the generic merge algorithm does not own.
+   * Implementations should ignore transport/runtime metadata.
+   */
+  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
+   */
+  ignoreClientOnlyEvents?: boolean
+}) {
+  yield* validateSyncState(syncState)
+  yield* validatePayload(payload)
 
   const mergeContext = MergeContext.make({ payload, syncState })
 
@@ -233,10 +229,10 @@ export const merge = ({
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
         baseEventSequenceNumber: newUpstreamHead,
-        isClientEvent,
+        isClientOnlyEvent,
       })
 
-      return validateMergeResult(
+      return yield* validateMergeResult(
         MergeResultRebase.make({
           _tag: 'rebase',
           newSyncState: new SyncState({
@@ -251,10 +247,10 @@ export const merge = ({
       )
     }
 
-    // #region upstream-advance
+    //#region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
@@ -271,20 +267,23 @@ 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) ===
+          true
+        ) {
+          return yield* Effect.dieDebugger(
+            `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) === true ||
+        EventSequenceNumber.Client.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum) === true
       ) {
-        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 yield* Effect.dieDebugger(
+          `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(', ')}]`,
         )
       }
 
@@ -294,8 +293,8 @@ export const merge = ({
         existingEvents: syncState.pending,
         incomingEvents: payload.newEvents,
         isEqualEvent,
-        isClientEvent,
-        ignoreClientEvents,
+        isClientOnlyEvent,
+        ignoreClientOnlyEvents,
       })
 
       // No divergent pending events, thus we can just advance (some of) the pending events
@@ -316,27 +315,27 @@ export const merge = ({
         const [pendingMatching, pendingRemaining] = ReadonlyArray.splitWhere(
           syncState.pending,
           (pendingEvent, index) => {
-            if (ignoreClientEvents && isClientEvent(pendingEvent)) {
+            if (ignoreClientOnlyEvents === true && isClientOnlyEvent(pendingEvent) === true) {
               clientIndexOffset++
               return false
             }
 
             const newEvent = payload.newEvents.at(index - clientIndexOffset)
-            if (!newEvent) {
+            if (newEvent == null) {
               return true
             }
-            return isEqualEvent(pendingEvent, newEvent) === false
+            return !isEqualEvent(pendingEvent, newEvent)
           },
         )
 
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
               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,
@@ -348,18 +347,18 @@ export const merge = ({
         const rebasedPending = rebaseEvents({
           events: divergentPending,
           baseEventSequenceNumber: newUpstreamHead,
-          isClientEvent,
+          isClientOnlyEvent: isClientOnlyEvent,
         })
 
         const divergentNewEventsIndex = findDivergencePoint({
           existingEvents: payload.newEvents,
           incomingEvents: syncState.pending,
           isEqualEvent,
-          isClientEvent,
-          ignoreClientEvents,
+          isClientOnlyEvent: isClientOnlyEvent,
+          ignoreClientOnlyEvents: ignoreClientOnlyEvents,
         })
 
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultRebase.make({
             _tag: 'rebase',
             newSyncState: new SyncState({
@@ -374,12 +373,12 @@ export const merge = ({
         )
       }
     }
-    // #endregion
+    //#endregion upstream-advance
 
     // This is the same as what's running in the sync backend
     case 'local-push': {
       if (payload.newEvents.length === 0) {
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: syncState,
@@ -391,15 +390,17 @@ export const merge = ({
       }
 
       const newEventsFirst = payload.newEvents.at(0)!
-      const invalidEventSequenceNumber =
-        EventSequenceNumber.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
+      const invalidEventSequenceNumber = !EventSequenceNumber.Client.isGreaterThan(
+        newEventsFirst.seqNum,
+        syncState.localHead,
+      )
 
-      if (invalidEventSequenceNumber) {
-        const expectedMinimumId = EventSequenceNumber.nextPair({
+      if (invalidEventSequenceNumber === true) {
+        const expectedMinimumId = EventSequenceNumber.Client.nextPair({
           seqNum: syncState.localHead,
-          isClient: true,
+          isClientOnly: true,
         }).seqNum
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultReject.make({
             _tag: 'reject',
             expectedMinimumId,
@@ -407,13 +408,21 @@ export const merge = ({
           }),
         )
       } else {
-        return validateMergeResult(
+        const nonClientOnlyEvents =
+          ignoreClientOnlyEvents === true
+            ? payload.newEvents.filter((event) => !isClientOnlyEvent(event))
+            : payload.newEvents
+        const newPending = [...syncState.pending, ...nonClientOnlyEvents]
+        const newLocalHead =
+          newPending.at(-1)?.seqNum ?? EventSequenceNumber.Client.max(syncState.localHead, syncState.upstreamHead)
+
+        return yield* 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: [],
@@ -423,11 +432,10 @@ export const merge = ({
       }
     }
 
-    default: {
-      casesHandled(payload)
-    }
+    default:
+      return casesHandled(payload)
   }
-}
+})
 
 /**
  * Gets the index relative to `existingEvents` where the divergence point is
@@ -437,57 +445,58 @@ export const findDivergencePoint = ({
   existingEvents,
   incomingEvents,
   isEqualEvent,
-  isClientEvent,
-  ignoreClientEvents,
+  isClientOnlyEvent,
+  ignoreClientOnlyEvents,
 }: {
-  existingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  incomingEvents: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  isEqualEvent: (a: LiveStoreEvent.EncodedWithMeta, b: LiveStoreEvent.EncodedWithMeta) => boolean
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
-  ignoreClientEvents: boolean
+  existingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  incomingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  ignoreClientOnlyEvents: boolean
 }): number => {
-  if (ignoreClientEvents) {
-    const filteredExistingEvents = existingEvents.filter((event) => !isClientEvent(event))
-    const divergencePointWithoutClientEvents = findDivergencePoint({
+  if (ignoreClientOnlyEvents === true) {
+    const filteredExistingEvents = existingEvents.filter((event) => !isClientOnlyEvent(event))
+    const divergencePointWithoutClientOnlyEvents = findDivergencePoint({
       existingEvents: filteredExistingEvents,
       incomingEvents,
       isEqualEvent,
-      isClientEvent,
-      ignoreClientEvents: false,
+      isClientOnlyEvent,
+      ignoreClientOnlyEvents: false,
     })
 
-    if (divergencePointWithoutClientEvents === -1) return -1
+    if (divergencePointWithoutClientOnlyEvents === -1) return -1
 
-    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientEvents]!.seqNum
+    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientOnlyEvents]!.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),
     )
   }
 
   return existingEvents.findIndex((existingEvent, index) => {
     const incomingEvent = incomingEvents[index]
     // return !incomingEvent || !isEqualEvent(existingEvent, incomingEvent)
-    return incomingEvent && !isEqualEvent(existingEvent, incomingEvent)
+    return incomingEvent !== undefined && isEqualEvent(existingEvent, incomingEvent) === false
   })
 }
 
 const rebaseEvents = ({
   events,
   baseEventSequenceNumber,
-  isClientEvent,
+  isClientOnlyEvent,
 }: {
-  events: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  baseEventSequenceNumber: EventSequenceNumber.EventSequenceNumber
-  isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
-}): ReadonlyArray<LiveStoreEvent.EncodedWithMeta> => {
+  events: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
+  baseEventSequenceNumber: EventSequenceNumber.Client.Composite
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+}): ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta> => {
   let prevEventSequenceNumber = baseEventSequenceNumber
   const rebaseGeneration = baseEventSequenceNumber.rebaseGeneration + 1
   return events.map((event) => {
-    const isClient = isClientEvent(event)
+    // Rebasing must preserve whether an event is client-only: client-only
+    // events become eN.1/eN.2, while synced events become eN+1.
     const newEvent = event.rebase({
       parentSeqNum: prevEventSequenceNumber,
-      isClient,
+      isClientOnly: isClientOnlyEvent(event),
       rebaseGeneration,
     })
     prevEventSequenceNumber = newEvent.seqNum
@@ -502,67 +511,73 @@ const rebaseEvents = ({
  * it could make sense to "flatten" update results into a single update result which the client session
  * can process more efficiently which avoids push-threshing
  */
-const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
+const _flattenMergeResults = (_updateResults: ReadonlyArray<typeof 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(', ')}]`,
-      )
+const validatePayload = (payload: typeof Payload.Type) =>
+  Effect.gen(function* () {
+    for (let i = 1; i < payload.newEvents.length; i++) {
+      if (
+        EventSequenceNumber.Client.isGreaterThanOrEqual(
+          payload.newEvents[i - 1]!.seqNum,
+          payload.newEvents[i]!.seqNum,
+        ) === true
+      ) {
+        return yield* Effect.dieDebugger(
+          `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
+        )
+      }
     }
-  }
-}
+  })
 
-const validateSyncState = (syncState: SyncState) => {
+const validateSyncState = Effect.fnUntraced(function* (syncState: SyncState) {
   for (let i = 0; i < syncState.pending.length; i++) {
     const event = syncState.pending[i]!
     const nextEvent = syncState.pending[i + 1]
     if (nextEvent === undefined) break // Reached end of chain
 
-    if (EventSequenceNumber.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(', ')}]`,
-        {
-          event,
-          nextEvent,
-        },
+    if (EventSequenceNumber.Client.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum) === true) {
+      return yield* Effect.dieDebugger(
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
+        { event, nextEvent },
       )
     }
 
     // If the global id has increased, then the client id must be 0
     const globalIdHasIncreased = nextEvent.seqNum.global > event.seqNum.global
-    if (globalIdHasIncreased) {
+    if (globalIdHasIncreased === true) {
       if (nextEvent.seqNum.client !== 0) {
-        shouldNeverHappen(
-          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.toString(nextEvent.seqNum)})`,
+        return yield* Effect.dieDebugger(
+          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.Client.toString(nextEvent.seqNum)})`,
           syncState.pending,
-          {
-            event,
-            nextEvent,
-          },
+          { event, nextEvent },
         )
       }
     } else {
       // Otherwise, the parentSeqNum must be the same as the previous event's id
-      if (EventSequenceNumber.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
-        shouldNeverHappen('Events must be linked in a continuous chain via the parentSeqNum', syncState.pending, {
-          event,
-          nextEvent,
-        })
+      if (EventSequenceNumber.Client.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
+        return yield* Effect.dieDebugger(
+          'Events must be linked in a continuous chain via the parentSeqNum',
+          syncState.pending,
+          { event, nextEvent },
+        )
       }
     }
   }
-}
+})
 
-const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
-  if (mergeResult._tag === 'unexpected-error' || mergeResult._tag === 'reject') return mergeResult
+const validateMergeResult = Effect.fnUntraced(function* (mergeResult: typeof MergeResult.Type) {
+  if (mergeResult._tag === 'reject') return mergeResult
 
-  validateSyncState(mergeResult.newSyncState)
+  yield* validateSyncState(mergeResult.newSyncState)
 
   // Ensure local head is always greater than or equal to upstream head
-  if (EventSequenceNumber.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)) {
-    shouldNeverHappen('Local head must be greater than or equal to upstream head', {
+  if (
+    EventSequenceNumber.Client.isGreaterThan(
+      mergeResult.newSyncState.upstreamHead,
+      mergeResult.newSyncState.localHead,
+    ) === true
+  ) {
+    return yield* Effect.dieDebugger('Local head must be greater than or equal to upstream head', {
       localHead: mergeResult.newSyncState.localHead,
       upstreamHead: mergeResult.newSyncState.upstreamHead,
     })
@@ -570,12 +585,12 @@ 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
   ) {
-    shouldNeverHappen('New local head must be greater than or equal to the previous local head', {
+    return yield* Effect.dieDebugger('New local head must be greater than or equal to the previous local head', {
       localHead: mergeResult.newSyncState.localHead,
       previousLocalHead: mergeResult.mergeContext.syncState.localHead,
     })
@@ -583,16 +598,16 @@ 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
   ) {
-    shouldNeverHappen('New upstream head must be greater than or equal to the previous upstream head', {
+    return yield* Effect.dieDebugger('New upstream head must be greater than or equal to the previous upstream head', {
       upstreamHead: mergeResult.newSyncState.upstreamHead,
       previousUpstreamHead: mergeResult.mergeContext.syncState.upstreamHead,
     })
   }
 
   return mergeResult
-}
+})