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

package/dist/store/store.d.ts

@@ -1,15 +1,18 @@
-import { type Bindable, type ClientSession, type ClientSessionSyncProcessor, type QueryBuilder, UnexpectedError } from '@livestore/common';
+import { type Bindable, type ClientSession, type ClientSessionSyncProcessor, MaterializeError, UnexpectedError } from '@livestore/common';
 import type { LiveStoreSchema } from '@livestore/common/schema';
 import { LiveStoreEvent } from '@livestore/common/schema';
 import type { Scope } from '@livestore/utils/effect';
 import { Cause, Effect, Inspectable, Schema, Stream } from '@livestore/utils/effect';
 import * as otel from '@opentelemetry/api';
-import type { LiveQuery, LiveQueryDef, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts';
+import type { LiveQuery, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts';
 import type { Ref } from '../reactive.ts';
 import { SqliteDbWrapper } from '../SqliteDbWrapper.ts';
 import { ReferenceCountedSet } from '../utils/data-structures.ts';
-import type { StackInfo } from '../utils/stack-info.ts';
-import type { RefreshReason, StoreCommitOptions, StoreEventsOptions, StoreOptions, StoreOtel, Unsubscribe } from './store-types.ts';
+import type { Queryable, RefreshReason, StoreCommitOptions, StoreEventsOptions, StoreOptions, StoreOtel, SubscribeOptions, Unsubscribe } from './store-types.ts';
+type SubscribeFn = {
+    <TResult>(query: Queryable<TResult>, onUpdate: (value: TResult) => void, options?: SubscribeOptions<TResult>): Unsubscribe;
+    <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): AsyncIterable<TResult>;
+};
 export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> extends Inspectable.Class {
     readonly storeId: string;
     reactivityGraph: ReactivityGraph;
@@ -18,6 +21,24 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
     schema: LiveStoreSchema;
     context: TContext;
     otel: StoreOtel;
+    /**
+     * Reactive connectivity updates emitted by the backing sync backend.
+     *
+     * @example
+     * ```ts
+     * import { Effect, Stream } from 'effect'
+     *
+     * const status = await store.networkStatus.pipe(Effect.runPromise)
+     *
+     * await store.networkStatus.changes.pipe(
+     *   Stream.tap((next) => console.log('network status update', next)),
+     *   Stream.runDrain,
+     *   Effect.scoped,
+     *   Effect.runPromise,
+     * )
+     * ```
+     */
+    readonly networkStatus: ClientSession['leaderThread']['networkStatus'];
     /**
      * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
      * This only works in combination with `equal: () => false` which will always trigger a refresh.
@@ -38,34 +59,27 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
     get clientId(): string;
     private checkShutdown;
     /**
-     * Subscribe to the results of a query
-     * Returns a function to cancel the subscription.
+     * Subscribe to the results of a query.
+     *
+     * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
+     * - Without a callback it returns an {@link AsyncIterable} that yields query results.
      *
      * @example
      * ```ts
-     * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+     * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
+     * ```
+     *
+     * @example
+     * ```ts
+     * for await (const result of store.subscribe(query$)) {
+     *   console.log(result)
+     * }
      * ```
      */
-    subscribe: <TResult>(query: LiveQueryDef<TResult, "def" | "signal-def"> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>, options: {
-        /** Called when the query result has changed */
-        onUpdate: (value: TResult) => void;
-        onSubscribe?: (query$: LiveQuery<TResult>) => void;
-        /** Gets called after the query subscription has been removed */
-        onUnsubsubscribe?: () => void;
-        label?: string;
-        /**
-         * Skips the initial `onUpdate` callback
-         * @default false
-         */
-        skipInitialRun?: boolean;
-        otelContext?: otel.Context;
-        /** If provided, the stack info will be added to the `activeSubscriptions` set of the query */
-        stackInfo?: StackInfo;
-    }) => Unsubscribe;
-    subscribeStream: <TResult>(query$: LiveQueryDef<TResult>, options?: {
-        label?: string;
-        skipInitialRun?: boolean;
-    } | undefined) => Stream.Stream<TResult>;
+    subscribe: SubscribeFn;
+    private subscribeWithCallback;
+    private subscribeAsAsyncIterable;
+    subscribeStream: <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>) => Stream.Stream<TResult>;
     /**
      * Synchronously queries the database without creating a LiveQuery.
      * This is useful for queries that don't need to be reactive.
@@ -80,7 +94,7 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
      * const completedTodos = store.query({ query: 'SELECT * FROM todo WHERE complete = 1', bindValues: {} })
      * ```
      */
-    query: <TResult>(query: QueryBuilder<TResult, any, any> | LiveQuery<TResult> | LiveQueryDef<TResult> | SignalDef<TResult> | {
+    query: <TResult>(query: Queryable<TResult> | {
         query: string;
         bindValues: Bindable;
         schema?: Schema.Schema<TResult>;
@@ -199,12 +213,14 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
      *
      * This is called automatically when the store was created using the React or Effect API.
      */
-    shutdown: (cause?: Cause.Cause<UnexpectedError>) => Effect.Effect<void>;
+    shutdown: (cause?: Cause.Cause<UnexpectedError | MaterializeError>) => Effect.Effect<void>;
     toJSON: () => {
         _tag: string;
         reactivityGraph: import("../reactive.ts").ReactiveGraphSnapshot;
     };
     private runEffectFork;
+    private runEffectPromise;
     private getCommitArgs;
 }
+export {};
 //# sourceMappingURL=store.d.ts.map

package/dist/store/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}

package/dist/store/store.js

@@ -1,6 +1,6 @@
-import { Devtools, getDurationMsFromSpan, getExecStatementsFromMaterializer, getResultSchema, hashMaterializerResults, IntentionalShutdownCause, isQueryBuilder, liveStoreVersion, makeClientSessionSyncProcessor, prepareBindValues, QueryBuilderAstSymbol, replaceSessionIdSymbol, UnexpectedError, } from '@livestore/common';
-import { getEventDef, LiveStoreEvent, SystemTables } from '@livestore/common/schema';
-import { assertNever, isDevEnv, notYetImplemented } from '@livestore/utils';
+import { Devtools, getExecStatementsFromMaterializer, getResultSchema, hashMaterializerResults, IntentionalShutdownCause, isQueryBuilder, liveStoreVersion, MaterializeError, MaterializerHashMismatchError, makeClientSessionSyncProcessor, prepareBindValues, QueryBuilderAstSymbol, replaceSessionIdSymbol, UnexpectedError, } from '@livestore/common';
+import { LiveStoreEvent, resolveEventDef, SystemTables } from '@livestore/common/schema';
+import { assertNever, isDevEnv, notYetImplemented, omitUndefineds, shouldNeverHappen } from '@livestore/utils';
 import { Cause, Effect, Exit, Fiber, Inspectable, Option, OtelTracer, Runtime, Schema, Stream, } from '@livestore/utils/effect';
 import { nanoid } from '@livestore/utils/nanoid';
 import * as otel from '@opentelemetry/api';
@@ -21,6 +21,24 @@ export class Store extends Inspectable.Class {
     schema;
     context;
     otel;
+    /**
+     * Reactive connectivity updates emitted by the backing sync backend.
+     *
+     * @example
+     * ```ts
+     * import { Effect, Stream } from 'effect'
+     *
+     * const status = await store.networkStatus.pipe(Effect.runPromise)
+     *
+     * await store.networkStatus.changes.pipe(
+     *   Stream.tap((next) => console.log('network status update', next)),
+     *   Stream.runDrain,
+     *   Effect.scoped,
+     *   Effect.runPromise,
+     * )
+     * ```
+     */
+    networkStatus;
     /**
      * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
      * This only works in combination with `equal: () => false` which will always trigger a refresh.
@@ -43,6 +61,7 @@ export class Store extends Inspectable.Class {
         this.clientSession = clientSession;
         this.schema = schema;
         this.context = context;
+        this.networkStatus = clientSession.leaderThread.networkStatus;
         this.effectContext = effectContext;
         const reactivityGraph = makeReactivityGraph();
         const syncSpan = otelOptions.tracer.startSpan('LiveStore:sync', {}, otelOptions.rootSpanContext);
@@ -50,23 +69,41 @@ export class Store extends Inspectable.Class {
             schema,
             clientSession,
             runtime: effectContext.runtime,
-            materializeEvent: (eventDecoded, { otelContext, withChangeset, materializerHashLeader }) => {
-                const { eventDef, materializer } = getEventDef(schema, eventDecoded.name);
+            materializeEvent: Effect.fn('client-session-sync-processor:materialize-event')((eventEncoded, { withChangeset, materializerHashLeader }) => 
+            // We need to use `Effect.gen` (even though we're using `Effect.fn`) so that we can pass `this` to the function
+            Effect.gen(this, function* () {
+                const resolution = yield* resolveEventDef(schema, {
+                    operation: '@livestore/livestore:store:materializeEvent',
+                    event: eventEncoded,
+                });
+                if (resolution._tag === 'unknown') {
+                    // Runtime schema doesn't know this event yet; skip materialization but
+                    // keep the log entry so upgraded clients can replay it later.
+                    return {
+                        writeTables: new Set(),
+                        sessionChangeset: { _tag: 'no-op' },
+                        materializerHash: Option.none(),
+                    };
+                }
+                const { eventDef, materializer } = resolution;
                 const execArgsArr = getExecStatementsFromMaterializer({
                     eventDef,
                     materializer,
                     dbState: this.sqliteDbWrapper,
-                    event: { decoded: eventDecoded, encoded: undefined },
+                    event: { decoded: undefined, encoded: eventEncoded },
                 });
                 const materializerHash = isDevEnv() ? Option.some(hashMaterializerResults(execArgsArr)) : Option.none();
+                // Hash mismatch detection only occurs during the pull path (when receiving events from the leader).
+                // During push path (local commits), materializerHashLeader is always Option.none(), so this condition
+                // will never be met. The check happens when the same event comes back from the leader during sync,
+                // allowing us to compare the leader's computed hash with our local re-materialization hash.
                 if (materializerHashLeader._tag === 'Some' &&
                     materializerHash._tag === 'Some' &&
                     materializerHashLeader.value !== materializerHash.value) {
-                    void this.shutdown(Cause.fail(UnexpectedError.make({
-                        cause: `Materializer hash mismatch detected for event "${eventDecoded.name}".`,
-                        note: `Please make sure your event materializer is a pure function without side effects.`,
-                    })));
+                    return yield* MaterializerHashMismatchError.make({ eventName: eventEncoded.name });
                 }
+                const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie);
+                const otelContext = otel.trace.setSpan(otel.context.active(), span);
                 const writeTablesForEvent = new Set();
                 const exec = () => {
                     for (const { statementSql, bindValues, writeTables = this.sqliteDbWrapper.getTablesUsed(statementSql), } of execArgsArr) {
@@ -74,16 +111,17 @@ export class Store extends Inspectable.Class {
                             this.sqliteDbWrapper.cachedExecute(statementSql, bindValues, { otelContext, writeTables });
                         }
                         catch (cause) {
+                            // TOOD refactor with `SqliteError`
                             throw UnexpectedError.make({
                                 cause,
-                                note: `Error executing materializer for event "${eventDecoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
+                                note: `Error executing materializer for event "${eventEncoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
                             });
                         }
                         // durationMsTotal += durationMs
                         for (const table of writeTables) {
                             writeTablesForEvent.add(table);
                         }
-                        this.sqliteDbWrapper.debug.head = eventDecoded.seqNum;
+                        this.sqliteDbWrapper.debug.head = eventEncoded.seqNum;
                     }
                 };
                 let sessionChangeset = { _tag: 'unset' };
@@ -94,7 +132,7 @@ export class Store extends Inspectable.Class {
                     exec();
                 }
                 return { writeTables: writeTablesForEvent, sessionChangeset, materializerHash };
-            },
+            }).pipe(Effect.mapError((cause) => MaterializeError.make({ cause })))),
             rollback: (changeset) => {
                 this.sqliteDbWrapper.rollback(changeset);
             },
@@ -109,8 +147,12 @@ export class Store extends Inspectable.Class {
             },
             span: syncSpan,
             params: {
-                leaderPushBatchSize: params.leaderPushBatchSize,
-                simulation: params.simulation?.clientSessionSyncProcessor,
+                ...omitUndefineds({
+                    leaderPushBatchSize: params.leaderPushBatchSize,
+                }),
+                ...(params.simulation?.clientSessionSyncProcessor !== undefined
+                    ? { simulation: params.simulation.clientSessionSyncProcessor }
+                    : {}),
             },
             confirmUnsavedChanges,
         });
@@ -188,18 +230,32 @@ export class Store extends Inspectable.Class {
         }
     };
     /**
-     * Subscribe to the results of a query
-     * Returns a function to cancel the subscription.
+     * Subscribe to the results of a query.
+     *
+     * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
+     * - Without a callback it returns an {@link AsyncIterable} that yields query results.
      *
      * @example
      * ```ts
-     * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+     * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
+     * ```
+     *
+     * @example
+     * ```ts
+     * for await (const result of store.subscribe(query$)) {
+     *   console.log(result)
+     * }
      * ```
      */
-    subscribe = (query, options) => {
+    subscribe = ((query, onUpdateOrOptions, maybeOptions) => {
+        if (typeof onUpdateOrOptions === 'function') {
+            return this.subscribeWithCallback(query, onUpdateOrOptions, maybeOptions);
+        }
+        return this.subscribeAsAsyncIterable(query, onUpdateOrOptions);
+    });
+    subscribeWithCallback = (query, onUpdate, options) => {
         this.checkShutdown('subscribe');
         return this.otel.tracer.startActiveSpan(`LiveStore.subscribe`, { attributes: { label: options?.label, queryLabel: isQueryBuilder(query) ? query.toString() : query.label } }, options?.otelContext ?? this.otel.queriesSpanContext, (span) => {
-            // console.debug('store sub', query$.id, query$.label)
             const otelContext = otel.trace.setSpan(otel.context.active(), span);
             const queryRcRef = isQueryBuilder(query)
                 ? queryDb(query).make(this.reactivityGraph.context)
@@ -211,18 +267,19 @@ export class Store extends Inspectable.Class {
                     };
             const query$ = queryRcRef.value;
             const label = `subscribe:${options?.label}`;
-            const effect = this.reactivityGraph.makeEffect((get, _otelContext, debugRefreshReason) => options.onUpdate(get(query$.results$, otelContext, debugRefreshReason)), { label });
+            const effect = this.reactivityGraph.makeEffect((get, _otelContext, debugRefreshReason) => onUpdate(get(query$.results$, otelContext, debugRefreshReason)), { label });
             if (options?.stackInfo) {
                 query$.activeSubscriptions.add(options.stackInfo);
             }
             options?.onSubscribe?.(query$);
             this.activeQueries.add(query$);
-            // Running effect right away to get initial value (unless `skipInitialRun` is set)
             if (options?.skipInitialRun !== true && !query$.isDestroyed) {
-                effect.doEffect(otelContext, { _tag: 'subscribe.initial', label: `subscribe-initial-run:${options?.label}` });
+                effect.doEffect(otelContext, {
+                    _tag: 'subscribe.initial',
+                    label: `subscribe-initial-run:${options?.label}`,
+                });
             }
             const unsubscribe = () => {
-                // console.debug('store unsub', query$.id, query$.label)
                 try {
                     this.reactivityGraph.destroyNode(effect);
                     this.activeQueries.remove(query$);
@@ -239,13 +296,16 @@ export class Store extends Inspectable.Class {
             return unsubscribe;
         });
     };
-    subscribeStream = (query$, options) => Stream.asyncPush((emit) => Effect.gen(this, function* () {
+    subscribeAsAsyncIterable = (query, options) => {
+        this.checkShutdown('subscribe');
+        return Stream.toAsyncIterable(this.subscribeStream(query, options));
+    };
+    subscribeStream = (query, options) => Stream.asyncPush((emit) => Effect.gen(this, function* () {
         const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.catchTag('NoSuchElementException', () => Effect.succeed(undefined)));
         const otelContext = otelSpan ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active();
-        yield* Effect.acquireRelease(Effect.sync(() => this.subscribe(query$, {
-            onUpdate: (result) => emit.single(result),
+        yield* Effect.acquireRelease(Effect.sync(() => this.subscribe(query, (result) => emit.single(result), {
+            ...(options ?? {}),
             otelContext,
-            label: options?.label,
         })), (unsub) => Effect.sync(() => unsub()));
     }));
     /**
@@ -266,7 +326,7 @@ export class Store extends Inspectable.Class {
         this.checkShutdown('query');
         if (typeof query === 'object' && 'query' in query && 'bindValues' in query) {
             const res = this.sqliteDbWrapper.cachedSelect(query.query, prepareBindValues(query.bindValues, query.query), {
-                otelContext: options?.otelContext,
+                ...omitUndefineds({ otelContext: options?.otelContext }),
             });
             if (query.schema) {
                 return Schema.decodeSync(query.schema)(res);
@@ -290,10 +350,16 @@ export class Store extends Inspectable.Class {
                 replaceSessionIdSymbol(sqlRes.bindValues, this.clientSession.sessionId);
             }
             const rawRes = this.sqliteDbWrapper.cachedSelect(sqlRes.query, sqlRes.bindValues, {
-                otelContext: options?.otelContext,
+                ...omitUndefineds({ otelContext: options?.otelContext }),
                 queriedTables: new Set([query[QueryBuilderAstSymbol].tableDef.sqliteDef.name]),
             });
-            return Schema.decodeSync(schema)(rawRes);
+            const decodeResult = Schema.decodeEither(schema)(rawRes);
+            if (decodeResult._tag === 'Right') {
+                return decodeResult.right;
+            }
+            else {
+                return shouldNeverHappen(`Failed to decode query result with for schema:`, schema.toString(), 'raw result:', rawRes, 'decode error:', decodeResult.left);
+            }
         }
         else if (query._tag === 'def') {
             const query$ = query.make(this.reactivityGraph.context);
@@ -306,7 +372,9 @@ export class Store extends Inspectable.Class {
             return signal$.value.get();
         }
         else {
-            return query.run({ otelContext: options?.otelContext, debugRefreshReason: options?.debugRefreshReason });
+            return query.run({
+                ...omitUndefineds({ otelContext: options?.otelContext, debugRefreshReason: options?.debugRefreshReason }),
+            });
         }
     };
     /**
@@ -393,73 +461,65 @@ export class Store extends Inspectable.Class {
     commit = (firstEventOrTxnFnOrOptions, ...restEvents) => {
         this.checkShutdown('commit');
         const { events, options } = this.getCommitArgs(firstEventOrTxnFnOrOptions, restEvents);
-        for (const event of events) {
-            replaceSessionIdSymbol(event.args, this.clientSession.sessionId);
-        }
-        if (events.length === 0)
-            return;
-        const skipRefresh = options?.skipRefresh ?? false;
-        const commitsSpan = otel.trace.getSpan(this.otel.commitsSpanContext);
-        commitsSpan.addEvent('commit');
-        // console.group('LiveStore.commit', { skipRefresh })
-        // events.forEach((_) => console.debug(_.name, _.args))
-        // console.groupEnd()
-        let durationMs;
-        return this.otel.tracer.startActiveSpan('LiveStore:commit', {
+        Effect.gen(this, function* () {
+            const commitsSpan = otel.trace.getSpan(this.otel.commitsSpanContext);
+            commitsSpan?.addEvent('commit');
+            const currentSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie);
+            commitsSpan?.addLink({ context: currentSpan.spanContext() });
+            for (const event of events) {
+                replaceSessionIdSymbol(event.args, this.clientSession.sessionId);
+            }
+            if (events.length === 0)
+                return;
+            const localRuntime = yield* Effect.runtime();
+            const materializeEventsTx = Effect.try({
+                try: () => {
+                    const runMaterializeEvents = () => {
+                        return this.syncProcessor.push(events).pipe(Runtime.runSync(localRuntime));
+                    };
+                    if (events.length > 1) {
+                        return this.sqliteDbWrapper.txn(runMaterializeEvents);
+                    }
+                    else {
+                        return runMaterializeEvents();
+                    }
+                },
+                catch: (cause) => UnexpectedError.make({ cause }),
+            });
+            // Materialize events to state
+            const { writeTables } = yield* materializeEventsTx;
+            const tablesToUpdate = [];
+            for (const tableName of writeTables) {
+                const tableRef = this.tableRefs[tableName];
+                assertNever(tableRef !== undefined, `No table ref found for ${tableName}`);
+                tablesToUpdate.push([tableRef, null]);
+            }
+            const debugRefreshReason = {
+                _tag: 'commit',
+                events,
+                writeTables: Array.from(writeTables),
+            };
+            const skipRefresh = options?.skipRefresh ?? false;
+            // Update all table refs together in a batch, to only trigger one reactive update
+            this.reactivityGraph.setRefs(tablesToUpdate, {
+                debugRefreshReason,
+                skipRefresh,
+                otelContext: otel.trace.setSpan(otel.context.active(), currentSpan),
+            });
+        }).pipe(Effect.withSpan('LiveStore:commit', {
+            root: true,
             attributes: {
                 'livestore.eventsCount': events.length,
                 'livestore.eventTags': events.map((_) => _.name),
-                'livestore.commitLabel': options?.label,
+                ...(options?.label && { 'livestore.commitLabel': options.label }),
             },
-            links: options?.spanLinks,
-        }, options?.otelContext ?? this.otel.commitsSpanContext, (span) => {
-            const otelContext = otel.trace.setSpan(otel.context.active(), span);
-            try {
-                // Materialize events to state
-                const { writeTables } = (() => {
-                    try {
-                        const materializeEvents = () => this.syncProcessor.push(events, { otelContext });
-                        if (events.length > 1) {
-                            return this.sqliteDbWrapper.txn(materializeEvents);
-                        }
-                        else {
-                            return materializeEvents();
-                        }
-                    }
-                    catch (e) {
-                        console.error(e);
-                        span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e.toString() });
-                        throw e;
-                    }
-                    finally {
-                        span.end();
-                    }
-                })();
-                const tablesToUpdate = [];
-                for (const tableName of writeTables) {
-                    const tableRef = this.tableRefs[tableName];
-                    assertNever(tableRef !== undefined, `No table ref found for ${tableName}`);
-                    tablesToUpdate.push([tableRef, null]);
-                }
-                const debugRefreshReason = {
-                    _tag: 'commit',
-                    events,
-                    writeTables: Array.from(writeTables),
-                };
-                // Update all table refs together in a batch, to only trigger one reactive update
-                this.reactivityGraph.setRefs(tablesToUpdate, { debugRefreshReason, otelContext, skipRefresh });
-            }
-            catch (e) {
-                console.error(e);
-                span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e.toString() });
-                throw e;
-            }
-            finally {
-                span.end();
-                durationMs = getDurationMsFromSpan(span);
-            }
-            return { durationMs };
-        });
+            links: [
+                // Span link to LiveStore:commits
+                OtelTracer.makeSpanLink({ context: otel.trace.getSpanContext(this.otel.commitsSpanContext) }),
+                // User-provided span links
+                ...(options?.spanLinks?.map(OtelTracer.makeSpanLink) ?? []),
+            ],
+        }), Effect.tapErrorCause(Effect.logError), Effect.catchAllCause((cause) => Effect.fork(this.shutdown(cause))), Runtime.runSync(this.effectContext.runtime));
     };
     // #endregion commit
     /**
@@ -517,7 +577,6 @@ export class Store extends Inspectable.Class {
      * This is called automatically when the store was created using the React or Effect API.
      */
     shutdown = (cause) => {
-        this.checkShutdown('shutdown');
         this.isShutdown = true;
         return this.clientSession.shutdown(cause ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })));
     };
@@ -556,12 +615,17 @@ export class Store extends Inspectable.Class {
             }))
                 .pipe(this.runEffectFork);
         },
-        syncStates: () => {
+        syncStates: () => Effect.gen(this, function* () {
+            const session = yield* this.syncProcessor.syncState;
+            const leader = yield* this.clientSession.leaderThread.syncState;
+            return { session, leader };
+        }).pipe(this.runEffectPromise),
+        printSyncStates: () => {
             Effect.gen(this, function* () {
                 const session = yield* this.syncProcessor.syncState;
-                console.log('Session sync state:', session.toJSON());
-                const leader = yield* this.clientSession.leaderThread.getSyncState;
-                console.log('Leader sync state:', leader.toJSON());
+                yield* Effect.log(`Session sync state: ${session.localHead} (upstream: ${session.upstreamHead})`, session.toJSON());
+                const leader = yield* this.clientSession.leaderThread.syncState;
+                yield* Effect.log(`Leader sync state: ${leader.localHead} (upstream: ${leader.upstreamHead})`, leader.toJSON());
             }).pipe(this.runEffectFork);
         },
         version: liveStoreVersion,
@@ -575,6 +639,7 @@ export class Store extends Inspectable.Class {
         reactivityGraph: this.reactivityGraph.getSnapshot({ includeResults: true }),
     });
     runEffectFork = (effect) => effect.pipe(Effect.forkIn(this.effectContext.lifetimeScope), Effect.tapCauseLogPretty, Runtime.runFork(this.effectContext.runtime));
+    runEffectPromise = (effect) => effect.pipe(Effect.tapCauseLogPretty, Runtime.runPromise(this.effectContext.runtime));
     getCommitArgs = (firstEventOrTxnFnOrOptions, restEvents) => {
         let events;
         let options;