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

package/dist/errors.js

@@ -1,14 +1,21 @@
-import { Effect, Schema, Stream } from '@livestore/utils/effect';
-export class UnexpectedError extends Schema.TaggedError()('LiveStore.UnexpectedError', {
+import { Cause, Effect, Layer, Schema, Stream } from '@livestore/utils/effect';
+import * as LiveStoreEvent from "./schema/LiveStoreEvent/mod.js";
+export class UnknownError extends Schema.TaggedError()('LiveStore.UnknownError', {
     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 mapToUnexpectedErrorStream = (stream) => stream.pipe(Stream.mapError((cause) => (Schema.is(UnexpectedError)(cause) ? cause : new UnexpectedError({ cause }))));
+    static mapToUnknownError = (effect) => effect.pipe(Effect.mapError((cause) => (Schema.is(UnknownError)(cause) ? cause : new UnknownError({ cause }))), Effect.catchAllDefect((cause) => new UnknownError({ cause })));
+    static mapToUnknownErrorLayer = (layer) => layer.pipe(Layer.catchAllCause((cause) => Cause.isFailType(cause) && Schema.is(UnknownError)(cause.error)
+        ? Layer.fail(cause.error)
+        : Layer.fail(new UnknownError({ cause: cause }))));
+    static mapToUnknownErrorStream = (stream) => stream.pipe(Stream.mapError((cause) => (Schema.is(UnknownError)(cause) ? cause : new UnknownError({ 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.Client.Encoded.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/index.d.ts

@@ -2,12 +2,13 @@ export * from './adapter-types.ts';
 export * from './bounded-collections.ts';
 export * from './debug-info.ts';
 export * as Devtools from './devtools/mod.ts';
+export * as LogConfig from './logging.ts';
 export * from './make-client-session.ts';
 export * from './materializer-helper.ts';
 export * from './otel.ts';
 export * from './rematerialize-from-eventlog.ts';
 export * from './schema/state/sqlite/query-builder/mod.ts';
-export * from './schema/state/sqlite/system-tables.ts';
+export * from './schema/state/sqlite/system-tables/mod.ts';
 export * from './schema-management/migrations.ts';
 export * as SqliteDbHelper from './sqlite-db-helper.ts';
 export * from './sync/index.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,WAAW,CAAA;AACzB,cAAc,kCAAkC,CAAA;AAChD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,wCAAwC,CAAA;AACtD,cAAc,mCAAmC,CAAA;AACjD,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,SAAS,MAAM,cAAc,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,WAAW,CAAA;AACzB,cAAc,kCAAkC,CAAA;AAChD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,4CAA4C,CAAA;AAC1D,cAAc,mCAAmC,CAAA;AACjD,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA"}

package/dist/index.js

@@ -2,12 +2,13 @@ export * from "./adapter-types.js";
 export * from "./bounded-collections.js";
 export * from "./debug-info.js";
 export * as Devtools from "./devtools/mod.js";
+export * as LogConfig from "./logging.js";
 export * from "./make-client-session.js";
 export * from "./materializer-helper.js";
 export * from "./otel.js";
 export * from "./rematerialize-from-eventlog.js";
 export * from "./schema/state/sqlite/query-builder/mod.js";
-export * from "./schema/state/sqlite/system-tables.js";
+export * from "./schema/state/sqlite/system-tables/mod.js";
 export * from "./schema-management/migrations.js";
 export * as SqliteDbHelper from "./sqlite-db-helper.js";
 export * from "./sync/index.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,WAAW,CAAA;AACzB,cAAc,kCAAkC,CAAA;AAChD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,wCAAwC,CAAA;AACtD,cAAc,mCAAmC,CAAA;AACjD,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,SAAS,MAAM,cAAc,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,WAAW,CAAA;AACzB,cAAc,kCAAkC,CAAA;AAChD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,4CAA4C,CAAA;AAC1D,cAAc,mCAAmC,CAAA;AACjD,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,cAAc,iBAAiB,CAAA;AAC/B,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA"}

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, UnknownError } 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,10 +51,15 @@ 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>;
         };
     };
-}) => Effect.Effect<LeaderSyncProcessor, UnexpectedError, Scope.Scope>;
+}) => Effect.Effect<LeaderSyncProcessor, UnknownError, Scope.Scope>;
 //# sourceMappingURL=LeaderSyncProcessor.d.ts.map

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,EAAwD,KAAK,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvH,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,YAAY,EAAE,KAAK,CAAC,KAAK,CAuR5D,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 { UnknownError } 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 = {
@@ -65,9 +62,9 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
      *
      * Thus the purpose of the pushHeadRef is the guard the integrity of the local push queue
      */
-    const pushHeadRef = { current: EventSequenceNumber.ROOT };
+    const pushHeadRef = { current: EventSequenceNumber.Client.ROOT };
     const advancePushHead = (eventNum) => {
-        pushHeadRef.current = EventSequenceNumber.max(pushHeadRef.current, eventNum);
+        pushHeadRef.current = EventSequenceNumber.Client.max(pushHeadRef.current, eventNum);
     };
     // NOTE: New events are only pushed to sync backend after successful local push processing
     const push = (newEvents, options) => Effect.gen(function* () {
@@ -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 eventEncoded = new LiveStoreEvent.EncodedWithMeta({
+        const resolution = yield* resolveEventDef(schema, {
+            operation: '@livestore/common:LeaderSyncProcessor:pushPartial',
+            event: {
+                name,
+                args,
+                clientId,
+                sessionId,
+                seqNum: syncState.localHead,
+            },
+        }).pipe(UnknownError.mapToUnknownError);
+        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.Client.EncodedWithMeta({
             name,
             args,
             clientId,
             sessionId,
-            ...EventSequenceNumber.nextPair({ seqNum: syncState.localHead, isClient: eventDef.options.clientOnly }),
+            ...EventSequenceNumber.Client.nextPair({
+                seqNum: syncState.localHead,
+                isClient: resolution.eventDef.options.clientOnly,
+            }),
         });
         yield* push([eventEncoded]);
     }).pipe(Effect.catchTag('LeaderAheadError', Effect.orDie));
@@ -125,20 +139,25 @@ export const makeLeaderSyncProcessor = ({ schema, dbState, initialBlockingSyncCo
         // Rehydrate sync queue
         if (initialSyncState.pending.length > 0) {
             const globalPendingEvents = initialSyncState.pending
-                // Don't sync clientOnly events
+                // Don't sync client-local 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 : UnknownError.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,26 +268,39 @@ 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 },
             isClientEvent,
-            isEqualEvent: LiveStoreEvent.isEqualEncoded,
+            isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
         });
         switch (mergeResult._tag) {
-            case 'unexpected-error': {
-                otelSpan?.addEvent(`push:unexpected-error`, {
+            case 'unknown-error': {
+                otelSpan?.addEvent(`push:unknown-error`, {
                     batchSize: newEvents.length,
                     newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
                 });
-                return yield* new SyncError({ cause: mergeResult.message });
+                return yield* new UnknownError({ cause: mergeResult.message });
             }
             case 'rebase': {
                 return shouldNeverHappen('The leader thread should never have to rebase due to a local push');
@@ -312,10 +350,10 @@ const backgroundApplyLocalPushes = ({ localPushesLatch, localPushesQueue, pullLa
             batchSize: newEvents.length,
             mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
         });
-        // Don't sync clientOnly events
+        // Don't sync client-local 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) {
@@ -370,18 +408,18 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
             syncState,
             payload: SyncState.PayloadUpstreamAdvance.make({ newEvents }),
             isClientEvent,
-            isEqualEvent: LiveStoreEvent.isEqualEncoded,
+            isEqualEvent: LiveStoreEvent.Client.isEqualEncoded,
             ignoreClientEvents: true,
         });
         if (mergeResult._tag === 'reject') {
             return shouldNeverHappen('The leader thread should never reject upstream advances');
         }
-        else if (mergeResult._tag === 'unexpected-error') {
-            otelSpan?.addEvent(`pull:unexpected-error`, {
+        else if (mergeResult._tag === 'unknown-error') {
+            otelSpan?.addEvent(`pull:unknown-error`, {
                 newEventsCount: newEvents.length,
                 newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
             });
-            return yield* new SyncError({ cause: mergeResult.message });
+            return yield* new UnknownError({ 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,
@@ -421,8 +465,8 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
             if (mergeResult.confirmedEvents.length > 0) {
                 // `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);
+                const confirmedNewEvents = newEvents.filter((event) => mergeResult.confirmedEvents.some((confirmedEvent) => EventSequenceNumber.Client.isEqual(event.seqNum, confirmedEvent.seqNum)));
+                yield* Eventlog.updateSyncMetadata(confirmedNewEvents).pipe(UnknownError.mapToUnknownError);
             }
         }
         // 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,
@@ -450,15 +497,17 @@ const backgroundBackendPulling = ({ initialBackendHead, isClientEvent, restartBa
         // (e.g. needed for simulating being offline)
         // TODO remove when there's a better way to handle this in stream above
         yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true);
-        yield* onNewPullChunk(batch.map((_) => LiveStoreEvent.EncodedWithMeta.fromGlobal(_.eventEncoded, {
+        yield* onNewPullChunk(batch.map((_) => LiveStoreEvent.Client.EncodedWithMeta.fromGlobal(_.eventEncoded, {
             syncMetadata: _.metadata,
             // TODO we can't really know the materializer result here yet beyond the first event batch item as we need to materialize it one by one first
             // This is a bug and needs to be fixed https://github.com/livestorejs/livestore/issues/503#issuecomment-3114533165
-            materializerHashLeader: hashMaterializerResult(LiveStoreEvent.encodedFromGlobal(_.eventEncoded)),
+            materializerHashLeader: hashMaterializerResult(LiveStoreEvent.Global.toClientEncoded(_.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 UnknownError cases
+        const isRetryable = (err) => err._tag === 'InvalidPushError' && err.cause._tag === 'LiveStore.UnknownError';
+        // 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) => {
@@ -506,15 +578,15 @@ const makePullQueueSet = Effect.gen(function* () {
         const queue = yield* Queue.unbounded().pipe(Effect.acquireRelease(Queue.shutdown));
         yield* Effect.addFinalizer(() => Effect.sync(() => set.delete(queue)));
         const payloadsSinceCursor = Array.from(cachedPayloads.entries())
-            .flatMap(([seqNumStr, payloads]) => payloads.map((payload) => ({ payload, seqNum: EventSequenceNumber.fromString(seqNumStr) })))
-            .filter(({ seqNum }) => EventSequenceNumber.isGreaterThan(seqNum, cursor))
-            .toSorted((a, b) => EventSequenceNumber.compare(a.seqNum, b.seqNum))
+            .flatMap(([seqNumStr, payloads]) => payloads.map((payload) => ({ payload, seqNum: EventSequenceNumber.Client.fromString(seqNumStr) })))
+            .filter(({ seqNum }) => EventSequenceNumber.Client.isGreaterThan(seqNum, cursor))
+            .toSorted((a, b) => EventSequenceNumber.Client.compare(a.seqNum, b.seqNum))
             .map(({ payload }) => {
             if (payload._tag === 'upstream-advance') {
                 return {
                     payload: {
                         _tag: 'upstream-advance',
-                        newEvents: ReadonlyArray.dropWhile(payload.newEvents, (eventEncoded) => EventSequenceNumber.isGreaterThanOrEqual(cursor, eventEncoded.seqNum)),
+                        newEvents: ReadonlyArray.dropWhile(payload.newEvents, (eventEncoded) => EventSequenceNumber.Client.isGreaterThanOrEqual(cursor, eventEncoded.seqNum)),
                     },
                 };
             }
@@ -554,7 +626,7 @@ const makePullQueueSet = Effect.gen(function* () {
         return queue;
     });
     const offer = (item) => Effect.gen(function* () {
-        const seqNumStr = EventSequenceNumber.toString(item.leaderHead);
+        const seqNumStr = EventSequenceNumber.Client.toString(item.leaderHead);
         if (cachedPayloads.has(seqNumStr)) {
             cachedPayloads.get(seqNumStr).push(item.payload);
         }
@@ -575,18 +647,29 @@ 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(', ')}]`);
+        if (EventSequenceNumber.Client.isGreaterThanOrEqual(batch[i - 1].seqNum, batch[i].seqNum)) {
+            return yield* LeaderAheadError.make({
+                minimumExpectedNum: batch[i - 1].seqNum,
+                providedNum: batch[i].seqNum,
+            });
         }
     }
     // Make sure smallest sequence number is > pushHead
-    if (EventSequenceNumber.isGreaterThanOrEqual(pushHead, batch[0].seqNum)) {
+    if (EventSequenceNumber.Client.isGreaterThanOrEqual(pushHead, batch[0].seqNum)) {
         return yield* LeaderAheadError.make({
             minimumExpectedNum: pushHead,
             providedNum: batch[0].seqNum,