@livestore/livestore 0.4.0-dev.8 → 0.4.0

package/src/store/create-store.ts

@@ -1,3 +1,5 @@
+import * as otel from '@opentelemetry/api'
+
 import {
   type Adapter,
   type BootStatus,
@@ -5,13 +7,13 @@ import {
   type ClientSessionDevtoolsChannel,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
-  type InvalidPullError,
-  type IsOfflineError,
+  LogConfig,
   type MaterializeError,
+  type BackendIdMismatchError,
   type MigrationsReport,
   provideOtel,
-  type SyncError,
-  UnexpectedError,
+  type ServerAheadError,
+  UnknownError,
 } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { isDevEnv, LS_DEV, omitUndefineds } from '@livestore/utils'
@@ -23,30 +25,45 @@ import {
   Fiber,
   identity,
   Layer,
-  Logger,
-  LogLevel,
   OtelTracer,
   Queue,
   Runtime,
-  type Schema,
+  Schema,
   Scope,
   TaskTracing,
 } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
-import * as otel from '@opentelemetry/api'
 
 import { connectDevtoolsToStore } from './devtools.ts'
-import { Store } from './store.ts'
 import type {
   LiveStoreContextRunning as LiveStoreContextRunning_,
   OtelOptions,
   ShutdownDeferred,
 } from './store-types.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
+import { STORE_DEFAULT_PARAMS, Store } from './store.ts'
 
-export const DEFAULT_PARAMS = {
-  leaderPushBatchSize: 100,
+declare global {
+  /** Store instances for console debugging */
+  var __debugLiveStore: Record<string, Store<any, any>> | undefined
 }
 
+/**
+ * @deprecated Use `makeStoreContext()` from `@livestore/livestore/effect` instead.
+ * This service doesn't preserve schema types. See the Effect integration docs for migration.
+ *
+ * @example Migration
+ * ```ts
+ * // Before (untyped)
+ * import { LiveStoreContextRunning } from '@livestore/livestore/effect'
+ * const { store } = yield* LiveStoreContextRunning
+ *
+ * // After (typed)
+ * import { makeStoreContext } from '@livestore/livestore/effect'
+ * const AppStore = makeStoreContext<typeof schema>()('app')
+ * const { store } = yield* AppStore.Tag
+ * ```
+ */
 export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/effect/LiveStoreContextRunning')<
   LiveStoreContextRunning,
   LiveStoreContextRunning_
@@ -58,12 +75,19 @@ export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/e
   }).pipe(Layer.unwrapScoped)
 }
 
+/**
+ * @deprecated Use `StoreContext.DeferredTag` from `makeStoreContext()` instead.
+ */
 export class DeferredStoreContext extends Context.Tag('@livestore/livestore/effect/DeferredStoreContext')<
   DeferredStoreContext,
-  Deferred.Deferred<LiveStoreContextRunning['Type'], UnexpectedError>
+  Deferred.Deferred<LiveStoreContextRunning['Type'], UnknownError>
 >() {}
 
