@livestore/livestore 0.2.0-dev.2 → 0.3.0-dev.10

package/src/live-queries/db.ts

@@ -5,6 +5,7 @@ import {
   prepareBindValues,
   QueryBuilderAstSymbol,
   replaceSessionIdSymbol,
+  UnexpectedError,
 } from '@livestore/common'
 import { deepEqual, shouldNeverHappen } from '@livestore/utils'
 import { Predicate, Schema, TreeFormatter } from '@livestore/utils/effect'
@@ -144,28 +145,32 @@ export class LiveStoreDbQuery<
     let queryInputRaw$OrQueryInputRaw: TQueryInputRaw | Thunk<TQueryInputRaw, QueryContext, RefreshReason>
 
     const fromQueryBuilder = (qb: QueryBuilder.Any, otelContext: otel.Context | undefined) => {
-      const qbRes = qb.asSql()
-      const schema = getResultSchema(qb) as Schema.Schema<TResultSchema, ReadonlyArray<any>>
-      const ast = qb[QueryBuilderAstSymbol]
-
-      return {
-        queryInputRaw: {
-          query: qbRes.query,
-          schema,
-          bindValues: qbRes.bindValues,
-          queriedTables: new Set([ast.tableDef.sqliteDef.name]),
-          queryInfo: ast._tag === 'RowQuery' ? { _tag: 'Row', table: ast.tableDef, id: ast.id } : { _tag: 'None' },
-        } satisfies TQueryInputRaw,
-        label: ast._tag === 'RowQuery' ? rowQueryLabel(ast.tableDef, ast.id) : qb.toString(),
-        execBeforeFirstRun:
-          ast._tag === 'RowQuery'
-            ? makeExecBeforeFirstRun({
-                table: ast.tableDef,
-                insertValues: ast.insertValues,
-                id: ast.id,
-                otelContext,
-              })
-            : undefined,
+      try {
+        const qbRes = qb.asSql()
+        const schema = getResultSchema(qb) as Schema.Schema<TResultSchema, ReadonlyArray<any>>
+        const ast = qb[QueryBuilderAstSymbol]
+
+        return {
+          queryInputRaw: {
+            query: qbRes.query,
+            schema,
+            bindValues: qbRes.bindValues,
+            queriedTables: new Set([ast.tableDef.sqliteDef.name]),
+            queryInfo: ast._tag === 'RowQuery' ? { _tag: 'Row', table: ast.tableDef, id: ast.id } : { _tag: 'None' },
+          } satisfies TQueryInputRaw,
+          label: ast._tag === 'RowQuery' ? rowQueryLabel(ast.tableDef, ast.id) : qb.toString(),
+          execBeforeFirstRun:
+            ast._tag === 'RowQuery'
+              ? makeExecBeforeFirstRun({
+                  table: ast.tableDef,
+                  insertValues: ast.insertValues,
+                  id: ast.id,
+                  otelContext,
+                })
+              : undefined,
+        }
+      } catch (cause) {
+        throw new UnexpectedError({ cause, note: `Error building query for ${qb.toString()}`, payload: { qb } })
       }
     }
 
@@ -274,7 +279,7 @@ export class LiveStoreDbQuery<
             }
 
             if (bindValues !== undefined) {
-              replaceSessionIdSymbol(bindValues, store.clientSession.coordinator.sessionId)
+              replaceSessionIdSymbol(bindValues, store.clientSession.sessionId)
             }
 
             // Establish a reactive dependency on the tables used in the query

package/src/row-query-utils.ts

@@ -60,6 +60,6 @@ export const makeExecBeforeFirstRun =
       }
 
       // NOTE It's important that we only mutate and don't refresh here, as this function is called during a render
-      store.mutateWithoutRefresh(table.insert({ id, ...insertValues }), { otelContext, coordinatorMode: 'default' })
+      store.mutate({ otelContext, skipRefresh: true }, table.insert({ id, ...insertValues }))
     }
   }

package/src/store/create-store.ts

