@livestore/common 0.4.0-dev.8 → 0.4.0

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@livestore/common",
-  "version": "0.4.0-dev.8",
+  "version": "0.4.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livestorejs/livestore.git"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "src"
+  ],
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -8,29 +18,72 @@
     "./sql-queries": "./dist/sql-queries/index.js",
     "./leader-thread": "./dist/leader-thread/mod.js",
     "./schema": "./dist/schema/mod.js",
+    "./sync": "./dist/sync/index.js",
     "./sync/next": "./dist/sync/next/mod.js",
-    "./sync/next/test": "./dist/sync/next/test/mod.js"
+    "./sync/next/test": "./dist/sync/next/test/mod.js",
+    "./testing": "./dist/testing/mod.js"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "graphology": "0.26.0-alpha1",
-    "graphology-dag": "0.4.1",
-    "graphology-types": "0.24.8",
-    "@livestore/webmesh": "0.4.0-dev.8",
-    "@livestore/utils": "0.4.0-dev.8"
+    "@livestore/utils": "^0.4.0",
+    "@livestore/webmesh": "^0.4.0"
   },
   "devDependencies": {
+    "@effect/ai": "0.35.0",
+    "@effect/cli": "0.75.1",
+    "@effect/cluster": "0.58.2",
+    "@effect/experimental": "0.60.0",
+    "@effect/opentelemetry": "0.63.0",
+    "@effect/platform": "0.96.1",
+    "@effect/platform-browser": "0.76.0",
+    "@effect/platform-bun": "0.89.0",
+    "@effect/platform-node": "0.106.0",
+    "@effect/printer": "0.49.0",
+    "@effect/printer-ansi": "0.49.0",
+    "@effect/rpc": "0.75.1",
+    "@effect/sql": "0.51.1",
+    "@effect/typeclass": "0.40.0",
+    "@effect/vitest": "0.29.0",
+    "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/resources": "2.2.0",
+    "@standard-schema/spec": "1.1.0",
+    "effect": "3.21.2",
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.8"
+    "@livestore/utils-dev": "^0.4.0"
   },
-  "files": [
-    "package.json",
-    "src",
-    "dist"
-  ],
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
+  "peerDependencies": {
+    "@effect/ai": "^0.35.0",
+    "@effect/cli": "^0.75.1",
+    "@effect/cluster": "^0.58.2",
+    "@effect/experimental": "^0.60.0",
+    "@effect/opentelemetry": "^0.63.0",
+    "@effect/platform": "^0.96.1",
+    "@effect/platform-browser": "^0.76.0",
+    "@effect/platform-bun": "^0.89.0",
+    "@effect/platform-node": "^0.106.0",
+    "@effect/printer": "^0.49.0",
+    "@effect/printer-ansi": "^0.49.0",
+    "@effect/rpc": "^0.75.1",
+    "@effect/sql": "^0.51.1",
+    "@effect/typeclass": "^0.40.0",
+    "@effect/vitest": "^0.29.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@standard-schema/spec": "^1.1.0",
+    "effect": "^3.21.2"
+  },
+  "$genie": {
+    "source": "package.json.genie.ts",
+    "warning": "DO NOT EDIT - changes will be overwritten",
+    "workspaceClosureDirs": [
+      "packages/@livestore/common",
+      "packages/@livestore/utils",
+      "packages/@livestore/utils-dev",
+      "packages/@livestore/webmesh"
+    ]
   },
   "scripts": {
     "test": "vitest"

package/src/ClientSessionLeaderThreadProxy.ts

@@ -1,33 +1,48 @@
-import type { Effect, Stream } from '@livestore/utils/effect'
+import type { Effect, Stream, Subscribable } from '@livestore/utils/effect'
 
+import type { StorageMode } from './adapter-types.ts'
 import type { MigrationsReport } from './defs.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { UnexpectedError } from './errors.ts'
-import type * as EventSequenceNumber from './schema/EventSequenceNumber.ts'
+import type { StreamEventsOptions } from './leader-thread/types.ts'
+import type * as EventSequenceNumber from './schema/EventSequenceNumber/mod.ts'
 import type { LiveStoreEvent } from './schema/mod.ts'
-import type { LeaderAheadError } from './sync/sync.ts'
+import type { RejectedPushError } from './leader-thread/RejectedPushError.ts'
+import type { SyncBackend } from './sync/sync.ts'
 import type { PayloadUpstream, SyncState } from './sync/syncstate.ts'
 
 export interface ClientSessionLeaderThreadProxy {
   events: {
     pull: (args: {
-      cursor: EventSequenceNumber.EventSequenceNumber
-    }) => Stream.Stream<{ payload: typeof PayloadUpstream.Type }, UnexpectedError>
+      cursor: EventSequenceNumber.Client.Composite
+    }) => Stream.Stream<{ payload: typeof PayloadUpstream.Type }>
     /** It's important that a client session doesn't call `push` concurrently. */
-    push(batch: ReadonlyArray<LiveStoreEvent.AnyEncoded>): Effect.Effect<void, UnexpectedError | LeaderAheadError>
+    push(batch: ReadonlyArray<LiveStoreEvent.Client.Encoded>): Effect.Effect<void, RejectedPushError>
+    /** Stream events with filtering */
+    stream(options: StreamEventsOptions): Stream.Stream<LiveStoreEvent.Client.Encoded>
   }
   /** The initial state after the leader thread has booted */
   readonly initialState: {
     /** The latest event sequence number during boot. Used for the client session to resume syncing. */
-    readonly leaderHead: EventSequenceNumber.EventSequenceNumber
+    readonly leaderHead: EventSequenceNumber.Client.Composite
     /** The migrations report from the leader thread */
     readonly migrationsReport: MigrationsReport
+    /**
+     * Indicates how data is being stored.
+     * - `persisted`: Data is persisted to disk (e.g., via OPFS)
+     * - `in-memory`: Data is only stored in memory and will be lost on page refresh (e.g., private browsing)
+     */
+    readonly storageMode: StorageMode
   }
