@livestore/common 0.3.0-dev.11 → 0.3.0-dev.13

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -1,4 +1,4 @@
-import { isNotUndefined, shouldNeverHappen, TRACE_VERBOSE } from '@livestore/utils'
+import { isNotUndefined, LS_DEV, shouldNeverHappen, TRACE_VERBOSE } from '@livestore/utils'
 import type { HttpClient, Scope, Tracer } from '@livestore/utils/effect'
 import {
   BucketQueue,
@@ -32,7 +32,7 @@ import * as SyncState from '../sync/syncstate.js'
 import { sql } from '../util.js'
 import { makeApplyMutation } from './apply-mutation.js'
 import { execSql } from './connection.js'
-import { getBackendHeadFromDb, getLocalHeadFromDb, getMutationEventsSince, updateBackendHead } from './mutationlog.js'
+import { getBackendHeadFromDb, getClientHeadFromDb, getMutationEventsSince, updateBackendHead } from './mutationlog.js'
 import type { InitialBlockingSyncContext, InitialSyncInfo, LeaderSyncProcessor } from './types.js'
 import { LeaderThreadCtx } from './types.js'
 
@@ -83,7 +83,7 @@ export const makeLeaderSyncProcessor = ({
 
     const isLocalEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) => {
       const mutationDef = schema.mutations.get(mutationEventEncoded.mutation)!
-      return mutationDef.options.localOnly
+      return mutationDef.options.clientOnly
     }
 
     // This context depends on data from `boot`, we should find a better implementation to avoid this ref indirection.
@@ -93,8 +93,7 @@ export const makeLeaderSyncProcessor = ({
         | {
             otelSpan: otel.Span | undefined
             span: Tracer.Span
-            devtoolsPullLatch: Effect.Latch | undefined
-            devtoolsPushLatch: Effect.Latch | undefined
+            devtoolsLatch: Effect.Latch | undefined
           },
     }
 
@@ -107,10 +106,6 @@ export const makeLeaderSyncProcessor = ({
         // TODO validate batch
         if (newEvents.length === 0) return
 
-        if (ctxRef.current?.devtoolsPushLatch !== undefined) {
-          yield* ctxRef.current.devtoolsPushLatch.await
-        }
-
         const waitForProcessing = options?.waitForProcessing ?? false
 
         if (waitForProcessing) {
@@ -137,18 +132,24 @@ export const makeLeaderSyncProcessor = ({
         }),
       )
 
-    const pushPartial: LeaderSyncProcessor['pushPartial'] = (mutationEventEncoded_) =>
+    const pushPartial: LeaderSyncProcessor['pushPartial'] = ({
+      mutationEvent: partialMutationEvent,
+      clientId,
+      sessionId,
+    }) =>
       Effect.gen(function* () {
         const syncState = yield* syncStateSref
         if (syncState === undefined) return shouldNeverHappen('Not initialized')
 
         const mutationDef =
-          schema.mutations.get(mutationEventEncoded_.mutation) ??
-          shouldNeverHappen(`Unknown mutation: ${mutationEventEncoded_.mutation}`)
+          schema.mutations.get(partialMutationEvent.mutation) ??
+          shouldNeverHappen(`Unknown mutation: ${partialMutationEvent.mutation}`)
 
         const mutationEventEncoded = new MutationEvent.EncodedWithMeta({
-          ...mutationEventEncoded_,
-          ...EventId.nextPair(syncState.localHead, mutationDef.options.localOnly),
+          ...partialMutationEvent,
+          clientId,
+          sessionId,
+          ...EventId.nextPair(syncState.localHead, mutationDef.options.clientOnly),
         })
 
         yield* push([mutationEventEncoded])
@@ -164,12 +165,11 @@ export const makeLeaderSyncProcessor = ({
         ctxRef.current = {
           otelSpan,
           span,
-          devtoolsPullLatch: devtools.enabled ? devtools.syncBackendPullLatch : undefined,
-          devtoolsPushLatch: devtools.enabled ? devtools.syncBackendPushLatch : undefined,
+          devtoolsLatch: devtools.enabled ? devtools.syncBackendLatch : undefined,
         }
 
         const initialBackendHead = dbMissing ? EventId.ROOT.global : getBackendHeadFromDb(dbMutationLog)
-        const initialLocalHead = dbMissing ? EventId.ROOT : getLocalHeadFromDb(dbMutationLog)
+        const initialLocalHead = dbMissing ? EventId.ROOT : getClientHeadFromDb(dbMutationLog)
 
         if (initialBackendHead > initialLocalHead.global) {
           return shouldNeverHappen(
@@ -179,14 +179,14 @@ export const makeLeaderSyncProcessor = ({
 
         const pendingMutationEvents = yield* getMutationEventsSince({
           global: initialBackendHead,
-          local: EventId.localDefault,
+          client: EventId.clientDefault,
         }).pipe(Effect.map(ReadonlyArray.map((_) => new MutationEvent.EncodedWithMeta(_))))
 
         const initialSyncState = new SyncState.SyncState({
           pending: pendingMutationEvents,
           // On the leader we don't need a rollback tail beyond `pending` items
           rollbackTail: [],
-          upstreamHead: { global: initialBackendHead, local: EventId.localDefault },
+          upstreamHead: { global: initialBackendHead, client: EventId.clientDefault },
           localHead: initialLocalHead,
         })
 
@@ -196,10 +196,10 @@ export const makeLeaderSyncProcessor = ({
         // Rehydrate sync queue
         if (pendingMutationEvents.length > 0) {
           const filteredBatch = pendingMutationEvents
-            // Don't sync localOnly mutations
+            // Don't sync clientOnly mutations
             .filter((mutationEventEncoded) => {
               const mutationDef = schema.mutations.get(mutationEventEncoded.mutation)!
-              return mutationDef.options.localOnly === false
+              return mutationDef.options.clientOnly === false
             })
 
           yield* BucketQueue.offerAll(syncBackendQueue, filteredBatch)
@@ -220,7 +220,12 @@ export const makeLeaderSyncProcessor = ({
 
         yield* FiberHandle.run(
           backendPushingFiberHandle,
-          backgroundBackendPushing({ dbReady, syncBackendQueue, otelSpan }).pipe(Effect.tapCauseLogPretty),
+          backgroundBackendPushing({
+            dbReady,
+            syncBackendQueue,
+            otelSpan,
+            devtoolsLatch: ctxRef.current?.devtoolsLatch,
+          }).pipe(Effect.tapCauseLogPretty),
         )
 
         yield* backgroundBackendPulling({
@@ -239,7 +244,12 @@ export const makeLeaderSyncProcessor = ({
               // Restart pushing fiber
               yield* FiberHandle.run(
                 backendPushingFiberHandle,
-                backgroundBackendPushing({ dbReady, syncBackendQueue, otelSpan }).pipe(Effect.tapCauseLogPretty),
+                backgroundBackendPushing({
+                  dbReady,
+                  syncBackendQueue,
+                  otelSpan,
+                  devtoolsLatch: ctxRef.current?.devtoolsLatch,
+                }).pipe(Effect.tapCauseLogPretty),
               )
             }),
           syncStateSref,
@@ -247,8 +257,10 @@ export const makeLeaderSyncProcessor = ({
           pullLatch,
           otelSpan,
           initialBlockingSyncContext,
-          devtoolsPullLatch: ctxRef.current?.devtoolsPullLatch,
+          devtoolsLatch: ctxRef.current?.devtoolsLatch,
         }).pipe(Effect.tapCauseLogPretty, Effect.forkScoped)
+
+        return { initialLeaderHead: initialLocalHead }
       }).pipe(Effect.withSpanScoped('@livestore/common:leader-thread:syncing'))
 
     return {
@@ -357,10 +369,10 @@ const backgroundApplyLocalPushes = ({
         updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
       })
 
-      // Don't sync localOnly mutations
+      // Don't sync clientOnly mutations
       const filteredBatch = updateResult.newEvents.filter((mutationEventEncoded) => {
         const mutationDef = schema.mutations.get(mutationEventEncoded.mutation)!
-        return mutationDef.options.localOnly === false
+        return mutationDef.options.clientOnly === false
       })
 
       yield* BucketQueue.offerAll(syncBackendQueue, filteredBatch)
@@ -431,7 +443,7 @@ const backgroundBackendPulling = ({
   syncStateSref,
   localPushesLatch,
   pullLatch,
-  devtoolsPullLatch,
+  devtoolsLatch,
   initialBlockingSyncContext,
 }: {
   dbReady: Deferred.Deferred<void>
@@ -444,7 +456,7 @@ const backgroundBackendPulling = ({
   syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
   localPushesLatch: Effect.Latch
   pullLatch: Effect.Latch
-  devtoolsPullLatch: Effect.Latch | undefined
+  devtoolsLatch: Effect.Latch | undefined
   initialBlockingSyncContext: InitialBlockingSyncContext
 }) =>
   Effect.gen(function* () {
@@ -466,8 +478,8 @@ const backgroundBackendPulling = ({
       Effect.gen(function* () {
         if (newEvents.length === 0) return
 
-        if (devtoolsPullLatch !== undefined) {
-          yield* devtoolsPullLatch.await
+        if (devtoolsLatch !== undefined) {
+          yield* devtoolsLatch.await
         }
 
         // Prevent more local pushes from being processed until this pull is finished
@@ -507,7 +519,7 @@ const backgroundBackendPulling = ({
 
           const filteredRebasedPending = updateResult.newSyncState.pending.filter((mutationEvent) => {
             const mutationDef = schema.mutations.get(mutationEvent.mutation)!
-            return mutationDef.options.localOnly === false
+            return mutationDef.options.clientOnly === false
           })
           yield* restartBackendPushing(filteredRebasedPending)
 
@@ -592,9 +604,9 @@ const rollback = ({
   Effect.gen(function* () {
     const rollbackEvents = db
       .select<SessionChangesetMetaRow>(
-        sql`SELECT * FROM ${SESSION_CHANGESET_META_TABLE} WHERE (idGlobal, idLocal) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.local})`).join(', ')})`,
+        sql`SELECT * FROM ${SESSION_CHANGESET_META_TABLE} WHERE (idGlobal, idClient) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.client})`).join(', ')})`,
       )
-      .map((_) => ({ id: { global: _.idGlobal, local: _.idLocal }, changeset: _.changeset, debug: _.debug }))
+      .map((_) => ({ id: { global: _.idGlobal, client: _.idClient }, changeset: _.changeset, debug: _.debug }))
       .toSorted((a, b) => EventId.compare(a.id, b.id))
 
     // Apply changesets in reverse order
@@ -607,12 +619,12 @@ const rollback = ({
 
     // Delete the changeset rows
     db.execute(
-      sql`DELETE FROM ${SESSION_CHANGESET_META_TABLE} WHERE (idGlobal, idLocal) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.local})`).join(', ')})`,
+      sql`DELETE FROM ${SESSION_CHANGESET_META_TABLE} WHERE (idGlobal, idClient) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.client})`).join(', ')})`,
     )
 
     // Delete the mutation log rows
     dbMutationLog.execute(
-      sql`DELETE FROM ${MUTATION_LOG_META_TABLE} WHERE (idGlobal, idLocal) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.local})`).join(', ')})`,
+      sql`DELETE FROM ${MUTATION_LOG_META_TABLE} WHERE (idGlobal, idClient) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.client})`).join(', ')})`,
     )
   }).pipe(
     Effect.withSpan('@livestore/common:leader-thread:syncing:rollback', {
@@ -632,12 +644,12 @@ const getCursorInfo = (remoteHead: EventId.GlobalEventId) =>
 
     const syncMetadataOption = yield* Effect.sync(() =>
       dbMutationLog.select<{ syncMetadataJson: string }>(
-        sql`SELECT syncMetadataJson FROM ${MUTATION_LOG_META_TABLE} WHERE idGlobal = ${remoteHead} ORDER BY idLocal ASC LIMIT 1`,
+        sql`SELECT syncMetadataJson FROM ${MUTATION_LOG_META_TABLE} WHERE idGlobal = ${remoteHead} ORDER BY idClient ASC LIMIT 1`,
       ),
     ).pipe(Effect.andThen(Schema.decode(MutationlogQuerySchema)), Effect.map(Option.flatten), Effect.orDie)
 
     return Option.some({
-      cursor: { global: remoteHead, local: EventId.localDefault },
+      cursor: { global: remoteHead, client: EventId.clientDefault },
       metadata: syncMetadataOption,
     }) satisfies InitialSyncInfo
   }).pipe(Effect.withSpan('@livestore/common:leader-thread:syncing:getCursorInfo', { attributes: { remoteHead } }))
@@ -646,10 +658,12 @@ const backgroundBackendPushing = ({
   dbReady,
   syncBackendQueue,
   otelSpan,
+  devtoolsLatch,
 }: {
   dbReady: Deferred.Deferred<void>
   syncBackendQueue: BucketQueue.BucketQueue<MutationEvent.EncodedWithMeta>
   otelSpan: otel.Span | undefined
+  devtoolsLatch: Effect.Latch | undefined
 }) =>
   Effect.gen(function* () {
     const { syncBackend, dbMutationLog } = yield* LeaderThreadCtx
@@ -665,6 +679,10 @@ const backgroundBackendPushing = ({
 
       yield* SubscriptionRef.waitUntil(syncBackend.isConnected, (isConnected) => isConnected === true)
 
+      if (devtoolsLatch !== undefined) {
+        yield* devtoolsLatch.await
+      }
+
       otelSpan?.addEvent('backend-push', {
         batchSize: queueItems.length,
         batch: TRACE_VERBOSE ? JSON.stringify(queueItems) : undefined,
@@ -674,6 +692,9 @@ const backgroundBackendPushing = ({
       const pushResult = yield* syncBackend.push(queueItems.map((_) => _.toGlobal())).pipe(Effect.either)
 
       if (pushResult._tag === 'Left') {
+        if (LS_DEV) {
+          yield* Effect.logDebug('backend-push-error', { error: pushResult.left.toString() })
+        }
         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
@@ -689,7 +710,7 @@ const backgroundBackendPushing = ({
           ...updateRows({
             tableName: MUTATION_LOG_META_TABLE,
             columns: mutationLogMetaTable.sqliteDef.columns,
-            where: { idGlobal: mutationEventEncoded.id.global, idLocal: mutationEventEncoded.id.local },
+            where: { idGlobal: mutationEventEncoded.id.global, idClient: mutationEventEncoded.id.client },
             updateValues: { syncMetadataJson: metadata[i]! },
           }),
         )

package/src/leader-thread/apply-mutation.ts

@@ -79,7 +79,7 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
             columns: sessionChangesetMetaTable.sqliteDef.columns,
             values: {
               idGlobal: mutationEventEncoded.id.global,
-              idLocal: mutationEventEncoded.id.local,
+              idClient: mutationEventEncoded.id.client,
               // NOTE the changeset will be empty (i.e. null) for no-op mutations
               changeset: changeset ?? null,
               debug: execArgsArr,
@@ -92,7 +92,13 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
         // write to mutation_log
         const excludeFromMutationLog = shouldExcludeMutationFromLog(mutationName, mutationEventEncoded)
         if (skipMutationLog === false && excludeFromMutationLog === false) {
-          yield* insertIntoMutationLog(mutationEventEncoded, dbMutationLog, mutationDefSchemaHashMap)
+          yield* insertIntoMutationLog(
+            mutationEventEncoded,
+            dbMutationLog,
+            mutationDefSchemaHashMap,
+            mutationEventEncoded.clientId,
+            mutationEventEncoded.sessionId,
+          )
         } else {
           //   console.debug('[@livestore/common:leader-thread] skipping mutation log write', mutation, statementSql, bindValues)
         }
@@ -101,7 +107,7 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
           attributes: {
             mutationName: mutationEventEncoded.mutation,
             mutationId: mutationEventEncoded.id,
-            'span.label': `(${mutationEventEncoded.id.global},${mutationEventEncoded.id.local}) ${mutationEventEncoded.mutation}`,
+            'span.label': `(${mutationEventEncoded.id.global},${mutationEventEncoded.id.client}) ${mutationEventEncoded.mutation}`,
           },
         }),
         // Effect.logDuration('@livestore/common:leader-thread:applyMutation'),
@@ -113,6 +119,8 @@ const insertIntoMutationLog = (
   mutationEventEncoded: MutationEvent.AnyEncoded,
   dbMutationLog: SqliteDb,
   mutationDefSchemaHashMap: Map<string, number>,
+  clientId: string,
+  sessionId: string | undefined,
 ) =>
   Effect.gen(function* () {
     const mutationName = mutationEventEncoded.mutation
@@ -127,11 +135,13 @@ const insertIntoMutationLog = (
         columns: mutationLogMetaTable.sqliteDef.columns,
         values: {
           idGlobal: mutationEventEncoded.id.global,
-          idLocal: mutationEventEncoded.id.local,
+          idClient: mutationEventEncoded.id.client,
           parentIdGlobal: mutationEventEncoded.parentId.global,
-          parentIdLocal: mutationEventEncoded.parentId.local,
+          parentIdClient: mutationEventEncoded.parentId.client,
           mutation: mutationEventEncoded.mutation,
           argsJson: mutationEventEncoded.args ?? {},
+          clientId,
+          sessionId: sessionId ?? null,
           schemaHash: mutationDefSchemaHash,
           syncMetadataJson: Option.none(),
         },

package/src/leader-thread/connection.ts

@@ -12,13 +12,58 @@ namespace WaSqlite {
   export type SQLiteError = any
 }
 
-export const configureConnection = (sqliteDb: SqliteDb, { fkEnabled }: { fkEnabled: boolean }) =>
+type ConnectionOptions = {
+  /**
+   * The database connection locking mode.
+   *
+   * @remarks
+   *
+   * This **option is ignored** when used on an **in-memory database** as they can only operate in exclusive locking mode.
+   * In-memory databases can’t share state between connections (unless using a
+   * {@link https://www.sqlite.org/sharedcache.html#shared_cache_and_in_memory_databases|shared cache}),
+   * making concurrent access impossible. This is functionally equivalent to exclusive locking.
+   *
+   * @defaultValue
+   * The default is `"NORMAL"` unless it was unless overridden at compile-time using `SQLITE_DEFAULT_LOCKING_MODE`.
+   *
+   * @see {@link https://www.sqlite.org/pragma.html#pragma_locking_mode|`locking_mode` pragma}
+   */
+  lockingMode?: 'NORMAL' | 'EXCLUSIVE'
+
+  /**
+   * Whether to enforce foreign key constraints.
+   *
+   * @privateRemarks
+   *
+   * We require a value for this option to minimize future problems, as the default value might change in future
+   * versions of SQLite.
+   *
+   * @see {@link https://www.sqlite.org/pragma.html#pragma_foreign_keys|`foreign_keys` pragma}
+   */
+  foreignKeys: boolean
+}
+
+export const configureConnection = (sqliteDb: SqliteDb, { foreignKeys, lockingMode }: ConnectionOptions) =>
   execSql(
     sqliteDb,
+    // We use the WAL journal mode is significantly faster in most scenarios than the traditional rollback journal mode.
+    // It specifically significantly improves write performance. However, when using the WAL journal mode, transactions
+    // that involve changes against multiple ATTACHed databases are atomic for each database but are not atomic
+    // across all databases as a set. Additionally, it is not possible to change the page size after entering WAL mode,
+    // whether on an empty database or by using VACUUM or the backup API. To change the page size, we must switch to the
+    // rollback journal mode.
+    //
+    // When connected to an in-memory database, the WAL journal mode option is ignored because an in-memory database can
+    // only be in either the MEMORY or OFF options. By default, an in-memory database is in the MEMORY option, which
+    // means that it stores the rollback journal in volatile RAM. This saves disk I/O but at the expense of safety and
+    // integrity. If the thread using SQLite crashes in the middle of a transaction, then the database file will very
+    // likely go corrupt.
     sql`
+    -- disable WAL until we have it working properly
+    -- PRAGMA journal_mode=WAL;
     PRAGMA page_size=8192;
-    PRAGMA journal_mode=MEMORY;
-    ${fkEnabled ? sql`PRAGMA foreign_keys='ON';` : sql`PRAGMA foreign_keys='OFF';`}
+    PRAGMA foreign_keys=${foreignKeys ? 'ON' : 'OFF'};
+    ${lockingMode === undefined ? '' : sql`PRAGMA locking_mode=${lockingMode};`}
   `,
     {},
   )

package/src/leader-thread/leader-worker-devtools.ts

@@ -5,7 +5,7 @@ import { MUTATION_LOG_META_TABLE, SCHEMA_META_TABLE, SCHEMA_MUTATIONS_META_TABLE
 import type { DevtoolsOptions, PersistenceInfoPair } from './types.js'
 import { LeaderThreadCtx } from './types.js'
 
-type SendMessageToDevtools = (message: Devtools.MessageFromAppLeader) => Effect.Effect<void>
+type SendMessageToDevtools = (message: Devtools.Leader.MessageFromApp) => Effect.Effect<void>
 
 // TODO bind scope to the webchannel lifetime
 export const bootDevtools = (options: DevtoolsOptions) =>
@@ -38,18 +38,7 @@ export const bootDevtools = (options: DevtoolsOptions) =>
     const pullQueue = yield* connectedClientSessionPullQueues.makeQueue(localHead)
 
     yield* Stream.fromQueue(pullQueue).pipe(
-      Stream.tap((msg) =>
-        Effect.gen(function* () {
-          if (msg.payload._tag === 'upstream-advance') {
-            for (const mutationEventEncoded of msg.payload.newEvents) {
-              // TODO refactor with push semantics
-              yield* sendMessage(Devtools.MutationBroadcast.make({ mutationEventEncoded, liveStoreVersion }))
-            }
-          } else {
-            yield* Effect.logWarning('TODO implement rebases in devtools')
-          }
-        }),
-      ),
+      Stream.tap((msg) => sendMessage(Devtools.Leader.SyncPull.make({ payload: msg.payload, liveStoreVersion }))),
       Stream.runDrain,
       Effect.forkScoped,
     )
@@ -66,7 +55,7 @@ const listenToDevtools = ({
   sendMessage,
   persistenceInfo,
 }: {
-  incomingMessages: Stream.Stream<Devtools.MessageToAppLeader>
+  incomingMessages: Stream.Stream<Devtools.Leader.MessageToApp>
   sendMessage: SendMessageToDevtools
   persistenceInfo?: PersistenceInfoPair
 }) =>
@@ -79,6 +68,8 @@ const listenToDevtools = ({
       shutdownStateSubRef,
       shutdownChannel,
       syncProcessor,
+      clientId,
+      devtools,
     } = yield* LeaderThreadCtx
 
     type RequestId = string
@@ -89,22 +80,22 @@ const listenToDevtools = ({
         Effect.gen(function* () {
           // yield* Effect.logDebug('[@livestore/common:leader-thread:devtools] incomingMessage', decodedEvent)
 
-          if (decodedEvent._tag === 'LSD.Disconnect') {
+          if (decodedEvent._tag === 'LSD.Leader.Disconnect') {
             return
           }
 
           const { requestId } = decodedEvent
-          const reqPayload = { requestId, liveStoreVersion }
+          const reqPayload = { requestId, liveStoreVersion, clientId }
 
           switch (decodedEvent._tag) {
-            case 'LSD.Ping': {
-              yield* sendMessage(Devtools.Pong.make({ ...reqPayload }))
+            case 'LSD.Leader.Ping': {
+              yield* sendMessage(Devtools.Leader.Pong.make({ ...reqPayload }))
               return
             }
             case 'LSD.Leader.SnapshotReq': {
               const snapshot = dbReadModel.export()
 
-              yield* sendMessage(Devtools.SnapshotRes.make({ snapshot, ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.SnapshotRes.make({ snapshot, ...reqPayload }))
 
               return
             }
@@ -125,7 +116,9 @@ const listenToDevtools = ({
                 tmpDb.close()
               } catch (e) {
                 yield* Effect.logError(`Error importing database file`, e)
-                yield* sendMessage(Devtools.LoadDatabaseFileRes.make({ ...reqPayload, status: 'unsupported-file' }))
+                yield* sendMessage(
+                  Devtools.Leader.LoadDatabaseFileRes.make({ ...reqPayload, status: 'unsupported-file' }),
+                )
 
                 return
               }
@@ -143,17 +136,19 @@ const listenToDevtools = ({
 
                 dbMutationLog.destroy()
               } else {
-                yield* sendMessage(Devtools.LoadDatabaseFileRes.make({ ...reqPayload, status: 'unsupported-database' }))
+                yield* sendMessage(
+                  Devtools.Leader.LoadDatabaseFileRes.make({ ...reqPayload, status: 'unsupported-database' }),
+                )
                 return
               }
 
-              yield* sendMessage(Devtools.LoadDatabaseFileRes.make({ ...reqPayload, status: 'ok' }))
+              yield* sendMessage(Devtools.Leader.LoadDatabaseFileRes.make({ ...reqPayload, status: 'ok' }))
 
               yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'devtools-import' })) ?? Effect.void
 
               return
             }
-            case 'LSD.Leader.ResetAllDataReq': {
+            case 'LSD.Leader.ResetAllData.Request': {
               const { mode } = decodedEvent
 
               yield* SubscriptionRef.set(shutdownStateSubRef, 'shutting-down')
@@ -164,7 +159,7 @@ const listenToDevtools = ({
                 dbMutationLog.destroy()
               }
 
-              yield* sendMessage(Devtools.ResetAllDataRes.make({ ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.ResetAllData.Response.make({ ...reqPayload }))
 
               yield* shutdownChannel.send(IntentionalShutdownCause.make({ reason: 'devtools-reset' })) ?? Effect.void
 
@@ -181,7 +176,7 @@ const listenToDevtools = ({
               const mutationLogFileSize = dbMutationLog.select<{ size: number }>(dbSizeQuery, undefined)[0]!.size
 
               yield* sendMessage(
-                Devtools.DatabaseFileInfoRes.make({
+                Devtools.Leader.DatabaseFileInfoRes.make({
                   readModel: { fileSize: dbFileSize, persistenceInfo: persistenceInfo.readModel },
                   mutationLog: { fileSize: mutationLogFileSize, persistenceInfo: persistenceInfo.mutationLog },
                   ...reqPayload,
@@ -193,14 +188,18 @@ const listenToDevtools = ({
             case 'LSD.Leader.MutationLogReq': {
               const mutationLog = dbMutationLog.export()
 
-              yield* sendMessage(Devtools.MutationLogRes.make({ mutationLog, ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.MutationLogRes.make({ mutationLog, ...reqPayload }))
 
               return
             }
             case 'LSD.Leader.RunMutationReq': {
-              yield* syncProcessor.pushPartial(decodedEvent.mutationEventEncoded)
+              yield* syncProcessor.pushPartial({
+                mutationEvent: decodedEvent.mutationEventEncoded,
+                clientId: `devtools-${clientId}`,
+                sessionId: undefined,
+              })
 
-              yield* sendMessage(Devtools.RunMutationRes.make({ ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.RunMutationRes.make({ ...reqPayload }))
 
               return
             }
@@ -213,7 +212,7 @@ const listenToDevtools = ({
                   Stream.map((_) => _.batch),
                   Stream.flattenIterables,
                   Stream.tap(({ mutationEventEncoded, metadata }) =>
-                    sendMessage(Devtools.SyncHistoryRes.make({ mutationEventEncoded, metadata, ...reqPayload })),
+                    sendMessage(Devtools.Leader.SyncHistoryRes.make({ mutationEventEncoded, metadata, ...reqPayload })),
                   ),
                   Stream.runDrain,
                   Effect.acquireRelease(() => Effect.log('syncHistorySubscribe done')),
@@ -234,12 +233,12 @@ const listenToDevtools = ({
               return
             }
             case 'LSD.Leader.SyncingInfoReq': {
-              const syncingInfo = Devtools.SyncingInfo.make({
+              const syncingInfo = Devtools.Leader.SyncingInfo.make({
                 enabled: syncBackend !== undefined,
                 metadata: {},
               })
 
-              yield* sendMessage(Devtools.SyncingInfoRes.make({ syncingInfo, ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.SyncingInfoRes.make({ syncingInfo, ...reqPayload }))
 
               return
             }
@@ -252,11 +251,14 @@ const listenToDevtools = ({
                 // This is probably the same "flaky databrowser loading" bug as we're seeing in the playwright tests
                 yield* Effect.sleep(1000)
 
-                yield* syncBackend.isConnected.changes.pipe(
-                  Stream.tap((isConnected) =>
+                yield* Stream.zipLatest(
+                  syncBackend.isConnected.changes,
+                  devtools.enabled ? devtools.syncBackendLatchState.changes : Stream.make({ latchClosed: false }),
+                ).pipe(
+                  Stream.tap(([isConnected, { latchClosed }]) =>
                     sendMessage(
-                      Devtools.NetworkStatusRes.make({
-                        networkStatus: { isConnected, timestampMs: Date.now() },
+                      Devtools.Leader.NetworkStatusRes.make({
+                        networkStatus: { isConnected, timestampMs: Date.now(), latchClosed },
                         ...reqPayload,
                       }),
                     ),
@@ -277,6 +279,54 @@ const listenToDevtools = ({
 
               return
             }
+            case 'LSD.Leader.SyncHeadSubscribe': {
+              const { requestId } = decodedEvent
+
+              yield* syncProcessor.syncState.changes.pipe(
+                Stream.tap((syncState) =>
+                  sendMessage(
+                    Devtools.Leader.SyncHeadRes.make({
+                      local: syncState.localHead,
+                      upstream: syncState.upstreamHead,
+                      ...reqPayload,
+                    }),
+                  ),
+                ),
+                Stream.runDrain,
+                Effect.interruptible,
+                Effect.tapCauseLogPretty,
+                FiberMap.run(subscriptionFiberMap, requestId),
+              )
+
+              return
+            }
+            case 'LSD.Leader.SyncHeadUnsubscribe': {
+              const { requestId } = decodedEvent
+
+              yield* FiberMap.remove(subscriptionFiberMap, requestId)
+
+              return
+            }
+            case 'LSD.Leader.SetSyncLatch.Request': {
+              const { closeLatch } = decodedEvent
+
+              if (devtools.enabled === false) return
+
+              if (closeLatch === true) {
+                yield* devtools.syncBackendLatch.close
+              } else {
+                yield* devtools.syncBackendLatch.open
+              }
+
+              yield* SubscriptionRef.set(devtools.syncBackendLatchState, { latchClosed: closeLatch })
+
+              yield* sendMessage(Devtools.Leader.SetSyncLatch.Response.make({ ...reqPayload }))
+
+              return
+            }
+            default: {
+              yield* Effect.logWarning(`TODO implement devtools message`, decodedEvent)
+            }
           }
         }).pipe(Effect.withSpan(`@livestore/common:leader-thread:onDevtoolsMessage:${decodedEvent._tag}`)),
       ),