-export type LiveStoreContextProps<TSchema extends LiveStoreSchema, TContext = {}> = {
+export type LiveStoreContextProps<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> = {
   schema: TSchema
   /**
    * The `storeId` can be used to isolate multiple stores from each other.
@@ -88,12 +112,47 @@ export type LiveStoreContextProps<TSchema extends LiveStoreSchema, TContext = {}
   disableDevtools?: boolean | 'auto'
   onBootStatus?: (status: BootStatus) => void
   batchUpdates: (run: () => void) => void
+  /**
+   * Schema describing the shape of the sync payload and used to encode it.
+   *
+   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
+   *   and pass it here to get end-to-end type safety and validation.
+   */
+  syncPayloadSchema?: TSyncPayloadSchema
+  /**
+   * Payload that is sent to the sync backend when connecting
+   *
+   * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
+   * - At runtime this value is encoded with `syncPayloadSchema` before being handed to the adapter.
+   *
+   * Example:
+   *   const SyncPayload = Schema.Struct({ authToken: Schema.String })
+   *   useStore({ ..., syncPayloadSchema: SyncPayload, syncPayload: { authToken: '...' } })
+   */
+  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
 }
 
-export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext = {}> {
+export interface CreateStoreOptions<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> extends LogConfig.WithLoggerOptions {
+  /** The LiveStore schema defining tables, events, and materializers. */
   schema: TSchema
+  /** Adapter used for data storage and synchronization. */
   adapter: Adapter
+  /**
+   * Unique identifier for the Store instance, stable for its lifetime.
+   *
+   * - **Valid characters**: Only alphanumeric characters, underscores (`_`), and hyphens (`-`)
+   *   are allowed. Must match `/^[a-zA-Z0-9_-]+$/`.
+   * - **Globally unique**: Use globally unique IDs (e.g., nanoid) to prevent collisions across stores.
+   * - **Use namespaces**: Prefix to avoid collisions and for easier identification when debugging
+   *   (e.g., `app-root`, `workspace-abc123`, `issue-456`)
+   */
   storeId: string
+  /** User-defined context that will be attached to the created Store (e.g. for dependency injection). */
   context?: TContext
   boot?: (
     store: Store<TSchema, TContext>,
@@ -102,6 +161,19 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
       parentSpan: otel.Span
     },
   ) => Effect.SyncOrPromiseOrEffect<void, unknown, OtelTracer.OtelTracer | LiveStoreContextRunning>
+  onBootStatus?: (status: BootStatus) => void
+  /**
+   * Needed in React so LiveStore can apply multiple events in a single render.
+   *
+   * @example
+   * ```ts
+   * // With React DOM
+   * import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
+   *
+   * // With React Native
+   * import { unstable_batchedUpdates as batchUpdates } from 'react-native'
+   * ```
+   */
   batchUpdates?: (run: () => void) => void
   /**
    * Whether to disable devtools.
@@ -109,7 +181,6 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
    * @default 'auto'
    */
   disableDevtools?: boolean | 'auto'
-  onBootStatus?: (status: BootStatus) => void
   shutdownDeferred?: ShutdownDeferred
   /**
    * Currently only used in the web adapter:
@@ -119,13 +190,29 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
    */
   confirmUnsavedChanges?: boolean
   /**
-   * Payload that will be passed to the sync backend when connecting
+   * Schema describing the shape of the sync payload and used to encode it.
+   *
+   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
+   *   and pass it here to get end-to-end type safety and validation.
+   */
+  syncPayloadSchema?: TSyncPayloadSchema
+  /**
+   * Payload that is sent to the sync backend when connecting
+   *
+   * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
+   * - At runtime this value is encoded with `syncPayloadSchema` and carried through the adapter
+   *   to the backend where it can be decoded with the same schema.
    *
    * @default undefined
    */
-  syncPayload?: Schema.JsonValue
+  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
+  /** Options provided to the Store constructor. */
   params?: {
+    /** Max events pushed to the leader per write batch. */
     leaderPushBatchSize?: number
+    /** Chunk size used when the stream replays confirmed events. */
+    eventQueryBatchSize?: number
     simulation?: {
       clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type
     }
@@ -135,15 +222,25 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
   }
 }
 
+export type CreateStoreOptionsPromise<
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> = CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema> & {
+  signal?: AbortSignal
+  otelOptions?: Partial<OtelOptions>
+}
+
 /** Create a new LiveStore Store */
-export const createStorePromise = async <TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}>({
+export const createStorePromise = async <
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>({
   signal,
   otelOptions,
   ...options
-}: CreateStoreOptions<TSchema, TContext> & {
-  signal?: AbortSignal
-  otelOptions?: Partial<OtelOptions>
-}): Promise<Store<TSchema, TContext>> =>
+}: CreateStoreOptionsPromise<TSchema, TContext, TSyncPayloadSchema>): Promise<Store<TSchema, TContext>> =>
   Effect.gen(function* () {
     const scope = yield* Scope.make()
     const runtime = yield* Effect.runtime()
@@ -162,12 +259,15 @@ export const createStorePromise = async <TSchema extends LiveStoreSchema = LiveS
     provideOtel(omitUndefineds({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer })),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
-    Effect.provide(Logger.prettyWithThread('window')),
-    Logger.withMinimumLogLevel(LogLevel.Debug),
+    LogConfig.withLoggerConfig(options, { threadName: 'window' }),
     Effect.runPromise,
   )
 
-export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}>({
+export const createStore = <
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>({
   schema,
   adapter,
   storeId,
@@ -181,9 +281,10 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
   debug,
   confirmUnsavedChanges = true,
   syncPayload,
-}: CreateStoreOptions<TSchema, TContext>): Effect.Effect<
+  syncPayloadSchema,
+}: CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema>): Effect.Effect<
   Store<TSchema, TContext>,