@@ -2,21 +2,18 @@ import type {
   Adapter,
   BootStatus,
   ClientSession,
-  EventId,
   IntentionalShutdownCause,
   StoreDevtoolsChannel,
 } from '@livestore/common'
-import { UnexpectedError } from '@livestore/common'
-import type { LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
-import { makeNoopTracer } from '@livestore/utils'
+import { provideOtel, UnexpectedError } from '@livestore/common'
+import type { EventId, LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
+import { LS_DEV } from '@livestore/utils'
+import type { Cause } from '@livestore/utils/effect'
 import {
-  Cause,
   Deferred,
-  Duration,
   Effect,
   Exit,
-  FiberSet,
-  Layer,
+  identity,
   Logger,
   LogLevel,
   MutableHashMap,
@@ -24,29 +21,34 @@ import {
   Queue,
   Runtime,
   Scope,
+  TaskTracing,
 } from '@livestore/utils/effect'
+import { nanoid } from '@livestore/utils/nanoid'
 import * as otel from '@opentelemetry/api'
 
 import { globalReactivityGraph } from '../global-state.js'
 import type { ReactivityGraph } from '../live-queries/base-class.js'
 import { connectDevtoolsToStore } from './devtools.js'
 import { Store } from './store.js'
-import type { BaseGraphQLContext, GraphQLOptions, OtelOptions } from './store-types.js'
+import type { BaseGraphQLContext, GraphQLOptions, OtelOptions, ShutdownDeferred } from './store-types.js'
 
-export type CreateStoreOptions<TGraphQLContext extends BaseGraphQLContext, TSchema extends LiveStoreSchema> = {
+export interface CreateStoreOptions<TGraphQLContext extends BaseGraphQLContext, TSchema extends LiveStoreSchema> {
   schema: TSchema
   adapter: Adapter
   storeId: string
   reactivityGraph?: ReactivityGraph
   graphQLOptions?: GraphQLOptions<TGraphQLContext>
-  otelOptions?: Partial<OtelOptions>
   boot?: (
     store: Store<TGraphQLContext, TSchema>,
     parentSpan: otel.Span,
-  ) => void | Promise<void> | Effect.Effect<void, unknown, otel.Tracer>
+  ) => void | Promise<void> | Effect.Effect<void, unknown, OtelTracer.OtelTracer>
   batchUpdates?: (run: () => void) => void
   disableDevtools?: boolean
   onBootStatus?: (status: BootStatus) => void
+  shutdownDeferred?: ShutdownDeferred
+  debug?: {
+    instanceId?: string
+  }
 }
 
 /** Create a new LiveStore Store */
@@ -55,8 +57,12 @@ export const createStorePromise = async <
   TSchema extends LiveStoreSchema = LiveStoreSchema,
 >({
   signal,
+  otelOptions,
   ...options
-}: CreateStoreOptions<TGraphQLContext, TSchema> & { signal?: AbortSignal }): Promise<Store<TGraphQLContext, TSchema>> =>
+}: CreateStoreOptions<TGraphQLContext, TSchema> & {
+  signal?: AbortSignal
+  otelOptions?: Partial<OtelOptions>
+}): Promise<Store<TGraphQLContext, TSchema>> =>
   Effect.gen(function* () {
     const scope = yield* Scope.make()
     const runtime = yield* Effect.runtime()
@@ -67,12 +73,12 @@ export const createStorePromise = async <
       })
     }
 
