@livestore/common 0.4.0-dev.1 → 0.4.0-dev.11

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema, Stream } from '@livestore/utils/effect';
+import { Effect, Layer, Schema, Stream } from '@livestore/utils/effect';
 declare const UnexpectedError_base: Schema.TaggedErrorClass<UnexpectedError, "LiveStore.UnexpectedError", {
     readonly _tag: Schema.tag<"LiveStore.UnexpectedError">;
 } & {
@@ -8,14 +8,18 @@ declare const UnexpectedError_base: Schema.TaggedErrorClass<UnexpectedError, "Li
 }>;
 export declare class UnexpectedError extends UnexpectedError_base {
     static mapToUnexpectedError: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, UnexpectedError, R>;
+    static mapToUnexpectedErrorLayer: <A, E, R>(layer: Layer.Layer<A, E, R>) => Layer.Layer<A, UnexpectedError, R>;
     static mapToUnexpectedErrorStream: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<A, UnexpectedError, R>;
 }
-declare const SyncError_base: Schema.TaggedErrorClass<SyncError, "LiveStore.SyncError", {
-    readonly _tag: Schema.tag<"LiveStore.SyncError">;
+declare const MaterializerHashMismatchError_base: Schema.TaggedErrorClass<MaterializerHashMismatchError, "LiveStore.MaterializerHashMismatchError", {
+    readonly _tag: Schema.tag<"LiveStore.MaterializerHashMismatchError">;
 } & {
-    cause: typeof Schema.Defect;
+    eventName: typeof Schema.String;
+    note: Schema.optionalWith<typeof Schema.String, {
+        default: () => string;
+    }>;
 }>;
-export declare class SyncError extends SyncError_base {
+export declare class MaterializerHashMismatchError extends MaterializerHashMismatchError_base {
 }
 declare const IntentionalShutdownCause_base: Schema.TaggedErrorClass<IntentionalShutdownCause, "LiveStore.IntentionalShutdownCause", {
     readonly _tag: Schema.tag<"LiveStore.IntentionalShutdownCause">;
@@ -46,5 +50,43 @@ declare const SqliteError_base: Schema.TaggedErrorClass<SqliteError, "LiveStore.
 }>;
 export declare class SqliteError extends SqliteError_base {
 }
+declare const UnknownEventError_base: Schema.TaggedErrorClass<UnknownEventError, "LiveStore.UnknownEventError", {
+    readonly _tag: Schema.tag<"LiveStore.UnknownEventError">;
+} & {
+    event: Schema.SchemaClass<{
+        readonly clientId: string;
+        readonly sessionId: string;
+        readonly name: string;
+        readonly seqNum: {
+            readonly global: number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">;
+            readonly client: number & import("effect/Brand").Brand<"ClientEventSequenceNumber">;
+            readonly rebaseGeneration: number;
+        };
+        readonly args: any;
+    }, {
+        readonly clientId: string;
+        readonly sessionId: string;
+        readonly name: string;
+        readonly seqNum: {
+            readonly global: number;
+            readonly client: number;
+            readonly rebaseGeneration: number;
+        };
+        readonly args: any;
+    }, never>;
+    reason: Schema.Literal<["event-definition-missing", "materializer-missing"]>;
+    operation: typeof Schema.String;
+    note: Schema.optional<typeof Schema.String>;
+}>;
+export declare class UnknownEventError extends UnknownEventError_base {
+}
+declare const MaterializeError_base: Schema.TaggedErrorClass<MaterializeError, "LiveStore.MaterializeError", {
+    readonly _tag: Schema.tag<"LiveStore.MaterializeError">;
+} & {
+    cause: Schema.Union<[typeof MaterializerHashMismatchError, typeof SqliteError, typeof UnknownEventError]>;
+    note: Schema.optional<typeof Schema.String>;
+}>;
+export declare class MaterializeError extends MaterializeError_base {
+}
 export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;;;;;;;;AAEhE,qBAAa,eAAgB,SAAQ,oBAInC;IACA,MAAM,CAAC,oBAAoB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,0CAInE;IAEH,MAAM,CAAC,0BAA0B,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,0CAGzE;CACJ;;;;;;AAED,qBAAa,SAAU,SAAQ,cAE7B;CAAG;;;;;;AAEL,qBAAa,wBAAyB,SAAQ,6BAK7C;CAAG;;;;;;AAEJ,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;;;;;;;;IASH,6BAA6B;;IAI7B,iCAAiC;;;;AAXnC,qBAAa,WAAY,SAAQ,gBAc/B;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;;;;;;;;AAI9E,qBAAa,eAAgB,SAAQ,oBAInC;IACA,MAAM,CAAC,oBAAoB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,0CAInE;IAEH,MAAM,CAAC,yBAAyB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,wCAOrE;IAEH,MAAM,CAAC,0BAA0B,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,0CAGzE;CACJ;;;;;;;;;AAED,qBAAa,6BAA8B,SAAQ,kCAQlD;CAAG;;;;;;AAEJ,qBAAa,wBAAyB,SAAQ,6BAK7C;CAAG;;;;;;AAEJ,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;;;;;;;;IASH,6BAA6B;;IAI7B,iCAAiC;;;;AAXnC,qBAAa,WAAY,SAAQ,gBAc/B;CAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEL,qBAAa,iBAAkB,SAAQ,sBAKrC;CAAG;;;;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAGpC;CAAG"}

package/dist/errors.js

@@ -1,14 +1,21 @@
-import { Effect, Schema, Stream } from '@livestore/utils/effect';
+import { Cause, Effect, Layer, Schema, Stream } from '@livestore/utils/effect';
+import * as LiveStoreEvent from "./schema/LiveStoreEvent.js";
 export class UnexpectedError extends Schema.TaggedError()('LiveStore.UnexpectedError', {
     cause: Schema.Defect,
     note: Schema.optional(Schema.String),
     payload: Schema.optional(Schema.Any),
 }) {
     static mapToUnexpectedError = (effect) => effect.pipe(Effect.mapError((cause) => (Schema.is(UnexpectedError)(cause) ? cause : new UnexpectedError({ cause }))), Effect.catchAllDefect((cause) => new UnexpectedError({ cause })));
+    static mapToUnexpectedErrorLayer = (layer) => layer.pipe(Layer.catchAllCause((cause) => Cause.isFailType(cause) && Schema.is(UnexpectedError)(cause.error)
+        ? Layer.fail(cause.error)
+        : Layer.fail(new UnexpectedError({ cause: cause }))));
     static mapToUnexpectedErrorStream = (stream) => stream.pipe(Stream.mapError((cause) => (Schema.is(UnexpectedError)(cause) ? cause : new UnexpectedError({ cause }))));
 }
-export class SyncError extends Schema.TaggedError()('LiveStore.SyncError', {
-    cause: Schema.Defect,
+export class MaterializerHashMismatchError extends Schema.TaggedError()('LiveStore.MaterializerHashMismatchError', {
+    eventName: Schema.String,
+    note: Schema.optionalWith(Schema.String, {
+        default: () => 'Please make sure your event materializer is a pure function without side effects.',
+    }),
 }) {
 }
 export class IntentionalShutdownCause extends Schema.TaggedError()('LiveStore.IntentionalShutdownCause', {
@@ -33,4 +40,16 @@ export class SqliteError extends Schema.TaggedError()('LiveStore.SqliteError', {
     note: Schema.optional(Schema.String),
 }) {
 }
+export class UnknownEventError extends Schema.TaggedError()('LiveStore.UnknownEventError', {
+    event: LiveStoreEvent.AnyEncoded.pipe(Schema.pick('name', 'args', 'seqNum', 'clientId', 'sessionId')),
+    reason: Schema.Literal('event-definition-missing', 'materializer-missing'),
+    operation: Schema.String,
+    note: Schema.optional(Schema.String),
+}) {
+}
+export class MaterializeError extends Schema.TaggedError()('LiveStore.MaterializeError', {
+    cause: Schema.Union(MaterializerHashMismatchError, SqliteError, UnknownEventError),
+    note: Schema.optional(Schema.String),
+}) {
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhE,MAAM,OAAO,eAAgB,SAAQ,MAAM,CAAC,WAAW,EAAmB,CAAC,2BAA2B,EAAE;IACtG,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;CACrC,CAAC;IACA,MAAM,CAAC,oBAAoB,GAAG,CAAU,MAA8B,EAAE,EAAE,CACxE,MAAM,CAAC,IAAI,CACT,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EACxG,MAAM,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CACjE,CAAA;IAEH,MAAM,CAAC,0BAA0B,GAAG,CAAU,MAA8B,EAAE,EAAE,CAC9E,MAAM,CAAC,IAAI,CACT,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CACzG,CAAA;;AAGL,MAAM,OAAO,SAAU,SAAQ,MAAM,CAAC,WAAW,EAAa,CAAC,qBAAqB,EAAE;IACpF,KAAK,EAAE,MAAM,CAAC,MAAM;CACrB,CAAC;CAAG;AAEL,MAAM,OAAO,wBAAyB,SAAQ,MAAM,CAAC,WAAW,EAA4B,CAC1F,oCAAoC,EACpC;IACE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,QAAQ,CAAC;CACvF,CACF;CAAG;AAEJ,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,WAAW,EAAoB,CAAC,4BAA4B,EAAE;IACzG,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CAAC;CAAG;AAEL,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,WAAW,EAAe,CAAC,uBAAuB,EAAE;IAC1F,KAAK,EAAE,MAAM,CAAC,QAAQ,CACpB,MAAM,CAAC,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,MAAM;QAClB,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;KAC7G,CAAC,CACH;IACD,6BAA6B;IAC7B,wCAAwC;IACxC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CACrC,CAAC;CAAG"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/leader-thread/LeaderSyncProcessor.d.ts

@@ -1,7 +1,6 @@
 import type { Scope } from '@livestore/utils/effect';
 import { Effect } from '@livestore/utils/effect';
-import type { SqliteDb } from '../adapter-types.ts';
-import { UnexpectedError } from '../adapter-types.ts';
+import { type SqliteDb, UnexpectedError } from '../adapter-types.ts';
 import type { LiveStoreSchema } from '../schema/mod.ts';
 import * as SyncState from '../sync/syncstate.ts';
 import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.ts';
@@ -35,7 +34,7 @@ import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.ts
  *
  * See ClientSessionSyncProcessor for how the leader and session sync processors are similar/different.
  */
-export declare const makeLeaderSyncProcessor: ({ schema, dbState, initialBlockingSyncContext, initialSyncState, onError, params, testing, }: {
+export declare const makeLeaderSyncProcessor: ({ schema, dbState, initialBlockingSyncContext, initialSyncState, onError, livePull, params, testing, }: {
     schema: LiveStoreSchema;
     dbState: SqliteDb;
     initialBlockingSyncContext: InitialBlockingSyncContext;
@@ -52,6 +51,11 @@ export declare const makeLeaderSyncProcessor: ({ schema, dbState, initialBlockin
          */
         backendPushBatchSize?: number;
     };
+    /**
+     * Whether the sync backend should reactively pull new events from the sync backend
+     * When `false`, the sync processor will only do an initial pull
+     */
+    livePull: boolean;
     testing: {
         delays?: {
             localPushProcessing?: Effect.Effect<void>;

package/dist/leader-thread/LeaderSyncProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LeaderSyncProcessor.d.ts","sourceRoot":"","sources":["../../src/leader-thread/LeaderSyncProcessor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAuB,KAAK,EAAU,MAAM,yBAAyB,CAAA;AACjF,OAAO,EAGL,MAAM,EAWP,MAAM,yBAAyB,CAAA;AAGhC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAa,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAGvD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AAIjD,OAAO,KAAK,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAQjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GAAI,8FAQrC;IACD,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,QAAQ,CAAA;IACjB,0BAA0B,EAAE,0BAA0B,CAAA;IACtD,sFAAsF;IACtF,gBAAgB,EAAE,SAAS,CAAC,SAAS,CAAA;IACrC,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC9B,MAAM,EAAE;QACN;;WAEG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B;;WAEG;QACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAC9B,CAAA;IACD,OAAO,EAAE;QACP,MAAM,CAAC,EAAE;YACP,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;SAC1C,CAAA;KACF,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,EAAE,KAAK,CAAC,KAAK,CA0O/D,CAAA"}
+{"version":3,"file":"LeaderSyncProcessor.d.ts","sourceRoot":"","sources":["../../src/leader-thread/LeaderSyncProcessor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAuB,KAAK,EAAU,MAAM,yBAAyB,CAAA;AACjF,OAAO,EAKL,MAAM,EAYP,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAGL,KAAK,QAAQ,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AASvD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA;AAIjD,OAAO,KAAK,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAQjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GAAI,wGASrC;IACD,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,QAAQ,CAAA;IACjB,0BAA0B,EAAE,0BAA0B,CAAA;IACtD,sFAAsF;IACtF,gBAAgB,EAAE,SAAS,CAAC,SAAS,CAAA;IACrC,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC9B,MAAM,EAAE;QACN;;WAEG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B;;WAEG;QACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAC9B,CAAA;IACD;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE;QACP,MAAM,CAAC,EAAE;YACP,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;SAC1C,CAAA;KACF,CAAA;CACF,KAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,EAAE,KAAK,CAAC,KAAK,CAuR/D,CAAA"}

package/dist/leader-thread/LeaderSyncProcessor.js

@@ -1,9 +1,9 @@
 import { casesHandled, isNotUndefined, LS_DEV, shouldNeverHappen, TRACE_VERBOSE } from '@livestore/utils';
-import { BucketQueue, Deferred, Effect, Exit, FiberHandle, Option, OtelTracer, pipe, Queue, ReadonlyArray, Stream, Subscribable, SubscriptionRef, } from '@livestore/utils/effect';
-import { SyncError, UnexpectedError } from "../adapter-types.js";
+import { BucketQueue, Cause, Deferred, Duration, Effect, Exit, FiberHandle, Layer, Option, OtelTracer, Queue, ReadonlyArray, Schedule, Stream, Subscribable, SubscriptionRef, } from '@livestore/utils/effect';
+import { UnexpectedError, } from "../adapter-types.js";
 import { makeMaterializerHash } from "../materializer-helper.js";
-import { EventSequenceNumber, getEventDef, LiveStoreEvent, SystemTables } from "../schema/mod.js";
-import { LeaderAheadError } from "../sync/sync.js";
+import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from "../schema/mod.js";
+import { LeaderAheadError, } from "../sync/sync.js";
 import * as SyncState from "../sync/syncstate.js";
 import { sql } from "../util.js";
 import * as Eventlog from "./eventlog.js";
@@ -39,15 +39,12 @@ import { LeaderThreadCtx } from "./types.js";
  *
  * See ClientSessionSyncProcessor for how the leader and session sync processors are similar/different.
  */
-export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncContext, initialSyncState, onError, params, testing, }) => Effect.gen(function* () {
+export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncContext, initialSyncState, onError, livePull, params, testing, }) => Effect.gen(function* () {
     const syncBackendPushQueue = yield* BucketQueue.make();
     const localPushBatchSize = params.localPushBatchSize ?? 1;
     const backendPushBatchSize = params.backendPushBatchSize ?? 2;
     const syncStateSref = yield* SubscriptionRef.make(undefined);
-    const isClientEvent = (eventEncoded) => {
-        const { eventDef } = getEventDef(schema, eventEncoded.name);
-        return eventDef.options.clientOnly;
-    };
+    const isClientEvent = (eventEncoded) => schema.eventsDefsMap.get(eventEncoded.name)?.options.clientOnly ?? false;
     const connectedClientSessionPullQueues = yield* makePullQueueSet;
     // This context depends on data from `boot`, we should find a better implementation to avoid this ref indirection.
     const ctxRef = {
@@ -98,13 +95,30 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
         const syncState = yield* syncStateSref;
         if (syncState === undefined)
             return shouldNeverHappen('Not initialized');
-        const { eventDef } = getEventDef(schema, name);
+        const resolution = yield* resolveEventDef(schema, {
+            operation: '@livestore/common:LeaderSyncProcessor:pushPartial',
+            event: {
+                name,
+                args,
+                clientId,
+                sessionId,
+                seqNum: syncState.localHead,
+            },
+        }).pipe(UnexpectedError.mapToUnexpectedError);
+        if (resolution._tag === 'unknown') {
+            // Ignore partial pushes for unrecognised events – they are still
+            // persisted server-side once a schema update ships.
+            return;
+        }
         const eventEncoded = new LiveStoreEvent.EncodedWithMeta({
             name,
             args,
             clientId,
             sessionId,
-            ...EventSequenceNumber.nextPair({ seqNum: syncState.localHead, isClient: eventDef.options.clientOnly }),
+            ...EventSequenceNumber.nextPair({
+                seqNum: syncState.localHead,
+                isClient: resolution.eventDef.options.clientOnly,
+            }),
         });
         yield* push([eventEncoded]);
     }).pipe(Effect.catchTag('LeaderAheadError', Effect.orDie));
@@ -127,18 +141,23 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
             const globalPendingEvents = initialSyncState.pending
                 // Don't sync clientOnly events
                 .filter((eventEncoded) => {
-                const { eventDef } = getEventDef(schema, eventEncoded.name);
-                return eventDef.options.clientOnly === false;
+                const eventDef = schema.eventsDefsMap.get(eventEncoded.name);
+                return eventDef === undefined ? true : eventDef.options.clientOnly === false;
             });
             if (globalPendingEvents.length > 0) {
                 yield* BucketQueue.offerAll(syncBackendPushQueue, globalPendingEvents);
             }
         }
-        const shutdownOnError = (cause) => Effect.gen(function* () {
-            if (onError === 'shutdown') {
-                yield* shutdownChannel.send(UnexpectedError.make({ cause }));
-                yield* Effect.die(cause);
+        const maybeShutdownOnError = (cause) => Effect.gen(function* () {
+            if (onError === 'ignore') {
+                if (LS_DEV) {
+                    yield* Effect.logDebug(`Ignoring sync error (${cause._tag === 'Fail' ? cause.error._tag : cause._tag})`, Cause.pretty(cause));
+                }
+                return;
             }
+            const errorToSend = Cause.isFailType(cause) ? cause.error : UnexpectedError.make({ cause });
+            yield* shutdownChannel.send(errorToSend).pipe(Effect.orDie);
+            return yield* Effect.die(cause);
         });
         yield* backgroundApplyLocalPushes({
             localPushesLatch,
@@ -154,17 +173,16 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
             testing: {
                 delay: testing?.delays?.localPushProcessing,
             },
-        }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError), Effect.forkScoped);
+        }).pipe(Effect.catchAllCause(maybeShutdownOnError), Effect.forkScoped);
         const backendPushingFiberHandle = yield* FiberHandle.make();
         const backendPushingEffect = backgroundBackendPushing({
             syncBackendPushQueue,
             otelSpan,
             devtoolsLatch: ctxRef.current?.devtoolsLatch,
             backendPushBatchSize,
-        }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError));
+        }).pipe(Effect.catchAllCause(maybeShutdownOnError));
         yield* FiberHandle.run(backendPushingFiberHandle, backendPushingEffect);
         yield* backgroundBackendPulling({
-            initialBackendHead: initialSyncState.upstreamHead.global,
             isClientEvent,
             restartBackendPushing: (filteredRebasedPending) => Effect.gen(function* () {
                 // Stop current pushing fiber
@@ -178,13 +196,20 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
             syncStateSref,
             localPushesLatch,
             pullLatch,
+            livePull,
             dbState,
             otelSpan,
             initialBlockingSyncContext,
             devtoolsLatch: ctxRef.current?.devtoolsLatch,
             connectedClientSessionPullQueues,
             advancePushHead,
-        }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError), Effect.forkScoped);
+        }).pipe(Effect.retry({
+            // We want to retry pulling if we've lost connection to the sync backend
+            while: (cause) => cause._tag === 'IsOfflineError',
+        }), Effect.catchAllCause(maybeShutdownOnError), 
+        // Needed to avoid `Fiber terminated with an unhandled error` logs which seem to happen because of the `Effect.retry` above.
+        // This might be a bug in Effect. Only seems to happen in the browser.
+        Effect.provide(Layer.setUnhandledErrorLogLevel(Option.none())), Effect.forkScoped);
         return { initialLeaderHead: initialSyncState.localHead };
     }).pipe(Effect.withSpanScoped('@livestore/common:LeaderSyncProcessor:boot'));
     const pull = ({ cursor }) => Effect.gen(function* () {
@@ -243,13 +268,26 @@ const backgroundApplyLocalPushes = ({ localPushesLatch, localPushesQueue, pullLa
         const currentRebaseGeneration = syncState.localHead.rebaseGeneration;
         // Since the rebase generation might have changed since enqueuing, we need to filter out items with older generation
         // It's important that we filter after we got localPushesLatch, otherwise we might filter with the old generation
-        const [newEvents, deferreds] = pipe(batchItems, ReadonlyArray.filter(([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration === currentRebaseGeneration), ReadonlyArray.unzip);
-        if (newEvents.length === 0) {
-            // console.log('dropping old-gen batch', currentLocalPushGenerationRef.current)
-            // Allow the backend pulling to start
+        const [droppedItems, filteredItems] = ReadonlyArray.partition(batchItems, ([eventEncoded]) => eventEncoded.seqNum.rebaseGeneration >= currentRebaseGeneration);
+        if (droppedItems.length > 0) {
+            otelSpan?.addEvent(`push:drop-old-generation`, {
+                droppedCount: droppedItems.length,
+                currentRebaseGeneration,
+            });
+            /**
+             * Dropped pushes may still have a deferred awaiting completion.
+             * Fail it so the caller learns the leader advanced and resubmits with the updated generation.
+             */
+            yield* Effect.forEach(droppedItems.filter((item) => item[1] !== undefined), ([eventEncoded, deferred]) => Deferred.fail(deferred, LeaderAheadError.make({
+                minimumExpectedNum: syncState.localHead,
+                providedNum: eventEncoded.seqNum,
+            })));
+        }
+        if (filteredItems.length === 0) {
             yield* pullLatch.open;
             continue;
         }
+        const [newEvents, deferreds] = ReadonlyArray.unzip(filteredItems);
         const mergeResult = SyncState.merge({
             syncState,
             payload: { _tag: 'local-push', newEvents },
@@ -262,7 +300,7 @@ const backgroundApplyLocalPushes = ({ localPushesLatch, localPushesQueue, pullLa
                     batchSize: newEvents.length,
                     newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
                 });
-                return yield* new SyncError({ cause: mergeResult.message });
+                return yield* new UnexpectedError({ cause: mergeResult.message });
             }
             case 'rebase': {
                 return shouldNeverHappen('The leader thread should never have to rebase due to a local push');
@@ -314,8 +352,8 @@ const backgroundApplyLocalPushes = ({ localPushesLatch, localPushesQueue, pullLa
         });
         // Don't sync clientOnly events
         const filteredBatch = mergeResult.newEvents.filter((eventEncoded) => {
-            const { eventDef } = getEventDef(schema, eventEncoded.name);
-            return eventDef.options.clientOnly === false;
+            const eventDef = schema.eventsDefsMap.get(eventEncoded.name);
+            return eventDef === undefined ? true : eventDef.options.clientOnly === false;
         });
         yield* BucketQueue.offerAll(syncBackendPushQueue, filteredBatch);
         yield* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds });
@@ -348,12 +386,12 @@ const materializeEventsBatch = ({ batchItems, deferreds }) => Effect.gen(functio
     dbEventlog.execute('COMMIT', undefined); // Commit the transaction
 }).pipe(Effect.uninterruptible, Effect.scoped, Effect.withSpan('@livestore/common:LeaderSyncProcessor:materializeEventItems', {
     attributes: { batchSize: batchItems.length },
-}), Effect.tapCauseLogPretty, UnexpectedError.mapToUnexpectedError);
-const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBackendPushing, otelSpan, dbState, syncStateSref, localPushesLatch, pullLatch, devtoolsLatch, initialBlockingSyncContext, connectedClientSessionPullQueues, advancePushHead, }) => Effect.gen(function* () {
+}), Effect.tapCauseLogPretty);
+const backgroundBackendPulling = ({ isClientEvent, restartBackendPushing, otelSpan, dbState, syncStateSref, localPushesLatch, livePull, pullLatch, devtoolsLatch, initialBlockingSyncContext, connectedClientSessionPullQueues, advancePushHead, }) => Effect.gen(function* () {
     const { syncBackend, dbState: db, dbEventlog, schema } = yield* LeaderThreadCtx;
     if (syncBackend === undefined)
         return;
-    const onNewPullChunk = (newEvents, remaining) => Effect.gen(function* () {
+    const onNewPullChunk = (newEvents, pageInfo) => Effect.gen(function* () {
         if (newEvents.length === 0)
             return;
         if (devtoolsLatch !== undefined) {
@@ -381,7 +419,7 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
                 newEventsCount: newEvents.length,
                 newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
             });
-            return yield* new SyncError({ cause: mergeResult.message });
+            return yield* new UnexpectedError({ cause: mergeResult.message });
         }
         const newBackendHead = newEvents.at(-1).seqNum;
         Eventlog.updateBackendHead(dbEventlog, newBackendHead);
@@ -393,8 +431,8 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
                 mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
             });
             const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
-                const { eventDef } = getEventDef(schema, event.name);
-                return eventDef.options.clientOnly === false;
+                const eventDef = schema.eventsDefsMap.get(event.name);
+                return eventDef === undefined ? true : eventDef.options.clientOnly === false;
             });
             yield* restartBackendPushing(globalRebasedPendingEvents);
             if (mergeResult.rollbackEvents.length > 0) {
@@ -414,6 +452,12 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
                 newEventsCount: newEvents.length,
                 mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
             });
+            // Ensure push fiber is active after advance by restarting with current pending (non-client) events
+            const globalPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
+                const eventDef = schema.eventsDefsMap.get(event.name);
+                return eventDef === undefined ? true : eventDef.options.clientOnly === false;
+            });
+            yield* restartBackendPushing(globalPendingEvents);
             yield* connectedClientSessionPullQueues.offer({
                 payload: SyncState.payloadFromMergeResult(mergeResult),
                 leaderHead: mergeResult.newSyncState.localHead,
@@ -422,7 +466,7 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
                 // `mergeResult.confirmedEvents` don't contain the correct sync metadata, so we need to use
                 // `newEvents` instead which we filter via `mergeResult.confirmedEvents`
                 const confirmedNewEvents = newEvents.filter((event) => mergeResult.confirmedEvents.some((confirmedEvent) => EventSequenceNumber.isEqual(event.seqNum, confirmedEvent.seqNum)));
-                yield* Eventlog.updateSyncMetadata(confirmedNewEvents);
+                yield* Eventlog.updateSyncMetadata(confirmedNewEvents).pipe(UnexpectedError.mapToUnexpectedError);
             }
         }
         // Removes the changeset rows which are no longer needed as we'll never have to rollback beyond this point
@@ -431,15 +475,18 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
         yield* materializeEventsBatch({ batchItems: mergeResult.newEvents, deferreds: undefined });
         yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState);
         // Allow local pushes to be processed again
-        if (remaining === 0) {
+        if (pageInfo._tag === 'NoMore') {
             yield* localPushesLatch.open;
         }
     });
-    const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo({ remoteHead: initialBackendHead });
+    const syncState = yield* syncStateSref;
+    if (syncState === undefined)
+        return shouldNeverHappen('Not initialized');
+    const cursorInfo = yield* Eventlog.getSyncBackendCursorInfo({ remoteHead: syncState.upstreamHead.global });
     const hashMaterializerResult = makeMaterializerHash({ schema, dbState });
-    yield* syncBackend.pull(cursorInfo).pipe(
+    yield* syncBackend.pull(cursorInfo, { live: livePull }).pipe(
     // TODO only take from queue while connected
-    Stream.tap(({ batch, remaining }) => Effect.gen(function* () {
+    Stream.tap(({ batch, pageInfo }) => Effect.gen(function* () {
         // yield* Effect.spanEvent('batch', {
         //   attributes: {
         //     batchSize: batch.length,
@@ -456,9 +503,11 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
             // This is a bug and needs to be fixed https://github.com/livestorejs/livestore/issues/503#issuecomment-3114533165
             materializerHashLeader: hashMaterializerResult(LiveStoreEvent.encodedFromGlobal(_.eventEncoded)),
             materializerHashSession: Option.none(),
-        })), remaining);
-        yield* initialBlockingSyncContext.update({ processed: batch.length, remaining });
+        })), pageInfo);
+        yield* initialBlockingSyncContext.update({ processed: batch.length, pageInfo });
     })), Stream.runDrain, Effect.interruptible);
+    // Should only ever happen when livePull is false
+    yield* Effect.logDebug('backend-pulling finished', { livePull });
 }).pipe(Effect.withSpan('@livestore/common:LeaderSyncProcessor:backend-pulling'));
 const backgroundBackendPushing = ({ syncBackendPushQueue, otelSpan, devtoolsLatch, backendPushBatchSize, }) => Effect.gen(function* () {
     const { syncBackend } = yield* LeaderThreadCtx;
@@ -475,16 +524,39 @@ const backgroundBackendPushing = ({ syncBackendPushQueue, otelSpan, devtoolsLatc
             batchSize: queueItems.length,
             batch: TRACE_VERBOSE ? JSON.stringify(queueItems) : undefined,
         });
-        // TODO handle push errors (should only happen during concurrent pull+push)
-        const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.either);
-        if (pushResult._tag === 'Left') {
-            if (LS_DEV) {
-                yield* Effect.logDebug('handled backend-push-error', { error: pushResult.left.toString() });
+        // Push with declarative retry/backoff using Effect schedules
+        // - Exponential backoff starting at 1s and doubling (1s, 2s, 4s, 8s, 16s, 30s ...)
+        // - Delay clamped at 30s (continues retrying at 30s)
+        // - Resets automatically after successful push
+        // TODO(metrics): expose counters/gauges for retry attempts and queue health via devtools/metrics
+        // Only retry for transient UnexpectedError cases
+        const isRetryable = (err) => err._tag === 'InvalidPushError' && err.cause._tag === 'LiveStore.UnexpectedError';
+        // Input: InvalidPushError | IsOfflineError, Output: Duration
+        const retrySchedule = Schedule.exponential(Duration.seconds(1)).pipe(Schedule.andThenEither(Schedule.spaced(Duration.seconds(30))), // clamp at 30 second intervals
+        Schedule.compose(Schedule.elapsed), Schedule.whileInput(isRetryable));
+        yield* Effect.gen(function* () {
+            const iteration = yield* Schedule.CurrentIterationMetadata;
+            const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.either);
+            const retries = iteration.recurrence;
+            if (retries > 0 && pushResult._tag === 'Right') {
+                otelSpan?.addEvent('backend-push-retry-success', { retries, batchSize: queueItems.length });
             }
-            otelSpan?.addEvent('backend-push-error', { error: pushResult.left.toString() });
-            // wait for interrupt caused by background pulling which will then restart pushing
-            return yield* Effect.never;
-        }
+            if (pushResult._tag === 'Left') {
+                otelSpan?.addEvent('backend-push-error', {
+                    error: pushResult.left.toString(),
+                    retries,
+                    batchSize: queueItems.length,
+                });
+                const error = pushResult.left;
+                if (error._tag === 'IsOfflineError' ||
+                    (error._tag === 'InvalidPushError' && error.cause._tag === 'ServerAheadError')) {
+                    // It's a core part of the sync protocol that the sync backend will emit a new pull chunk alongside the ServerAheadError
+                    yield* Effect.logDebug('handled backend-push-error (waiting for interupt caused by pull)', { error });
+                    return yield* Effect.never;
+                }
+                return yield* error;
+            }
+        }).pipe(Effect.retry(retrySchedule));
     }
 }).pipe(Effect.interruptible, Effect.withSpan('@livestore/common:LeaderSyncProcessor:backend-pushing'));
 const trimChangesetRows = (db, newHead) => {
@@ -575,14 +647,25 @@ const makePullQueueSet = Effect.gen(function* () {
         offer,
     };
 });
+/**
+ * Validate a client-provided batch before it is admitted to the leader queue.
+ * Ensures the numbers form a strictly increasing chain and that the first
+ * event sits ahead of the current push head.
+ */
 const validatePushBatch = (batch, pushHead) => Effect.gen(function* () {
     if (batch.length === 0) {
         return;
     }
-    // Make sure batch is monotonically increasing
+    // Example: session A already enqueued e1…e6 while session B (same client, different
+    // session) still believes the head is e1 and submits [e2, e7, e8]. The numbers look
+    // monotonic from B’s perspective, but we must reject and force B to rebase locally
+    // so the leader never regresses.
     for (let i = 1; i < batch.length; i++) {
         if (EventSequenceNumber.isGreaterThanOrEqual(batch[i - 1].seqNum, batch[i].seqNum)) {
-            shouldNeverHappen(`Events must be ordered in monotonically ascending order by eventNum. Received: [${batch.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`);
+            return yield* LeaderAheadError.make({
+                minimumExpectedNum: batch[i - 1].seqNum,
+                providedNum: batch[i].seqNum,
+            });
         }
     }
     // Make sure smallest sequence number is > pushHead