-  UnexpectedError,
+  UnknownError,
   Scope.Scope | OtelTracer.OtelTracer
 > =>
   Effect.gen(function* () {
@@ -194,6 +295,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
     yield* Effect.addFinalizer((_) => Scope.close(lifetimeScope, _))
 
     const debugInstanceId = debug?.instanceId ?? nanoid(10)
+    const resolvedSyncPayloadSchema = (syncPayloadSchema ?? Schema.JsonValue) as TSyncPayloadSchema
 
     return yield* Effect.gen(function* () {
       const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
@@ -223,7 +325,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
       const shutdown = (
         exit: Exit.Exit<
           IntentionalShutdownCause,
-          UnexpectedError | MaterializeError | SyncError | InvalidPullError | IsOfflineError
+          UnknownError | MaterializeError | BackendIdMismatchError
         >,
       ) =>
         Effect.gen(function* () {
@@ -235,7 +337,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
             ),
           )
 
-          if (shutdownDeferred) {
+          if (shutdownDeferred !== undefined) {
             yield* Deferred.done(shutdownDeferred, exit)
           }
 
@@ -250,6 +352,11 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
           Fiber.join,
         )
 
+      const syncPayloadEncoded =
+        syncPayload === undefined
+          ? undefined
+          : yield* Schema.encode(resolvedSyncPayloadSchema)(syncPayload).pipe(UnknownError.mapToUnknownError)
+
       const clientSession: ClientSession = yield* adapter({
         schema,
         storeId,
@@ -258,10 +365,11 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
         shutdown,
         connectDevtoolsToStore: connectDevtoolsToStore_,
         debugInstanceId,
-        syncPayload,
+        syncPayloadSchema: resolvedSyncPayloadSchema,
+        syncPayloadEncoded,
       }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
 
-      if (LS_DEV && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
+      if (LS_DEV === true && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
         yield* Effect.logDebug(
           '[@livestore/livestore:createStore] migrationsReport',
           ...clientSession.leaderThread.initialState.migrationsReport.migrations.map((m) =>
@@ -280,27 +388,28 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
         effectContext: { lifetimeScope, runtime },
         // TODO find a better way to detect if we're running LiveStore in the LiveStore devtools
         // But for now this is a good enough approximation with little downsides
-        __runningInDevtools: getDevtoolsEnabled(disableDevtools) === false,
+        __runningInDevtools: ! getDevtoolsEnabled(disableDevtools),
         confirmUnsavedChanges,
         // NOTE during boot we're not yet executing events in a batched context
         // but only set the provided `batchUpdates` function after boot
         batchUpdates: (run) => run(),
         storeId,
         params: {
-          leaderPushBatchSize: params?.leaderPushBatchSize ?? DEFAULT_PARAMS.leaderPushBatchSize,
+          leaderPushBatchSize: params?.leaderPushBatchSize ?? STORE_DEFAULT_PARAMS.leaderPushBatchSize,
+          eventQueryBatchSize: params?.eventQueryBatchSize ?? STORE_DEFAULT_PARAMS.eventQueryBatchSize,
           ...omitUndefineds({ simulation: params?.simulation }),
         },
       })
 
       // Starts background fibers (syncing, event processing, etc) for store
-      yield* store.boot
+      yield* store[StoreInternalsSymbol].boot
 
       if (boot !== undefined) {
         // TODO also incorporate `boot` function progress into `bootStatusQueue`
         yield* Effect.tryAll(() =>
           boot(store, { migrationsReport: clientSession.leaderThread.initialState.migrationsReport, parentSpan: span }),
         ).pipe(
-          UnexpectedError.mapToUnexpectedError,
+          UnknownError.mapToUnknownError,
           Effect.provide(Layer.succeed(LiveStoreContextRunning, { stage: 'running', store: store as any as Store })),
           Effect.withSpan('createStore:boot'),
         )
@@ -311,16 +420,26 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
 
       if (batchUpdates !== undefined) {
         // Replacing the default batchUpdates function with the provided one after boot
-        store.reactivityGraph.context!.effectsWrapper = batchUpdates
+        store[StoreInternalsSymbol].reactivityGraph.context!.effectsWrapper = batchUpdates
       }
 
       yield* Deferred.succeed(storeDeferred, store as any as Store)
 
+      // Expose store on globalThis for console debugging
+      globalThis.__debugLiveStore ??= {}
+      globalThis.__debugLiveStore[storeId] = store
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          delete globalThis.__debugLiveStore?.[storeId]
+        }),
+      )
+
       return store
     }).pipe(
       Effect.withSpan('createStore', { attributes: { debugInstanceId, storeId } }),
       Effect.annotateLogs({ debugInstanceId, storeId }),
-      LS_DEV ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
+      LS_DEV === true ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
       Scope.extend(lifetimeScope),
     )
   })
@@ -329,8 +448,8 @@ const validateStoreId = (storeId: string) =>
   Effect.gen(function* () {
     const validChars = /^[a-zA-Z0-9_-]+$/
 
-    if (!validChars.test(storeId)) {
-      return yield* UnexpectedError.make({
+    if (validChars.test(storeId) === false) {
+      return yield* UnknownError.make({
         cause: `Invalid storeId: ${storeId}. Only alphanumeric characters, underscores, and hyphens are allowed.`,
         payload: { storeId },
       })

package/src/store/devtools.ts

@@ -1,23 +1,21 @@
-import type { ClientSession, ClientSessionSyncProcessor, DebugInfo, SyncState } from '@livestore/common'
-import { Devtools, liveStoreVersion, UnexpectedError } from '@livestore/common'
+import type { DebugInfo, SyncState } from '@livestore/common'
+import {
+  Devtools,
+  devtoolsProtocolVersion,
+  isDevtoolsProtocolVersionSupported,
+  liveStoreVersion,
+  resolveDevtoolsProtocolVersion,
+  UnknownError,
+} from '@livestore/common'
 import { throttle } from '@livestore/utils'
 import type { WebChannel } from '@livestore/utils/effect'
 import { Effect, Stream } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
 
-import type { LiveQuery, ReactivityGraph } from '../live-queries/base-class.ts'
 import { NOT_REFRESHED_YET } from '../reactive.ts'
-import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
 import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.ts'
-import type { ReferenceCountedSet } from '../utils/data-structures.ts'
-
-type IStore = {
-  clientSession: ClientSession
-  reactivityGraph: ReactivityGraph
-  sqliteDbWrapper: SqliteDbWrapper
-  activeQueries: ReferenceCountedSet<LiveQuery<any>>
-  syncProcessor: ClientSessionSyncProcessor
-}
+import { StoreInternalsSymbol } from './store-types.ts'
+import type { Store } from './store.ts'
 
 type Unsub = () => void
 type RequestId = string
@@ -32,7 +30,7 @@ const requestNextTick: (cb: () => void) => number =
 const cancelTick: (id: number) => void =
   globalThis.cancelAnimationFrame === undefined ? (id: number) => clearTimeout(id) : globalThis.cancelAnimationFrame
 
-export const connectDevtoolsToStore = ({
+export const connectDevtoolsToStore = Effect.fn('LSD.devtools.connectStoreToDevtools')(function* ({
   storeDevtoolsChannel,
   store,
 }: {
@@ -40,15 +38,14 @@ export const connectDevtoolsToStore = ({
     Devtools.ClientSession.MessageToApp,
     Devtools.ClientSession.MessageFromApp
   >
-  store: IStore
-}) =>
-  Effect.gen(function* () {
+  store: Store
+}) {
     const reactivityGraphSubcriptions: SubMap = new Map()
     const liveQueriesSubscriptions: SubMap = new Map()
     const debugInfoHistorySubscriptions: SubMap = new Map()
     const syncHeadClientSessionSubscriptions: SubMap = new Map()
 
-    const { clientId, sessionId } = store.clientSession
+    const { clientId, sessionId } = store[StoreInternalsSymbol].clientSession
 
     yield* Effect.addFinalizer(() =>
       Effect.sync(() => {
@@ -73,7 +70,21 @@ export const connectDevtoolsToStore = ({
       }
 
       if (decodedMessage._tag === 'LSD.ClientSession.Disconnect') {
-        // console.error('TODO handle disconnect properly in store')
+        // Gracefully tear down all DevTools subscriptions and close the channel.
+        // This prevents background fibers from lingering after DevTools closes
+        // (e.g. when a window is closed without sending explicit unsubs).
+        for (const unsub of reactivityGraphSubcriptions.values()) unsub()
+        reactivityGraphSubcriptions.clear()
+        for (const unsub of liveQueriesSubscriptions.values()) unsub()
+        liveQueriesSubscriptions.clear()
+        for (const unsub of debugInfoHistorySubscriptions.values()) unsub()
+        debugInfoHistorySubscriptions.clear()
+        for (const unsub of syncHeadClientSessionSubscriptions.values()) unsub()
+        syncHeadClientSessionSubscriptions.clear()
+
+        // Signal the WebChannel to shut down; this causes the `listen` stream
+        // to complete and allows the surrounding scoped fiber to exit.
+        storeDevtoolsChannel.shutdown.pipe(Effect.runFork)
         return
       }
 
@@ -83,7 +94,7 @@ export const connectDevtoolsToStore = ({
       // So far I could only observe this problem with webmesh proxy channels (e.g. for Expo)
       // Proof: https://share.cleanshot.com/V9G87B0B
       // Also see `leader-worker-devtools.ts` for same problem
-      if (handledRequestIds.has(requestId)) {
+      if (handledRequestIds.has(requestId) === true) {
         return
       }
 
@@ -103,7 +114,7 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.ReactivityGraphRes.make({
-                    reactivityGraph: store.reactivityGraph.getSnapshot({ includeResults }),
+                    reactivityGraph: store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults }),
                     requestId: nanoid(10),
                     clientId,
                     sessionId,
@@ -121,14 +132,17 @@ export const connectDevtoolsToStore = ({
           // This might need to be tweaked further and possibly be exposed to the user in some way.
           const throttledSend = throttle(send, 20)
 
-          reactivityGraphSubcriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          reactivityGraphSubcriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
         case 'LSD.ClientSession.DebugInfoReq': {
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRes.make({
-              debugInfo: store.sqliteDbWrapper.debugInfo,
+              debugInfo: store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo,
               requestId,
               clientId,
               sessionId,
@@ -144,13 +158,13 @@ export const connectDevtoolsToStore = ({
           let tickHandle: number | undefined
 
           const tick = () => {
-            buffer.push(store.sqliteDbWrapper.debugInfo)
+            buffer.push(store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo)
 
             // NOTE this resets the debug info, so all other "readers" e.g. in other `requestAnimationFrame` loops,
             // will get the empty debug info
             // TODO We need to come up with a more graceful way to do store. Probably via a single global
             // `requestAnimationFrame` loop that is passed in somehow.
-            store.sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
+            store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
 
             if (buffer.length > 10) {
               sendToDevtools(
@@ -194,7 +208,7 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.DebugInfoResetReq': {
-          store.sqliteDbWrapper.debugInfo.slowQueries.clear()
+          store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo.slowQueries.clear()
           sendToDevtools(
             Devtools.ClientSession.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -202,7 +216,10 @@ export const connectDevtoolsToStore = ({
         }
         case 'LSD.ClientSession.DebugInfoRerunQueryReq': {
           const { queryStr, bindValues, queriedTables } = decodedMessage
-          store.sqliteDbWrapper.cachedSelect(queryStr, bindValues, { queriedTables, skipCache: true })
+          store[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(queryStr, bindValues, {
+            queriedTables,
+            skipCache: true,
+          })
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -223,7 +240,8 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.LiveQueriesRes.make({
-                    liveQueries: [...store.activeQueries].map((q) => ({
+                    liveQueries: [...store[StoreInternalsSymbol].activeQueries].map((q) => ({
+                      /** TODO: include schema metadata for schema-aware rendering in devtools (e.g., schema AST/hash/identifier or table+columns for QueryBuilder-derived queries). */
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
@@ -251,7 +269,10 @@ export const connectDevtoolsToStore = ({
           // Same as in the reactivity graph subscription case above, we need to throttle the updates
           const throttledSend = throttle(send, 20)
 
-          liveQueriesSubscriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          liveQueriesSubscriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
@@ -278,11 +299,11 @@ export const connectDevtoolsToStore = ({
               }),
             )
 
-          send(store.syncProcessor.syncState.pipe(Effect.runSync))
+          send(store[StoreInternalsSymbol].syncProcessor.syncState.pipe(Effect.runSync))
 
           syncHeadClientSessionSubscriptions.set(
             subscriptionId,
-            store.syncProcessor.syncState.changes.pipe(
+            store[StoreInternalsSymbol].syncProcessor.syncState.changes.pipe(
               Stream.tap((syncState) => send(syncState)),
               Stream.runDrain,
               Effect.interruptible,
@@ -302,7 +323,30 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.Ping': {
-          sendToDevtools(Devtools.ClientSession.Pong.make({ requestId, clientId, sessionId, liveStoreVersion }))
+          if (isDevtoolsProtocolVersionSupported(decodedMessage.devtoolsProtocolVersion) === false) {
+            sendToDevtools(
+              Devtools.ClientSession.VersionMismatch.make({
+                requestId,
+                clientId,
+                sessionId,
+                liveStoreVersion,
+                appVersion: liveStoreVersion,
+                receivedVersion: decodedMessage.liveStoreVersion,
+                appDevtoolsProtocolVersion: devtoolsProtocolVersion,
+                receivedDevtoolsProtocolVersion: resolveDevtoolsProtocolVersion(decodedMessage.devtoolsProtocolVersion),
+              }),
+            )
+            break
+          }
+          sendToDevtools(
+            Devtools.ClientSession.Pong.make({
+              requestId,
+              clientId,
+              sessionId,
+              liveStoreVersion,
+              devtoolsProtocolVersion,
+            }),
+          )
           break
         }
         default: {
@@ -318,4 +362,4 @@ export const connectDevtoolsToStore = ({
       Stream.runDrain,
       Effect.withSpan('LSD.devtools.onMessage'),
     )
-  }).pipe(UnexpectedError.mapToUnexpectedError, Effect.withSpan('LSD.devtools.connectStoreToDevtools'))
+}, UnknownError.mapToUnknownError)