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

package/dist/sync/syncstate.d.ts

@@ -1,6 +1,43 @@
 import { Schema } from '@livestore/utils/effect';
-import * as EventId from '../schema/EventId.js';
+import { UnexpectedError } from '../adapter-types.js';
 import * as MutationEvent from '../schema/MutationEvent.js';
+declare const SyncState_base: Schema.Class<SyncState, {
+    pending: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    rollbackTail: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    upstreamHead: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+    localHead: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+}, Schema.Struct.Encoded<{
+    pending: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    rollbackTail: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    upstreamHead: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+    localHead: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+}>, never, {
+    readonly pending: readonly MutationEvent.EncodedWithMeta[];
+} & {
+    readonly upstreamHead: {
+        readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+        readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+    };
+} & {
+    readonly localHead: {
+        readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+        readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+    };
+} & {
+    readonly rollbackTail: readonly MutationEvent.EncodedWithMeta[];
+}, {}, {}>;
 /**
  * SyncState represents the current sync state of a sync node relative to an upstream node.
  * Events flow from local to upstream, with each state maintaining its own event head.
@@ -36,35 +73,20 @@ import * as MutationEvent from '../schema/MutationEvent.js';
  * The `updateSyncState` function processes updates to the sync state based on incoming payloads,
  * handling cases such as upstream rebase, advance, local push, and rollback tail trimming.
  */