-    return yield* FiberSet.make().pipe(
-      Effect.andThen((fiberSet) => createStore({ ...options, fiberSet })),
-      Scope.extend(scope),
-    )
+    return yield* createStore({ ...options }).pipe(Scope.extend(scope))
   }).pipe(
-    Effect.withSpan('createStore'),
+    Effect.withSpan('createStore', {
+      attributes: { storeId: options.storeId, disableDevtools: options.disableDevtools },
+    }),
+    provideOtel({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer }),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
     Effect.provide(Logger.pretty),
@@ -88,127 +94,117 @@ export const createStore = <
   adapter,
   storeId,
   graphQLOptions,
-  otelOptions,
   boot,
   reactivityGraph = globalReactivityGraph,
   batchUpdates,
   disableDevtools,
   onBootStatus,
-  fiberSet,
-}: CreateStoreOptions<TGraphQLContext, TSchema> & { fiberSet: FiberSet.FiberSet }): Effect.Effect<
+  shutdownDeferred,
+  debug,
+}: CreateStoreOptions<TGraphQLContext, TSchema>): Effect.Effect<
   Store<TGraphQLContext, TSchema>,
   UnexpectedError,
-  Scope.Scope
-> => {
-  const otelTracer = otelOptions?.tracer ?? makeNoopTracer()
-  const otelRootSpanContext = otelOptions?.rootSpanContext ?? otel.context.active()
+  Scope.Scope | OtelTracer.OtelTracer
+> =>
+  Effect.gen(function* () {
+    const lifetimeScope = yield* Scope.make()
 
-  const TracingLive = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
-    Layer.provide(Layer.sync(OtelTracer.Tracer, () => otelTracer)),
-  )
+    yield* Effect.addFinalizer((_) => Scope.close(lifetimeScope, _))
 
-  return Effect.gen(function* () {
-    const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
+    const debugInstanceId = debug?.instanceId ?? nanoid(10)
 
-    const bootStatusQueue = yield* Queue.unbounded<BootStatus>().pipe(Effect.acquireRelease(Queue.shutdown))
+    return yield* Effect.gen(function* () {
+      const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
+      const otelRootSpanContext = otel.trace.setSpan(otel.context.active(), span)
+      const otelTracer = yield* OtelTracer.OtelTracer
 
-    yield* Queue.take(bootStatusQueue).pipe(
-      Effect.tapSync((status) => onBootStatus?.(status)),
-      Effect.tap((status) => (status.stage === 'done' ? Queue.shutdown(bootStatusQueue) : Effect.void)),
-      Effect.forever,
-      Effect.tapCauseLogPretty,
-      Effect.forkScoped,
-    )
+      const bootStatusQueue = yield* Queue.unbounded<BootStatus>().pipe(Effect.acquireRelease(Queue.shutdown))
 
-    const storeDeferred = yield* Deferred.make<Store>()
+      yield* Queue.take(bootStatusQueue).pipe(
+        Effect.tapSync((status) => onBootStatus?.(status)),
+        Effect.tap((status) => (status.stage === 'done' ? Queue.shutdown(bootStatusQueue) : Effect.void)),
+        Effect.forever,
+        Effect.tapCauseLogPretty,
+        Effect.forkScoped,
+      )
 
-    const connectDevtoolsToStore_ = (storeDevtoolsChannel: StoreDevtoolsChannel) =>
-      Effect.gen(function* () {
-        const store = yield* Deferred.await(storeDeferred)
-        yield* connectDevtoolsToStore({ storeDevtoolsChannel, store })
-      })
+      const storeDeferred = yield* Deferred.make<Store>()
+
+      const connectDevtoolsToStore_ = (storeDevtoolsChannel: StoreDevtoolsChannel) =>
+        Effect.gen(function* () {
+          const store = yield* storeDeferred
+          yield* connectDevtoolsToStore({ storeDevtoolsChannel, store })
+        })
+
+      const runtime = yield* Effect.runtime<Scope.Scope>()
 
-    const runtime = yield* Effect.runtime<Scope.Scope>()
-
-    // TODO close parent scope? (Needs refactor with Mike Arnaldi)
-    const shutdown = (cause: Cause.Cause<UnexpectedError | IntentionalShutdownCause>) =>
-      Effect.gen(function* () {
-        // NOTE we're calling `cause.toString()` here to avoid triggering a `console.error` in the grouped log
-        const logCause =
-          Cause.isFailType(cause) && cause.error._tag === 'LiveStore.IntentionalShutdownCause'
-            ? cause.toString()
-            : cause
-        yield* Effect.logDebug(`Shutting down LiveStore`, logCause)
-
-        FiberSet.clear(fiberSet).pipe(
-          Effect.andThen(() => FiberSet.run(fiberSet, Effect.failCause(cause))),
-          Effect.timeout(Duration.seconds(1)),
-          Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown:clear-fiber-set', duration: 500 }),
-          Effect.catchTag('TimeoutException', (err) =>
-            Effect.logError('Store shutdown timed out. Forcing shutdown.', err).pipe(
-              Effect.andThen(FiberSet.run(fiberSet, Effect.failCause(cause))),
-            ),
+      const shutdown = (cause: Cause.Cause<UnexpectedError | IntentionalShutdownCause>) =>
+        Scope.close(lifetimeScope, Exit.failCause(cause)).pipe(
+          Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown', duration: 500 }),
+          Effect.timeout(1000),
+          Effect.catchTag('TimeoutException', () =>
+            Effect.logError('@livestore/livestore:shutdown: Timed out after 1 second'),
           ),
-          Runtime.runFork(runtime), // NOTE we need to fork this separately otherwise it will also be interrupted
+          Effect.tap(() => (shutdownDeferred ? Deferred.failCause(shutdownDeferred, cause) : Effect.void)),
+          Effect.tap(() => Effect.logDebug('LiveStore shutdown complete')),
+          Effect.withSpan('livestore:shutdown'),
         )
-      }).pipe(Effect.withSpan('livestore:shutdown'))
-
-    const clientSession: ClientSession = yield* adapter({
-      schema,
-      storeId,
-      devtoolsEnabled: disableDevtools !== true,
-      bootStatusQueue,
-      shutdown,
-      connectDevtoolsToStore: connectDevtoolsToStore_,
-    }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
-
-    // TODO fill up with unsynced mutation events from the client session
-    const unsyncedMutationEvents = MutableHashMap.empty<EventId, MutationEvent.ForSchema<TSchema>>()
-
-    const store = Store.createStore<TGraphQLContext, TSchema>(
-      {
-        clientSession,
+
+      const clientSession: ClientSession = yield* adapter({
         schema,
-        graphQLOptions,
-        otelOptions: { tracer: otelTracer, rootSpanContext: otelRootSpanContext },
-        reactivityGraph,
-        disableDevtools,
-        unsyncedMutationEvents,
-        fiberSet,
-        runtime,
-        // NOTE during boot we're not yet executing mutations in a batched context
-        // but only set the provided `batchUpdates` function after boot
-        batchUpdates: (run) => run(),
         storeId,
-      },
-      span,
-    )
-
-    if (boot !== undefined) {
-      // TODO also incorporate `boot` function progress into `bootStatusQueue`
-      yield* Effect.tryAll(() => boot(store, span)).pipe(
-        UnexpectedError.mapToUnexpectedError,
-        Effect.withSpan('createStore:boot'),
+        devtoolsEnabled: disableDevtools !== true,
+        bootStatusQueue,
+        shutdown,
+        connectDevtoolsToStore: connectDevtoolsToStore_,
+        debugInstanceId,
+      }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
+
+      // TODO fill up with unsynced mutation events from the client session
+      const unsyncedMutationEvents = MutableHashMap.empty<EventId.EventId, MutationEvent.ForSchema<TSchema>>()
+
+      const store = Store.createStore<TGraphQLContext, TSchema>(
+        {
+          clientSession,
+          schema,
+          graphQLOptions,
+          otelOptions: { tracer: otelTracer, rootSpanContext: otelRootSpanContext },
+          reactivityGraph,
+          disableDevtools,
+          unsyncedMutationEvents,
+          lifetimeScope,
+          runtime,
+          // NOTE during boot we're not yet executing mutations in a batched context
+          // but only set the provided `batchUpdates` function after boot
+          batchUpdates: (run) => run(),
+          storeId,
+        },
+        span,
       )
-    }
 
-    // NOTE it's important to yield here to allow the forked Effect in the store constructor to run
-    yield* Effect.yieldNow()
+      if (boot !== undefined) {
+        // TODO also incorporate `boot` function progress into `bootStatusQueue`
+        yield* Effect.tryAll(() => boot(store, span)).pipe(
+          UnexpectedError.mapToUnexpectedError,
+          Effect.withSpan('createStore:boot'),
+        )
+      }
 
-    if (batchUpdates !== undefined) {
-      // Replacing the default batchUpdates function with the provided one after boot
-      store.reactivityGraph.context!.effectsWrapper = batchUpdates
-    }
+      // NOTE it's important to yield here to allow the forked Effect in the store constructor to run
+      yield* Effect.yieldNow()
 
-    yield* Deferred.succeed(storeDeferred, store as any as Store)
+      if (batchUpdates !== undefined) {
+        // Replacing the default batchUpdates function with the provided one after boot
+        store.reactivityGraph.context!.effectsWrapper = batchUpdates
+      }
 
-    return store
-  }).pipe(
-    Effect.withSpan('createStore', {
-      parent: otelOptions?.rootSpanContext
-        ? OtelTracer.makeExternalSpan(otel.trace.getSpanContext(otelOptions.rootSpanContext)!)
-        : undefined,
-    }),
-    Effect.provide(TracingLive),
-  )
-}
+      yield* Deferred.succeed(storeDeferred, store as any as Store)
+
+      return store
+    }).pipe(
+      Effect.withSpan('createStore', { attributes: { debugInstanceId, storeId } }),
+      Effect.annotateLogs({ debugInstanceId, storeId }),
+      LS_DEV ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
+      Scope.extend(lifetimeScope),
+    )
+  })

package/src/store/devtools.ts

@@ -21,20 +21,29 @@ type Unsub = () => void
 type RequestId = string
 type SubMap = Map<RequestId, Unsub>
 
+// When running this code in Node.js, we need to use `setTimeout` instead of `requestAnimationFrame`
+const requestNextTick: (cb: () => void) => number =
+  globalThis.requestAnimationFrame === undefined
+    ? (cb: () => void) => setTimeout(cb, 1000) as unknown as number
+    : globalThis.requestAnimationFrame
+
+const cancelTick: (id: number) => void =
+  globalThis.cancelAnimationFrame === undefined ? (id: number) => clearTimeout(id) : globalThis.cancelAnimationFrame
+
 export const connectDevtoolsToStore = ({
   storeDevtoolsChannel,
   store,
 }: {
-  storeDevtoolsChannel: WebChannel.WebChannel<Devtools.MessageToAppHostStore, Devtools.MessageFromAppHostStore>
+  storeDevtoolsChannel: WebChannel.WebChannel<Devtools.MessageToAppClientSession, Devtools.MessageFromAppClientSession>
   store: IStore
 }) =>
   Effect.gen(function* () {
-    const appHostId = store.clientSession.coordinator.devtools.appHostId
-
     const reactivityGraphSubcriptions: SubMap = new Map()
     const liveQueriesSubscriptions: SubMap = new Map()
     const debugInfoHistorySubscriptions: SubMap = new Map()
 
+    const { clientId, sessionId } = store.clientSession
+
     yield* Effect.addFinalizer(() =>
       Effect.sync(() => {
         reactivityGraphSubcriptions.forEach((unsub) => unsub())
@@ -43,17 +52,22 @@ export const connectDevtoolsToStore = ({
       }),
     )
 
-    const sendToDevtools = (message: Devtools.MessageFromAppHostStore) =>
-      storeDevtoolsChannel.send(message).pipe(Effect.tapCauseLogPretty, Effect.runSync)
+    const sendToDevtools = (message: Devtools.MessageFromAppClientSession) =>
+      storeDevtoolsChannel.send(message).pipe(Effect.tapCauseLogPretty, Effect.runFork)
 
-    const onMessage = (decodedMessage: typeof Devtools.MessageToAppHostStore.Type) => {
-      // console.log('storeMessagePort message', decodedMessage)
+    const onMessage = (decodedMessage: typeof Devtools.MessageToAppClientSession.Type) => {
+      // console.debug('@livestore/livestore:store:devtools:onMessage', decodedMessage)
 
-      if (decodedMessage.appHostId !== store.clientSession.coordinator.devtools.appHostId) {
+      if (decodedMessage.clientId !== clientId || decodedMessage.sessionId !== sessionId) {
         // console.log(`Unknown message`, event)
         return
       }
 
+      if (decodedMessage._tag === 'LSD.Disconnect') {
+        // console.error('TODO handle disconnect properly in store')
+        return
+      }
+
       const requestId = decodedMessage.requestId
 
       const requestIdleCallback = globalThis.requestIdleCallback ?? ((cb: () => void) => cb())
@@ -71,7 +85,8 @@ export const connectDevtoolsToStore = ({
                   Devtools.ReactivityGraphRes.make({
                     reactivityGraph: store.reactivityGraph.getSnapshot({ includeResults }),
                     requestId,
-                    appHostId,
+                    clientId,
+                    sessionId,
                     liveStoreVersion,
                   }),
                 ),
@@ -94,7 +109,8 @@ export const connectDevtoolsToStore = ({
             Devtools.DebugInfoRes.make({
               debugInfo: store.syncDbWrapper.debugInfo,
               requestId,
-              appHostId,
+              clientId,
+              sessionId,
               liveStoreVersion,
             }),
           )
@@ -103,7 +119,7 @@ export const connectDevtoolsToStore = ({
         case 'LSD.DebugInfoHistorySubscribe': {
           const buffer: DebugInfo[] = []
           let hasStopped = false
-          let rafHandle: number | undefined
+          let tickHandle: number | undefined
 
           const tick = () => {
             buffer.push(store.syncDbWrapper.debugInfo)
@@ -119,7 +135,8 @@ export const connectDevtoolsToStore = ({
                 Devtools.DebugInfoHistoryRes.make({
                   debugInfoHistory: buffer,
                   requestId,
-                  appHostId,
+                  clientId,
+                  sessionId,
                   liveStoreVersion,
                 }),
               )
@@ -127,16 +144,17 @@ export const connectDevtoolsToStore = ({
             }
 
             if (hasStopped === false) {
-              rafHandle = requestAnimationFrame(tick)
+              tickHandle = requestNextTick(tick)
             }
           }
 
-          rafHandle = requestAnimationFrame(tick)
+          tickHandle = requestNextTick(tick)
 
           const unsub = () => {
             hasStopped = true
-            if (rafHandle !== undefined) {
-              cancelAnimationFrame(rafHandle)
+            if (tickHandle !== undefined) {
+              cancelTick(tickHandle)
+              tickHandle = undefined
             }
           }
 
@@ -145,23 +163,27 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.DebugInfoHistoryUnsubscribe': {
-          debugInfoHistorySubscriptions.get(requestId)!()
+          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
+          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          debugInfoHistorySubscriptions.get(requestId)?.()
           debugInfoHistorySubscriptions.delete(requestId)
           break
         }
         case 'LSD.DebugInfoResetReq': {
           store.syncDbWrapper.debugInfo.slowQueries.clear()
-          sendToDevtools(Devtools.DebugInfoResetRes.make({ requestId, appHostId, liveStoreVersion }))
+          sendToDevtools(Devtools.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }))
           break
         }
         case 'LSD.DebugInfoRerunQueryReq': {
           const { queryStr, bindValues, queriedTables } = decodedMessage
           store.syncDbWrapper.select(queryStr, { bindValues, queriedTables, skipCache: true })
-          sendToDevtools(Devtools.DebugInfoRerunQueryRes.make({ requestId, appHostId, liveStoreVersion }))
+          sendToDevtools(Devtools.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }))
           break
         }
         case 'LSD.ReactivityGraphUnsubscribe': {
-          reactivityGraphSubcriptions.get(requestId)!()
+          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
+          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          reactivityGraphSubcriptions.get(requestId)?.()
           break
         }
         case 'LSD.LiveQueriesSubscribe': {
@@ -184,7 +206,8 @@ export const connectDevtoolsToStore = ({
                     })),
                     requestId,
                     liveStoreVersion,
-                    appHostId,
+                    clientId,
+                    sessionId,
                   }),
                 ),
               { timeout: 500 },
@@ -200,7 +223,9 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.LiveQueriesUnsubscribe': {
-          liveQueriesSubscriptions.get(requestId)!()
+          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
+          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          liveQueriesSubscriptions.get(requestId)?.()
           liveQueriesSubscriptions.delete(requestId)
           break
         }
@@ -209,6 +234,7 @@ export const connectDevtoolsToStore = ({
     }
 
     yield* storeDevtoolsChannel.listen.pipe(
+      // Stream.tapLogWithLabel('@livestore/livestore:store:devtools:onMessage'),
       Stream.flatten(),
       Stream.tapSync((message) => onMessage(message)),
       Stream.runDrain,

package/src/store/store-types.ts

@@ -1,6 +1,6 @@
-import type { ClientSession, EventId, IntentionalShutdownCause, UnexpectedError } from '@livestore/common'
-import type { LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
-import type { FiberSet, MutableHashMap, Runtime, Scope } from '@livestore/utils/effect'
+import type { ClientSession, IntentionalShutdownCause, UnexpectedError } from '@livestore/common'
+import type { EventId, LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
+import type { Deferred, MutableHashMap, Runtime, Scope } from '@livestore/utils/effect'
 import { Schema } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 import type { GraphQLSchema } from 'graphql'
@@ -25,6 +25,11 @@ export type LiveStoreContext =
 export class StoreAbort extends Schema.TaggedError<StoreAbort>()('LiveStore.StoreAbort', {}) {}
 export class StoreInterrupted extends Schema.TaggedError<StoreInterrupted>()('LiveStore.StoreInterrupted', {}) {}
 
+export type ShutdownDeferred = Deferred.Deferred<
+  void,
+  UnexpectedError | IntentionalShutdownCause | StoreInterrupted | StoreAbort
+>
+
 export type LiveStoreContextRunning = {
   stage: 'running'
   store: Store
@@ -58,10 +63,11 @@ export type StoreOptions<
   otelOptions: OtelOptions
   reactivityGraph: ReactivityGraph
   disableDevtools?: boolean
-  fiberSet: FiberSet.FiberSet
+  lifetimeScope: Scope.Scope
   runtime: Runtime.Runtime<Scope.Scope>
   batchUpdates: (runUpdates: () => void) => void
-  unsyncedMutationEvents: MutableHashMap.MutableHashMap<EventId, MutationEvent.ForSchema<TSchema>>
+  // TODO validate whether we still need this
+  unsyncedMutationEvents: MutableHashMap.MutableHashMap<EventId.EventId, MutationEvent.ForSchema<TSchema>>
 }
 
 export type RefreshReason =
@@ -69,7 +75,7 @@ export type RefreshReason =
   | {
       _tag: 'mutate'
       /** The mutations that were applied */
-      mutations: ReadonlyArray<MutationEvent.Any>
+      mutations: ReadonlyArray<MutationEvent.AnyDecoded | MutationEvent.PartialAnyDecoded>
 
       /** The tables that were written to by the event */
       writeTables: ReadonlyArray<string>
@@ -99,12 +105,6 @@ export type StoreOtel = {
 export type StoreMutateOptions = {
   label?: string
   skipRefresh?: boolean
-  wasSyncMessage?: boolean
-  /**
-   * When set to `false` the mutation won't be persisted in the mutation log and sync server (but still synced).
-   * This can be useful e.g. for fine-granular update events (e.g. position updates during drag & drop)
-   *
-   * @default true
-   */
-  persisted?: boolean
+  spanLinks?: otel.Link[]
+  otelContext?: otel.Context
 }