-  export: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getSyncState: Effect.Effect<SyncState, UnexpectedError>
+  export: Effect.Effect<Uint8Array<ArrayBuffer>>
+  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>>
+  syncState: Subscribable.Subscribable<SyncState>
   /** For debugging purposes it can be useful to manually trigger devtools messages (e.g. to reset the database) */
-  sendDevtoolsMessage: (message: Devtools.Leader.MessageToApp) => Effect.Effect<void, UnexpectedError>
+  sendDevtoolsMessage: (message: Devtools.Leader.MessageToApp) => Effect.Effect<void>
+  /**
+   * Reactive stream describing the connectivity between the leader and its upstream sync backend.
+   * Includes raw connection state, last transition timestamp, and devtools overrides (latch state).
+   */
+  networkStatus: Subscribable.Subscribable<SyncBackend.NetworkStatus>
 }
 
 export const of = (

package/src/WorkerTransportError.ts

@@ -0,0 +1,12 @@
+import { ParseResult, WorkerError } from '@livestore/utils/effect'
+
+/**
+ * Type guard that identifies infrastructure errors from the Effect Worker transport layer.
+ *
+ * @remarks
+ *
+ * These errors ({@link WorkerError.WorkerError}, {@link ParseResult.ParseError}) represent communication failures between
+ * threads/processes — not application-level failures.
+ */
+export const isWorkerTransportError = (e: unknown): e is WorkerError.WorkerError | ParseResult.ParseError =>
+  ParseResult.isParseError(e) || WorkerError.isWorkerError(e)

package/src/adapter-types.ts

@@ -10,16 +10,21 @@ import {
 
 import type { ClientSessionLeaderThreadProxy } from './ClientSessionLeaderThreadProxy.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { IntentionalShutdownCause, MaterializeError, UnexpectedError } from './errors.ts'
+import type { IntentionalShutdownCause, MaterializeError, UnknownError } from './errors.ts'
 import type { LiveStoreSchema } from './schema/mod.ts'
 import type { SqliteDb } from './sqlite-types.ts'
-import type { IsOfflineError, SyncError } from './sync/index.js'
+import type { BackendIdMismatchError } from './sync/index.ts'
 
 export * as ClientSessionLeaderThreadProxy from './ClientSessionLeaderThreadProxy.ts'
 export * from './defs.ts'
 export * from './errors.ts'
 export * from './sqlite-types.ts'
 
+/**
+ * Runtime handle to an active LiveStore client session within the current process.
+ * Provides direct access to the embedded SQLite database, leader thread bridge,
+ * and lifecycle controls useful for application-level coordination.
+ */
 export interface ClientSession {
   /** SQLite database with synchronous API running in the same thread (usually in-memory) */
   sqliteDb: SqliteDb
@@ -29,7 +34,10 @@ export interface ClientSession {
   /** Status info whether current session is leader or not */
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
   shutdown: (
-    cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError>,
+    cause: Exit.Exit<
+      IntentionalShutdownCause,
+      UnknownError | MaterializeError | BackendIdMismatchError
+    >,
   ) => Effect.Effect<void>
   /** A proxy API to communicate with the leader thread */
   leaderThread: ClientSessionLeaderThreadProxy
@@ -44,12 +52,42 @@ export const BootStateProgress = Schema.Struct({
   total: Schema.Number,
 })
 
+/**
+ * Describes known reasons why LiveStore boot may encounter storage issues.
+ *
+ * @remarks
+ * - `private-browsing`: OPFS unavailable due to private/incognito browsing mode (Safari, Firefox)
+ * - `storage-unavailable`: OPFS access denied for other reasons (permissions, quota)
+ * - `unknown`: Unexpected error during storage initialization
+ */
+export const BootWarningReason = Schema.Literal('private-browsing', 'storage-unavailable', 'unknown')
+export type BootWarningReason = typeof BootWarningReason.Type
+
+/**
+ * Describes the storage mode the store is operating in.
+ *
+ * @remarks
+ * - `persisted`: Data is persisted to disk (e.g., via OPFS)
+ * - `in-memory`: Data is only stored in memory and will be lost on page refresh
+ */
+export const StorageMode = Schema.Literal('persisted', 'in-memory')
+export type StorageMode = typeof StorageMode.Type
+
 export const BootStatus = Schema.Union(
   Schema.Struct({ stage: Schema.Literal('loading') }),
   Schema.Struct({ stage: Schema.Literal('migrating'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('rehydrating'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('syncing'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('done') }),
+  /**
+   * Indicates a non-fatal issue occurred during boot that may degrade functionality.
+   * LiveStore continues running but without full capabilities (e.g., no persistence).
+   */
+  Schema.Struct({
+    stage: Schema.Literal('warning'),
+    reason: BootWarningReason,
+    message: Schema.String,
+  }),
 ).annotations({ title: 'BootStatus' })
 
 export type BootStatus = typeof BootStatus.Type
@@ -114,9 +152,9 @@ export interface ClientSessionDevtoolsChannel
 
 export type ConnectDevtoolsToStore = (
   storeDevtoolsChannel: ClientSessionDevtoolsChannel,
-) => Effect.Effect<void, UnexpectedError, Scope.Scope>
+) => Effect.Effect<void, UnknownError, Scope.Scope>
 
-export type Adapter = (args: AdapterArgs) => Effect.Effect<ClientSession, UnexpectedError, Scope.Scope>
+export type Adapter = (args: AdapterArgs) => Effect.Effect<ClientSession, UnknownError, Scope.Scope>
 
 export interface AdapterArgs {
   schema: LiveStoreSchema
@@ -125,7 +163,10 @@ export interface AdapterArgs {
   debugInstanceId: string
   bootStatusQueue: Queue.Queue<BootStatus>
   shutdown: (
-    exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError | IsOfflineError>,
+    exit: Exit.Exit<
+      IntentionalShutdownCause,
+      UnknownError | MaterializeError | BackendIdMismatchError
+    >,
   ) => Effect.Effect<void>
   connectDevtoolsToStore: ConnectDevtoolsToStore
   /**
@@ -133,5 +174,7 @@ export interface AdapterArgs {
    *
    * @default undefined
    */
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadSchema: Schema.Schema<any> | undefined
+  /** Encoded representation of the sync payload matching `syncPayloadSchema`. */
+  syncPayloadEncoded: Schema.JsonValue | undefined
 }

package/src/bounded-collections.ts

@@ -16,10 +16,11 @@ export class BoundMap<K, V> {
     this.#map.set(key, value)
     // console.log(this.#map.size, this.#sizeLimit);
     if (this.#map.size > this.#sizeLimit) {
-      const firstKey = this.#map.keys().next().value as K
+      const firstKey = this.#map.keys().next().value
+      if (firstKey === undefined) return
       const deletedValue = this.#map.get(firstKey)!
       this.#map.delete(firstKey)
-      if (this.onEvict) {
+      if (this.onEvict !== undefined) {
         this.onEvict(firstKey, deletedValue)
       }
     }
@@ -47,7 +48,7 @@ export class BoundSet<V> {
   }
 
   #onEvict = (v: V) => {
-    if (this.onEvict) {
+    if (this.onEvict !== undefined) {
       this.onEvict(v)
     }
   }
@@ -85,7 +86,7 @@ export class BoundArray<V> {
     this.#array.push(v)
     if (this.#array.length > this.sizeLimit) {
       const first = this.#array.shift()
-      if (first && this.onEvict) {
+      if (first !== undefined && this.onEvict !== undefined) {
         this.onEvict(first)
       }
     }
@@ -116,6 +117,6 @@ export class BoundArray<V> {
   }
 
   sort = (fn?: (a: V, b: V) => number) => {
-    return this.#array.sort(fn)
+    return this.#array.toSorted(fn)
   }
 }

package/src/debug-info.ts

@@ -22,6 +22,15 @@ export const SlowQueryInfo = Schema.Struct({
   startTimePerfNow: Schema.Number,
 })
 
+const getSizeLimit = (value: unknown): number =>
+  typeof (value as { sizeLimit?: number }).sizeLimit === 'number'
+    ? (value as { sizeLimit: number }).sizeLimit
+    : Number.POSITIVE_INFINITY
+
+const isBoundArrayLike = (value: unknown): value is BoundArray<unknown> =>
+  value instanceof BoundArray ||
+  (value !== null && typeof value === 'object' && typeof (value as { sizeLimit?: number }).sizeLimit === 'number')
+
 const BoundArraySchemaFromSelf = <A, I, R>(
   item: Schema.Schema<A, I, R>,
 ): Schema.Schema<BoundArray<A>, BoundArray<I>, R> =>
@@ -29,16 +38,17 @@ const BoundArraySchemaFromSelf = <A, I, R>(
     [item],
     {
       decode: (item) => (input, parseOptions, ast) => {
-        if (input instanceof BoundArray) {
+        if (isBoundArrayLike(input) === true) {
           const elements = ParseResult.decodeUnknown(Schema.Array(item))([...input], parseOptions)
-          return ParseResult.map(elements, (as): BoundArray<A> => BoundArray.make(input.sizeLimit, as))
+          return ParseResult.map(elements, (as): BoundArray<A> => BoundArray.make(getSizeLimit(input), as))
         }
         return ParseResult.fail(new ParseResult.Type(ast, input))
       },
       encode: (item) => (input, parseOptions, ast) => {
-        if (input instanceof BoundArray) {
-          const elements = ParseResult.encodeUnknown(Schema.Array(item))([...input], parseOptions)
-          return ParseResult.map(elements, (is): BoundArray<I> => BoundArray.make(input.sizeLimit, is))
+        if (isBoundArrayLike(input) === true) {
+          const items = [...input]
+          const elements = ParseResult.encodeUnknown(Schema.Array(item))(items, parseOptions)
+          return ParseResult.map(elements, (is): BoundArray<I> => BoundArray.make(getSizeLimit(input), is))
         }
         return ParseResult.fail(new ParseResult.Type(ast, input))
       },
@@ -47,7 +57,28 @@ const BoundArraySchemaFromSelf = <A, I, R>(
       description: `BoundArray<${Schema.format(item)}>`,
       pretty: () => (_) => `BoundArray(${_.length})`,
       arbitrary: () => (fc) => fc.anything() as any,
-      equivalence: () => (a, b) => a === b,
+      equivalence: () => {
+        const elementEquivalence = Schema.equivalence(item)
+        return (a: unknown, b: unknown) => {
+          if (a === b) {
+            return true
+          }
+          if (isBoundArrayLike(a) === false || isBoundArrayLike(b) === false) {
+            return false
+          }
+          if (getSizeLimit(a) !== getSizeLimit(b) || a.length !== b.length) {
+            return false
+          }
+          const itemsA = [...a]
+          const itemsB = [...b]
+          for (let i = 0; i < itemsA.length; i++) {
+            if (elementEquivalence(itemsA[i] as any, itemsB[i] as any) === false) {
+              return false
+            }
+          }
+          return true
+        }
+      },
     },
   )
 

package/src/devtools/devtools-compatibility.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+
+import { isDevtoolsProtocolVersionSupported, resolveDevtoolsProtocolVersion } from '../version.ts'
+
+describe('DevTools protocol compatibility', () => {
+  it('treats legacy pings without a protocol version as protocol 1', () => {
+    expect(resolveDevtoolsProtocolVersion(undefined)).toBe(1)
+    expect(isDevtoolsProtocolVersionSupported(undefined, [1])).toBe(true)
+  })
+
+  it('accepts supported protocol versions independent of package version', () => {
+    expect(isDevtoolsProtocolVersionSupported(1, [1])).toBe(true)
+  })
+
+  it('rejects unsupported protocol versions', () => {
+    expect(isDevtoolsProtocolVersionSupported(2, [1])).toBe(false)
+  })
+})

package/src/devtools/devtools-messages-client-session.ts

@@ -52,8 +52,8 @@ export class SyncHeadUnsubscribe extends LSDClientSessionReqResMessage('LSD.Clie
   subscriptionId: Schema.String,
 }) {}
 export class SyncHeadRes extends LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadRes', {
-  local: EventSequenceNumber.EventSequenceNumber,
-  upstream: EventSequenceNumber.EventSequenceNumber,
+  local: EventSequenceNumber.Client.Composite,
+  upstream: EventSequenceNumber.Client.Composite,
   subscriptionId: Schema.String,
 }) {}
 
@@ -103,9 +103,26 @@ export class LiveQueriesRes extends LSDClientSessionReqResMessage('LSD.ClientSes
   subscriptionId: Schema.String,
 }) {}
 
-export class Ping extends LSDClientSessionReqResMessage('LSD.ClientSession.Ping', {}) {}
+export class Ping extends LSDClientSessionReqResMessage('LSD.ClientSession.Ping', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
+
+export class Pong extends LSDClientSessionReqResMessage('LSD.ClientSession.Pong', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
 
-export class Pong extends LSDClientSessionReqResMessage('LSD.ClientSession.Pong', {}) {}
+/**
+ * Sent by the app when the DevTools protocol isn't compatible.
+ * Contains package versions for display and protocol versions for the actual compatibility decision.
+ */
+export class VersionMismatch extends LSDClientSessionReqResMessage('LSD.ClientSession.VersionMismatch', {
+  /** The version running in the app */
+  appVersion: Schema.String,
+  /** The version that was sent by DevTools (that caused the mismatch) */
+  receivedVersion: Schema.String,
+  appDevtoolsProtocolVersion: Schema.Number,
+  receivedDevtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
 
 export class Disconnect extends LSDClientSessionChannelMessage('LSD.ClientSession.Disconnect', {}) {}
 
@@ -136,6 +153,7 @@ export const MessageFromApp = Schema.Union(
   LiveQueriesRes,
   Disconnect,
   Pong,
+  VersionMismatch,
   SyncHeadRes,
 ).annotations({ identifier: 'LSD.ClientSession.MessageFromApp' })
 

package/src/devtools/devtools-messages-common.ts

@@ -1,20 +1,15 @@
 import { Schema } from '@livestore/utils/effect'
 
-import { liveStoreVersion as pkgVersion } from '../version.ts'
-
-export const NetworkStatus = Schema.Struct({
-  isConnected: Schema.Boolean,
-  timestampMs: Schema.Number,
-  /** Whether the network status devtools latch is closed. Used to simulate network disconnection. */
-  latchClosed: Schema.Boolean,
-})
-
-export type NetworkStatus = typeof NetworkStatus.Type
+export { NetworkStatus } from '../sync/sync-backend.ts'
 
 export const requestId = Schema.String
 export const clientId = Schema.String
 export const sessionId = Schema.String
-export const liveStoreVersion = Schema.Literal(pkgVersion)
+/**
+ * Display/package version field for DevTools messages.
+ * Compatibility is decided by the optional DevTools protocol version carried by handshake messages.
+ */
+export const liveStoreVersion = Schema.String
 
 export const LSDMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
   Schema.TaggedStruct(tag, {
@@ -94,7 +89,7 @@ export const LeaderReqResMessage = <
     ...fields.success,
   }).annotations({ identifier: `${tag}.Response.Success` })
 
-  const Error = fields.error
+  const Error = fields.error !== undefined
     ? Schema.TaggedStruct(`${tag}.Response.Error`, {
         requestId,
         liveStoreVersion,

package/src/devtools/devtools-messages-leader.ts

@@ -1,6 +1,6 @@
 import { Schema, Transferable } from '@livestore/utils/effect'
 
-import * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
 import { EventSequenceNumber } from '../schema/mod.ts'
 import * as SyncState from '../sync/syncstate.ts'
 import { LeaderReqResMessage, LSDMessage, LSDReqResMessage, NetworkStatus } from './devtools-messages-common.ts'
@@ -51,7 +51,7 @@ export class SyncHistoryUnsubscribe extends LSDReqResMessage('LSD.Leader.SyncHis
   subscriptionId: Schema.String,
 }) {}
 export class SyncHistoryRes extends LSDReqResMessage('LSD.Leader.SyncHistoryRes', {
-  eventEncoded: LiveStoreEvent.AnyEncodedGlobal,
+  eventEncoded: LiveStoreEvent.Global.Encoded,
   metadata: Schema.Option(Schema.JsonValue),
   subscriptionId: Schema.String,
 }) {}
@@ -63,8 +63,8 @@ export class SyncHeadUnsubscribe extends LSDReqResMessage('LSD.Leader.SyncHeadUn
   subscriptionId: Schema.String,
 }) {}
 export class SyncHeadRes extends LSDReqResMessage('LSD.Leader.SyncHeadRes', {
-  local: EventSequenceNumber.EventSequenceNumber,
-  upstream: EventSequenceNumber.EventSequenceNumber,
+  local: EventSequenceNumber.Client.Composite,
+  upstream: EventSequenceNumber.Client.Composite,
   subscriptionId: Schema.String,
 }) {}
 
@@ -77,13 +77,14 @@ export class SnapshotRes extends LSDReqResMessage('LSD.Leader.SnapshotRes', {
 export const LoadDatabaseFile = LeaderReqResMessage('LSD.Leader.LoadDatabaseFile', {
   payload: {
     data: Transferable.Uint8Array as Schema.Schema<Uint8Array<ArrayBuffer>>,
+    batchId: Schema.optional(Schema.String),
   },
   success: {},
   error: {
     cause: Schema.Union(
       Schema.TaggedStruct('unsupported-file', {}),
       Schema.TaggedStruct('unsupported-database', {}),
-      Schema.TaggedStruct('unexpected-error', { cause: Schema.Defect }),
+      Schema.TaggedStruct('unknown-error', { cause: Schema.Defect }),
     ),
   },
 })
@@ -95,7 +96,7 @@ export class SyncPull extends LSDMessage('LSD.Leader.SyncPull', {
 
 // TODO refactor this to use push/pull semantics
 export class CommitEventReq extends LSDReqResMessage('LSD.Leader.CommitEventReq', {
-  eventEncoded: LiveStoreEvent.PartialAnyEncoded,
+  eventEncoded: LiveStoreEvent.Input.Encoded,
 }) {}
 
 export class CommitEventRes extends LSDReqResMessage('LSD.Leader.CommitEventRes', {}) {}
@@ -106,9 +107,26 @@ export class EventlogRes extends LSDReqResMessage('LSD.Leader.EventlogRes', {
   eventlog: Transferable.Uint8Array as Schema.Schema<Uint8Array<ArrayBuffer>>,
 }) {}
 
-export class Ping extends LSDReqResMessage('LSD.Leader.Ping', {}) {}
+export class Ping extends LSDReqResMessage('LSD.Leader.Ping', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
+
+export class Pong extends LSDReqResMessage('LSD.Leader.Pong', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
 
-export class Pong extends LSDReqResMessage('LSD.Leader.Pong', {}) {}
+/**
+ * Sent by the app when the DevTools protocol isn't compatible.
+ * Contains package versions for display and protocol versions for the actual compatibility decision.
+ */
+export class VersionMismatch extends LSDReqResMessage('LSD.Leader.VersionMismatch', {
+  /** The version running in the app */
+  appVersion: Schema.String,
+  /** The version that was sent by DevTools (that caused the mismatch) */
+  receivedVersion: Schema.String,
+  appDevtoolsProtocolVersion: Schema.Number,
+  receivedDevtoolsProtocolVersion: Schema.optional(Schema.Number),
+}) {}
 
 export class Disconnect extends LSDReqResMessage('LSD.Leader.Disconnect', {}) {}
 
@@ -133,7 +151,7 @@ export const ResetAllData = LeaderReqResMessage('LSD.Leader.ResetAllData', {
 //     liveStoreVersion,
 //   },
 //   success: DatabaseFileInfo,
-//   failure: UnexpectedError,
+//   failure: UnknownError,
 // }) {}
 
 // export class NetworkStatus_ extends Schema.TaggedRequest<NetworkStatus_>()('LSD.Leader.NetworkStatus', {
@@ -142,7 +160,7 @@ export const ResetAllData = LeaderReqResMessage('LSD.Leader.ResetAllData', {
 //     liveStoreVersion,
 //   },
 //   success: NetworkStatus,
-//   failure: UnexpectedError,
+//   failure: UnknownError,
 // }) {}
 
 // export const MessageToApp_ = Schema.Union(DatabaseFileInfo_, NetworkStatus_)
@@ -180,6 +198,7 @@ export const MessageFromApp = Schema.Union(
   NetworkStatusRes,
   CommitEventRes,
   Pong,
+  VersionMismatch,
   DatabaseFileInfoRes,
   SyncHistoryRes,
   SyncingInfoRes,

package/src/devtools/devtools-sessioninfo.ts

@@ -21,6 +21,12 @@ export const SessionInfo = Schema.TaggedStruct('SessionInfo', {
   sessionId: Schema.String,
   schemaAlias: Schema.String,
   isLeader: Schema.Boolean,
+  /**
+   * Browser origin that produced this SessionInfo (for example, 'http://localhost:5173').
+   * Set by browser-based publishers so DevTools can defensively filter by origin.
+   * Currently only needed by the browser extension; non‑browser publishers typically set `undefined`.
+   */
+  origin: Schema.UndefinedOr(Schema.String),
 })
 export type SessionInfo = typeof SessionInfo.Type
 
@@ -55,7 +61,7 @@ export const requestSessionInfoSubscription = ({
   webChannel: WebChannel.WebChannel<Message, Message>
   pollInterval?: Duration.DurationInput
   staleTimeout?: Duration.DurationInput
-}): Effect.Effect<Subscribable.Subscribable<Set<SessionInfo>>, ParseResult.ParseError, Scope.Scope> =>
+}): Effect.Effect<Subscribable.Subscribable<HashSet.HashSet<SessionInfo>>, ParseResult.ParseError, Scope.Scope> =>
   Effect.gen(function* () {
     yield* webChannel
       .send(RequestSessions.make({}))
@@ -94,8 +100,5 @@ export const requestSessionInfoSubscription = ({
       Effect.forkScoped,
     )
 
-    return Subscribable.make({
-      get: sessionInfoSubRef.get.pipe(Effect.map((sessionInfos) => new Set(sessionInfos))),
-      changes: sessionInfoSubRef.changes.pipe(Stream.map((sessionInfos) => new Set(sessionInfos))),
-    })
+    return Subscribable.make({ get: sessionInfoSubRef.get, changes: sessionInfoSubRef.changes })
   })