-export interface SyncState {
-    pending: ReadonlyArray<MutationEvent.EncodedWithMeta>;
-    rollbackTail: ReadonlyArray<MutationEvent.EncodedWithMeta>;
-    upstreamHead: EventId.EventId;
-    localHead: EventId.EventId;
+export declare class SyncState extends SyncState_base {
+    toJSON: () => any;
 }
-export declare const SyncState: Schema.Struct<{
-    pending: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
-    rollbackTail: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
-    upstreamHead: Schema.Struct<{
-        global: typeof Schema.Number;
-        local: typeof Schema.Number;
-    }>;
-    localHead: Schema.Struct<{
-        global: typeof Schema.Number;
-        local: typeof Schema.Number;
-    }>;
-}>;
 declare const PayloadUpstreamRebase_base: Schema.TaggedStruct<"upstream-rebase", {
     /** Rollback until this event in the rollback tail (inclusive). Starting from the end of the rollback tail. */
     rollbackUntil: Schema.Struct<{
-        global: typeof Schema.Number;
-        local: typeof Schema.Number;
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
     }>;
     newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
     /** Trim rollback tail up to this event (inclusive). */
     trimRollbackUntil: Schema.optional<Schema.Struct<{
-        global: typeof Schema.Number;
-        local: typeof Schema.Number;
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
     }>>;
 }>;
 export declare class PayloadUpstreamRebase extends PayloadUpstreamRebase_base {
@@ -73,8 +95,8 @@ declare const PayloadUpstreamAdvance_base: Schema.TaggedStruct<"upstream-advance
     newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
     /** Trim rollback tail up to this event (inclusive). */
     trimRollbackUntil: Schema.optional<Schema.Struct<{
-        global: typeof Schema.Number;
-        local: typeof Schema.Number;
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
     }>>;
 }>;
 export declare class PayloadUpstreamAdvance extends PayloadUpstreamAdvance_base {
@@ -89,28 +111,139 @@ export declare class Payload extends Payload_base {
 }
 export declare const PayloadUpstream: Schema.Union<[typeof PayloadUpstreamRebase, typeof PayloadUpstreamAdvance]>;
 export type PayloadUpstream = typeof PayloadUpstream.Type;
-export type UpdateResultAdvance = {
-    _tag: 'advance';
-    newSyncState: SyncState;
-    previousSyncState: SyncState;
+declare const UpdateContext_base: Schema.Class<UpdateContext, {
+    payload: typeof Payload;
+    syncState: typeof SyncState;
+}, Schema.Struct.Encoded<{
+    payload: typeof Payload;
+    syncState: typeof SyncState;
+}>, never, {
+    readonly payload: {
+        readonly _tag: "upstream-rebase";
+        readonly rollbackUntil: {
+            readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+            readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+        };
+        readonly newEvents: readonly MutationEvent.EncodedWithMeta[];
+        readonly trimRollbackUntil?: {
+            readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+            readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+        } | undefined;
+    } | {
+        readonly _tag: "upstream-advance";
+        readonly newEvents: readonly MutationEvent.EncodedWithMeta[];
+        readonly trimRollbackUntil?: {
+            readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+            readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+        } | undefined;
+    } | {
+        readonly _tag: "local-push";
+        readonly newEvents: readonly MutationEvent.EncodedWithMeta[];
+    };
+} & {
+    readonly syncState: SyncState;
+}, {}, {}>;
+/** Only used for debugging purposes */
+export declare class UpdateContext extends UpdateContext_base {
+    toJSON: () => any;
+}
+declare const UpdateResultAdvance_base: Schema.Class<UpdateResultAdvance, {
+    _tag: Schema.Literal<["advance"]>;
+    newSyncState: typeof SyncState;
+    /** Events which weren't pending before the update */
+    newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    updateContext: typeof UpdateContext;
+}, Schema.Struct.Encoded<{
+    _tag: Schema.Literal<["advance"]>;
+    newSyncState: typeof SyncState;
     /** Events which weren't pending before the update */
-    newEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>;
-};
-export type UpdateResultRebase = {
-    _tag: 'rebase';
-    newSyncState: SyncState;
-    previousSyncState: SyncState;
+    newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    updateContext: typeof UpdateContext;
+}>, never, {
+    readonly _tag: "advance";
+} & {
+    readonly newEvents: readonly MutationEvent.EncodedWithMeta[];
+} & {
+    readonly newSyncState: SyncState;
+} & {
+    readonly updateContext: UpdateContext;
+}, {}, {}>;
+export declare class UpdateResultAdvance extends UpdateResultAdvance_base {
+    toJSON: () => any;
+}
+declare const UpdateResultRebase_base: Schema.Class<UpdateResultRebase, {
+    _tag: Schema.Literal<["rebase"]>;
+    newSyncState: typeof SyncState;
+    /** Events which weren't pending before the update */
+    newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    eventsToRollback: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    updateContext: typeof UpdateContext;
+}, Schema.Struct.Encoded<{
+    _tag: Schema.Literal<["rebase"]>;
+    newSyncState: typeof SyncState;
     /** Events which weren't pending before the update */
-    newEvents: ReadonlyArray<MutationEvent.EncodedWithMeta>;
-    eventsToRollback: ReadonlyArray<MutationEvent.EncodedWithMeta>;
-};
-export type UpdateResultReject = {
-    _tag: 'reject';
-    previousSyncState: SyncState;
+    newEvents: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    eventsToRollback: Schema.Array$<typeof MutationEvent.EncodedWithMeta>;
+    updateContext: typeof UpdateContext;
+}>, never, {
+    readonly _tag: "rebase";
+} & {
+    readonly newEvents: readonly MutationEvent.EncodedWithMeta[];
+} & {
+    readonly newSyncState: SyncState;
+} & {
+    readonly updateContext: UpdateContext;
+} & {
+    readonly eventsToRollback: readonly MutationEvent.EncodedWithMeta[];
+}, {}, {}>;
+export declare class UpdateResultRebase extends UpdateResultRebase_base {
+    toJSON: () => any;
+}
+declare const UpdateResultReject_base: Schema.Class<UpdateResultReject, {
+    _tag: Schema.Literal<["reject"]>;
+    /** The minimum id that the new events must have */
+    expectedMinimumId: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+    updateContext: typeof UpdateContext;
+}, Schema.Struct.Encoded<{
+    _tag: Schema.Literal<["reject"]>;
     /** The minimum id that the new events must have */
-    expectedMinimumId: EventId.EventId;
-};
-export type UpdateResult = UpdateResultAdvance | UpdateResultRebase | UpdateResultReject;
+    expectedMinimumId: Schema.Struct<{
+        global: Schema.BrandSchema<number & import("effect/Brand").Brand<"GlobalEventId">, number, never>;
+        client: Schema.BrandSchema<number & import("effect/Brand").Brand<"ClientEventId">, number, never>;
+    }>;
+    updateContext: typeof UpdateContext;
+}>, never, {
+    readonly _tag: "reject";
+} & {
+    readonly updateContext: UpdateContext;
+} & {
+    readonly expectedMinimumId: {
+        readonly global: number & import("effect/Brand").Brand<"GlobalEventId">;
+        readonly client: number & import("effect/Brand").Brand<"ClientEventId">;
+    };
+}, {}, {}>;
+export declare class UpdateResultReject extends UpdateResultReject_base {
+    toJSON: () => any;
+}
+declare const UpdateResultUnexpectedError_base: Schema.Class<UpdateResultUnexpectedError, {
+    _tag: Schema.Literal<["unexpected-error"]>;
+    cause: typeof UnexpectedError;
+}, Schema.Struct.Encoded<{
+    _tag: Schema.Literal<["unexpected-error"]>;
+    cause: typeof UnexpectedError;
+}>, never, {
+    readonly _tag: "unexpected-error";
+} & {
+    readonly cause: UnexpectedError;
+}, {}, {}>;
+export declare class UpdateResultUnexpectedError extends UpdateResultUnexpectedError_base {
+}
+declare const UpdateResult_base: Schema.Union<[typeof UpdateResultAdvance, typeof UpdateResultRebase, typeof UpdateResultReject, typeof UpdateResultUnexpectedError]>;
+export declare class UpdateResult extends UpdateResult_base {
+}
 export declare const updateSyncState: ({ syncState, payload, isLocalEvent, isEqualEvent, ignoreLocalEvents, }: {
     syncState: SyncState;
     payload: typeof Payload.Type;
@@ -118,6 +251,6 @@ export declare const updateSyncState: ({ syncState, payload, isLocalEvent, isEqu
     isEqualEvent: (a: MutationEvent.EncodedWithMeta, b: MutationEvent.EncodedWithMeta) => boolean;
     /** This is used in the leader which should ignore local events when receiving an upstream-advance payload */
     ignoreLocalEvents?: boolean;
-}) => UpdateResult;
+}) => typeof UpdateResult.Type;
 export {};
 //# sourceMappingURL=syncstate.d.ts.map

package/dist/sync/syncstate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"syncstate.d.ts","sourceRoot":"","sources":["../../src/sync/syncstate.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAE/D,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAC/C,OAAO,KAAK,aAAa,MAAM,4BAA4B,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,eAAe,CAAC,CAAA;IACrD,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,eAAe,CAAC,CAAA;IAC1D,YAAY,EAAE,OAAO,CAAC,OAAO,CAAA;IAC7B,SAAS,EAAE,OAAO,CAAC,OAAO,CAAA;CAC3B;AAED,eAAO,MAAM,SAAS;;;;;;;;;;;EAKgB,CAAA;;IAGpC,8GAA8G;;;;;;IAG9G,uDAAuD;;;;;;AAJzD,qBAAa,qBAAsB,SAAQ,0BAMzC;CAAG;;;IAIH,uDAAuD;;;;;;AAFzD,qBAAa,sBAAuB,SAAQ,2BAI1C;CAAG;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;;AAEL,qBAAa,OAAQ,SAAQ,YAA6E;CAAG;AAE7G,eAAO,MAAM,eAAe,6EAA8D,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,SAAS,CAAA;IACf,YAAY,EAAE,SAAS,CAAA;IACvB,iBAAiB,EAAE,SAAS,CAAA;IAC5B,qDAAqD;IACrD,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,eAAe,CAAC,CAAA;CACxD,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,YAAY,EAAE,SAAS,CAAA;IACvB,iBAAiB,EAAE,SAAS,CAAA;IAC5B,qDAAqD;IACrD,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,eAAe,CAAC,CAAA;IACvD,gBAAgB,EAAE,aAAa,CAAC,aAAa,CAAC,eAAe,CAAC,CAAA;CAC/D,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,iBAAiB,EAAE,SAAS,CAAA;IAC5B,mDAAmD;IACnD,iBAAiB,EAAE,OAAO,CAAC,OAAO,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,kBAAkB,CAAA;AAExF,eAAO,MAAM,eAAe,2EAMzB;IACD,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,OAAO,OAAO,CAAC,IAAI,CAAA;IAC5B,YAAY,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,eAAe,KAAK,OAAO,CAAA;IAC/D,YAAY,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,EAAE,aAAa,CAAC,eAAe,KAAK,OAAO,CAAA;IAC7F,6GAA6G;IAC7G,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,KAAG,YA+MH,CAAA"}
+{"version":3,"file":"syncstate.d.ts","sourceRoot":"","sources":["../../src/sync/syncstate.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEtE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,aAAa,MAAM,4BAA4B,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,SAAU,SAAQ,cAK7B;IACA,MAAM,QAAO,GAAG,CAOf;CACF;;IAGC,8GAA8G;;;;;;IAG9G,uDAAuD;;;;;;AAJzD,qBAAa,qBAAsB,SAAQ,0BAMzC;CAAG;;;IAIH,uDAAuD;;;;;;AAFzD,qBAAa,sBAAuB,SAAQ,2BAI1C;CAAG;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;;AAEL,qBAAa,OAAQ,SAAQ,YAA6E;CAAG;AAE7G,eAAO,MAAM,eAAe,6EAA8D,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEzD,uCAAuC;AACvC,qBAAa,aAAc,SAAQ,kBAGjC;IACA,MAAM,QAAO,GAAG,CAoBf;CACF;;;;IAKC,qDAAqD;;;;;;IAArD,qDAAqD;;;;;;;;;;;;AAHvD,qBAAa,mBAAoB,SAAQ,wBAMvC;IACA,MAAM,QAAO,GAAG,CAOf;CACF;;;;IAKC,qDAAqD;;;;;;;IAArD,qDAAqD;;;;;;;;;;;;;;;AAHvD,qBAAa,kBAAmB,SAAQ,uBAOtC;IACA,MAAM,QAAO,GAAG,CAQf;CACF;;;IAIC,mDAAmD;;;;;;;;IAAnD,mDAAmD;;;;;;;;;;;;;;;;AAFrD,qBAAa,kBAAmB,SAAQ,uBAKtC;IACA,MAAM,QAAO,GAAG,CAMf;CACF;;;;;;;;;;;;AAED,qBAAa,2BAA4B,SAAQ,gCAK/C;CAAG;;AAEL,qBAAa,YAAa,SAAQ,iBAKjC;CAAG;AAQJ,eAAO,MAAM,eAAe,GAAI,wEAM7B;IACD,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,OAAO,OAAO,CAAC,IAAI,CAAA;IAC5B,YAAY,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,eAAe,KAAK,OAAO,CAAA;IAC/D,YAAY,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,EAAE,aAAa,CAAC,eAAe,KAAK,OAAO,CAAA;IAC7F,6GAA6G;IAC7G,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,KAAG,OAAO,YAAY,CAAC,IAiNvB,CAAA"}

package/dist/sync/syncstate.js

@@ -1,13 +1,58 @@
-import { shouldNeverHappen } from '@livestore/utils';
-import { ReadonlyArray, Schema } from '@livestore/utils/effect';
+import { casesHandled } from '@livestore/utils';
+import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect';
+import { UnexpectedError } from '../adapter-types.js';
 import * as EventId from '../schema/EventId.js';
 import * as MutationEvent from '../schema/MutationEvent.js';
-export const SyncState = Schema.Struct({
+/**
+ * SyncState represents the current sync state of a sync node relative to an upstream node.
+ * Events flow from local to upstream, with each state maintaining its own event head.
+ *
+ * Event Chain Structure:
+ * ```
+ *                 +-------------------------+------------------------+
+ *                 |      ROLLBACK TAIL      |     PENDING EVENTS     |
+ *                 +-------------------------+------------------------+
+ *                                         ▼                       ▼
+ *                                  Upstream Head             Local Head
+ *   Example:              (0,0), (0,1), (1,0)     (1,1), (1,2), (2,0)
+ * ```
+ *
+ * State:
+ * - **Pending Events**: Events awaiting acknowledgment from the upstream.
+ *   - Can be confirmed or rejected by the upstream.
+ *   - Subject to rebase if rejected.
+ * - **Rollback Tail**: Events that are kept around temporarily for potential rollback until confirmed by upstream.
+ *
+ * Payloads:
+ * - `PayloadUpstreamRebase`: Upstream has performed a rebase, so downstream must roll back to the specified event
+ *    and rebase the pending events on top of the new events.
+ * - `PayloadUpstreamAdvance`: Upstream has advanced, so downstream must rebase the pending events on top of the new events.
+ * - `PayloadUpstreamTrimRollbackTail`: Upstream has advanced, so downstream can trim the rollback tail.
+ * - `PayloadLocalPush`: Local push payload
+ *
+ * Invariants:
+ * 1. **Chain Continuity**: Each event must reference its immediate parent.
+ * 2. **Head Ordering**: Upstream Head ≤ Local Head.
+ * 3. **ID Sequence**: Must follow the pattern (1,0)→(1,1)→(1,2)→(2,0).
+ *
+ * The `updateSyncState` function processes updates to the sync state based on incoming payloads,
+ * handling cases such as upstream rebase, advance, local push, and rollback tail trimming.
+ */
+export class SyncState extends Schema.Class('SyncState')({
     pending: Schema.Array(MutationEvent.EncodedWithMeta),
     rollbackTail: Schema.Array(MutationEvent.EncodedWithMeta),
     upstreamHead: EventId.EventId,
     localHead: EventId.EventId,
-}).annotations({ title: 'SyncState' });
+}) {
+    toJSON = () => {
+        return {
+            pending: this.pending.map((e) => e.toJSON()),
+            rollbackTail: this.rollbackTail.map((e) => e.toJSON()),
+            upstreamHead: `(${this.upstreamHead.global},${this.upstreamHead.client})`,
+            localHead: `(${this.localHead.global},${this.localHead.client})`,
+        };
+    };
+}
 export class PayloadUpstreamRebase extends Schema.TaggedStruct('upstream-rebase', {
     /** Rollback until this event in the rollback tail (inclusive). Starting from the end of the rollback tail. */
     rollbackUntil: EventId.EventId,
@@ -29,6 +74,87 @@ export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
 export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {
 }
 export const PayloadUpstream = Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance);
+/** Only used for debugging purposes */
+export class UpdateContext extends Schema.Class('UpdateContext')({
+    payload: Payload,
+    syncState: SyncState,
+}) {
+    toJSON = () => {
+        const payload = Match.value(this.payload).pipe(Match.tag('local-push', () => ({
+            _tag: 'local-push',
+            newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+        })), Match.tag('upstream-advance', () => ({
+            _tag: 'upstream-advance',
+            newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+        })), Match.tag('upstream-rebase', () => ({
+            _tag: 'upstream-rebase',
+            newEvents: this.payload.newEvents.map((e) => e.toJSON()),
+        })), Match.exhaustive);
+        return {
+            payload,
+            syncState: this.syncState.toJSON(),
+        };
+    };
+}
+export class UpdateResultAdvance extends Schema.Class('UpdateResultAdvance')({
+    _tag: Schema.Literal('advance'),
+    newSyncState: SyncState,
+    /** Events which weren't pending before the update */
+    newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+    updateContext: UpdateContext,
+}) {
+    toJSON = () => {
+        return {
+            _tag: this._tag,
+            newSyncState: this.newSyncState.toJSON(),
+            newEvents: this.newEvents.map((e) => e.toJSON()),
+            updateContext: this.updateContext.toJSON(),
+        };
+    };
+}
+export class UpdateResultRebase extends Schema.Class('UpdateResultRebase')({
+    _tag: Schema.Literal('rebase'),
+    newSyncState: SyncState,
+    /** Events which weren't pending before the update */
+    newEvents: Schema.Array(MutationEvent.EncodedWithMeta),
+    eventsToRollback: Schema.Array(MutationEvent.EncodedWithMeta),
+    updateContext: UpdateContext,
+}) {
+    toJSON = () => {
+        return {
+            _tag: this._tag,
+            newSyncState: this.newSyncState.toJSON(),
+            newEvents: this.newEvents.map((e) => e.toJSON()),
+            eventsToRollback: this.eventsToRollback.map((e) => e.toJSON()),
+            updateContext: this.updateContext.toJSON(),
+        };
+    };
+}
+export class UpdateResultReject extends Schema.Class('UpdateResultReject')({
+    _tag: Schema.Literal('reject'),
+    /** The minimum id that the new events must have */
+    expectedMinimumId: EventId.EventId,
+    updateContext: UpdateContext,
+}) {
+    toJSON = () => {
+        return {
+            _tag: this._tag,
+            expectedMinimumId: `(${this.expectedMinimumId.global},${this.expectedMinimumId.client})`,
+            updateContext: this.updateContext.toJSON(),
+        };
+    };
+}
+export class UpdateResultUnexpectedError extends Schema.Class('UpdateResultUnexpectedError')({
+    _tag: Schema.Literal('unexpected-error'),
+    cause: UnexpectedError,
+}) {
+}
+export class UpdateResult extends Schema.Union(UpdateResultAdvance, UpdateResultRebase, UpdateResultReject, UpdateResultUnexpectedError) {
+}
+const unexpectedError = (cause) => UpdateResultUnexpectedError.make({
+    _tag: 'unexpected-error',
+    cause: new UnexpectedError({ cause }),
+});
 export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent, ignoreLocalEvents = false, }) => {
     const trimRollbackTail = (rollbackTail) => {
         const trimRollbackUntil = payload._tag === 'local-push' ? undefined : payload.trimRollbackUntil;
@@ -39,12 +165,13 @@ export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent
             return [];
         return rollbackTail.slice(index + 1);
     };
+    const updateContext = UpdateContext.make({ payload, syncState });
     switch (payload._tag) {
         case 'upstream-rebase': {
             // Find the index of the rollback event in the rollback tail
             const rollbackIndex = syncState.rollbackTail.findIndex((event) => EventId.isEqual(event.id, payload.rollbackUntil));
             if (rollbackIndex === -1) {
-                return shouldNeverHappen(`Rollback event not found in rollback tail. Rollback until: [${payload.rollbackUntil.global},${payload.rollbackUntil.local}]. Rollback tail: [${syncState.rollbackTail.map((e) => e.toString()).join(', ')}]`);
+                return unexpectedError(`Rollback event not found in rollback tail. Rollback until: [${payload.rollbackUntil.global},${payload.rollbackUntil.client}]. Rollback tail: [${syncState.rollbackTail.map((e) => e.toString()).join(', ')}]`);
             }
             const eventsToRollback = [...syncState.rollbackTail.slice(rollbackIndex), ...syncState.pending];
             // Get the last new event's ID as the new upstream head
@@ -55,39 +182,43 @@ export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent
                 baseEventId: newUpstreamHead,
                 isLocalEvent,
             });
-            return {
+            return UpdateResultRebase.make({
                 _tag: 'rebase',
-                newSyncState: {
+                newSyncState: new SyncState({
                     pending: rebasedPending,
                     rollbackTail: trimRollbackTail([...syncState.rollbackTail.slice(0, rollbackIndex), ...payload.newEvents]),
                     upstreamHead: newUpstreamHead,
                     localHead: rebasedPending.at(-1)?.id ?? newUpstreamHead,
-                },
-                previousSyncState: syncState,
-                newEvents: payload.newEvents,
+                }),
+                newEvents: [...payload.newEvents, ...rebasedPending],
                 eventsToRollback,
-            };
+                updateContext,
+            });
         }
         case 'upstream-advance': {
             if (payload.newEvents.length === 0) {
-                return {
+                return UpdateResultAdvance.make({
                     _tag: 'advance',
-                    newSyncState: {
+                    newSyncState: new SyncState({
                         pending: syncState.pending,
                         rollbackTail: trimRollbackTail(syncState.rollbackTail),
                         upstreamHead: syncState.upstreamHead,
                         localHead: syncState.localHead,
-                    },
-                    previousSyncState: syncState,
+                    }),
                     newEvents: [],
-                };
+                    updateContext,
+                });
             }
             // Validate that newEvents are sorted in ascending order by eventId
             for (let i = 1; i < payload.newEvents.length; i++) {
                 if (EventId.isGreaterThan(payload.newEvents[i - 1].id, payload.newEvents[i].id)) {
-                    return shouldNeverHappen('Events must be sorted in ascending order by eventId');
+                    return unexpectedError(`Events must be sorted in ascending order by eventId. Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`);
                 }
             }
+            // Validate that incoming events are larger than upstream head
+            if (EventId.isGreaterThan(syncState.upstreamHead, payload.newEvents[0].id)) {
+                return unexpectedError(`Incoming events must be greater than upstream head. Expected greater than: [${syncState.upstreamHead.global},${syncState.upstreamHead.client}]. Received: [${payload.newEvents.map((e) => `(${e.id.global},${e.id.client})`).join(', ')}]`);
+            }
             const newUpstreamHead = payload.newEvents.at(-1).id;
             const divergentPendingIndex = findDivergencePoint({
                 existingEvents: syncState.pending,
@@ -97,8 +228,8 @@ export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent
                 ignoreLocalEvents,
             });
             if (divergentPendingIndex === -1) {
-                const pendingEventIds = new Set(syncState.pending.map((e) => `${e.id.global},${e.id.local}`));
-                const newEvents = payload.newEvents.filter((e) => !pendingEventIds.has(`${e.id.global},${e.id.local}`));
+                const pendingEventIds = new Set(syncState.pending.map((e) => `${e.id.global},${e.id.client}`));
+                const newEvents = payload.newEvents.filter((e) => !pendingEventIds.has(`${e.id.global},${e.id.client}`));
                 // In the case where the incoming events are a subset of the pending events,
                 // we need to split the pending events into two groups:
                 // - pendingMatching: The pending events up to point where they match the incoming events
@@ -118,24 +249,24 @@ export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent
                 });
                 const seenEventIds = new Set();
                 const pendingAndNewEvents = [...pendingMatching, ...payload.newEvents].filter((event) => {
-                    const eventIdStr = `${event.id.global},${event.id.local}`;
+                    const eventIdStr = `${event.id.global},${event.id.client}`;
                     if (seenEventIds.has(eventIdStr)) {
                         return false;
                     }
                     seenEventIds.add(eventIdStr);
                     return true;
                 });
-                return {
+                return UpdateResultAdvance.make({
                     _tag: 'advance',
-                    newSyncState: {
+                    newSyncState: new SyncState({
                         pending: pendingRemaining,
                         rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...pendingAndNewEvents]),
                         upstreamHead: newUpstreamHead,
                         localHead: pendingRemaining.at(-1)?.id ?? newUpstreamHead,
-                    },
-                    previousSyncState: syncState,
+                    }),
                     newEvents,
-                };
+                    updateContext,
+                });
             }
             else {
                 const divergentPending = syncState.pending.slice(divergentPendingIndex);
@@ -151,63 +282,56 @@ export const updateSyncState = ({ syncState, payload, isLocalEvent, isEqualEvent
                     isLocalEvent,
                     ignoreLocalEvents,
                 });
-                return {
+                return UpdateResultRebase.make({
                     _tag: 'rebase',
-                    newSyncState: {
+                    newSyncState: new SyncState({
                         pending: rebasedPending,
                         rollbackTail: trimRollbackTail([...syncState.rollbackTail, ...payload.newEvents]),
                         upstreamHead: newUpstreamHead,
                         localHead: rebasedPending.at(-1).id,
-                    },
-                    previousSyncState: syncState,
+                    }),
                     newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
                     eventsToRollback: [...syncState.rollbackTail, ...divergentPending],
-                };
+                    updateContext,
+                });
             }
         }
         case 'local-push': {
             if (payload.newEvents.length === 0) {
-                return { _tag: 'advance', newSyncState: syncState, previousSyncState: syncState, newEvents: [] };
+                return UpdateResultAdvance.make({
+                    _tag: 'advance',
+                    newSyncState: syncState,
+                    newEvents: [],
+                    updateContext,
+                });
             }
             const newEventsFirst = payload.newEvents.at(0);
             const invalidEventId = EventId.isGreaterThan(newEventsFirst.id, syncState.localHead) === false;
             if (invalidEventId) {
                 const expectedMinimumId = EventId.nextPair(syncState.localHead, true).id;
-                return { _tag: 'reject', previousSyncState: syncState, expectedMinimumId };
+                return UpdateResultReject.make({
+                    _tag: 'reject',
+                    expectedMinimumId,
+                    updateContext,
+                });
             }
             else {
-                return {
+                return UpdateResultAdvance.make({
                     _tag: 'advance',
-                    newSyncState: {
+                    newSyncState: new SyncState({
                         pending: [...syncState.pending, ...payload.newEvents],
                         rollbackTail: syncState.rollbackTail,
                         upstreamHead: syncState.upstreamHead,
                         localHead: payload.newEvents.at(-1).id,
-                    },
-                    previousSyncState: syncState,
+                    }),
                     newEvents: payload.newEvents,
-                };
+                    updateContext,
+                });
             }
         }
-        // case 'upstream-trim-rollback-tail': {
-        //   // Find the index of the new rollback start in the rollback tail
-        //   const startIndex = syncState.rollbackTail.findIndex((event) => eventIdsEqual(event.id, payload.trimRollbackUntil))
-        //   if (startIndex === -1) {
-        //     return shouldNeverHappen('New rollback start event not found in rollback tail')
-        //   }
-        //   // Keep only the events from the start index onwards
-        //   const newRollbackTail = syncState.rollbackTail.slice(startIndex)
-        //   return {
-        //     _tag: 'advance',
-        //     syncState: {
-        //       pending: syncState.pending,
-        //       rollbackTail: newRollbackTail,
-        //       upstreamHead: syncState.upstreamHead,
-        //       localHead: syncState.localHead,
-        //     },
-        //     newEvents: [],
-        //   }
-        // }
+        default: {
+            casesHandled(payload);
+        }
     }
 };
 /**
@@ -245,4 +369,12 @@ const rebaseEvents = ({ events, baseEventId, isLocalEvent, }) => {
         return newEvent;
     });
 };
+/**
+ * TODO: Implement this
+ *
+ * In certain scenarios e.g. when the client session has a queue of upstream update results,
+ * 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 _flattenUpdateResults = (_updateResults) => { };
 //# sourceMappingURL=syncstate.js.map