@livestore/common 0.4.0-dev.2 → 0.4.0-dev.21

package/dist/sync/validate-push-payload.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-push-payload.js","sourceRoot":"","sources":["../../src/sync/validate-push-payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C,+BAA+B;AAC/B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAAqD,EACrD,0BAAyE,EACzE,EAAE,CACF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,IAAI,0BAA0B,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC;YAClC,MAAM,EAAE;gBACN,IAAI,EAAE,aAAa;gBACnB,kBAAkB,EAAE,0BAA0B,GAAG,CAAC;gBAClD,WAAW,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM;aAC9B;SACF,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAC,CAAA"}
+{"version":3,"file":"validate-push-payload.js","sourceRoot":"","sources":["../../src/sync/validate-push-payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EAAE,mBAAmB,EAAuB,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE9D,+BAA+B;AAC/B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAAmD,EACnD,0BAA2D,EAC3D,EAAE,CACF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,IAAI,0BAA0B,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC;YAClC,KAAK,EAAE,IAAI,gBAAgB,CAAC;gBAC1B,kBAAkB,EAAE,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,GAAG,CAAC,CAAC;gBACnF,WAAW,EAAE,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC;aAC/D,CAAC;SACH,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAC,CAAA"}

package/dist/testing/event-factory.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Helpers for synthesizing LiveStore events in tests while keeping track of
+ * sequence numbers, parent pointers, and authoring client identity. Inspired
+ * by the effect-based schema utilities, the factory exposes a namespaced API
+ * where each event definition maps to a helper with `next`, `advanceTo`, and
+ * `setParent` functions that share a single sequence stream.
+ *
+ * @example
+ * ```ts
+ * import { EventFactory } from '@livestore/common/testing'
+ * import { events } from './schema'
+ *
+ * const eventFactory = EventFactory.makeFactory(events)({
+ *   client: EventFactory.clientIdentity('test-client'),
+ *   startSeq: 1,
+ *   initialParent: 'root',
+ * })
+ *
+ * const bootstrap = eventFactory.todoCreated.next({
+ *   id: 'todo-1',
+ *   text: 'write tests',
+ *   completed: false,
+ * })
+ *
+ * eventFactory.todoCreated.advanceTo(42)
+ * const branched = eventFactory.todoUpdated.next({
+ *   id: 'todo-1',
+ *   text: 'ship feature',
+ *   completed: true,
+ * })
+ * ```
+ */
+import type { EventDef } from '../schema/EventDef/mod.ts';
+import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts';
+export interface ClientIdentity {
+    clientId: string;
+    sessionId: string;
+}
+export declare const clientIdentity: (label: string, session?: string) => ClientIdentity;
+export type SequenceValue = 'root' | number;
+type EventFactoriesArgs<TDefs extends Record<string, EventDef.Any>> = {
+    [K in keyof TDefs]: Parameters<TDefs[K]>[0];
+};
+type EventFactories<TDefs extends Record<string, EventDef.Any>, TResult> = {
+    [K in keyof TDefs]: {
+        next: (args: EventFactoriesArgs<TDefs>[K]) => TResult;
+        advanceTo: (seq: number, parent?: SequenceValue) => void;
+        setParent: (parent: SequenceValue) => void;
+        current: () => {
+            seq: number;
+            parent: SequenceValue;
+        };
+    };
+};
+export interface EventFactoriesConfig {
+    client: ClientIdentity;
+    /**
+     * @default 1
+     */
+    startSeq?: number;
+    /**
+     * @default 0 (root)
+     */
+    initialParent?: SequenceValue;
+}
+export declare const makeFactory: <TDefs extends Record<string, EventDef.Any>>(eventDefs: TDefs) => ({ client, startSeq, initialParent, }: EventFactoriesConfig) => EventFactories<TDefs, LiveStoreEvent.Global.Encoded>;
+export {};
+//# sourceMappingURL=event-factory.d.ts.map

package/dist/testing/event-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-factory.d.ts","sourceRoot":"","sources":["../../src/testing/event-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AAEzD,OAAO,KAAK,cAAc,MAAM,iCAAiC,CAAA;AAEjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,gBAA4B,KAAG,cAG3E,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAA;AAE3C,KAAK,kBAAkB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI;KACnE,CAAC,IAAI,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAA;AAED,KAAK,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI;KACxE,CAAC,IAAI,MAAM,KAAK,GAAG;QAClB,IAAI,EAAE,CAAC,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAA;QACrD,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,KAAK,IAAI,CAAA;QACxD,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAA;QAC1C,OAAO,EAAE,MAAM;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,aAAa,CAAA;SAAE,CAAA;KACtD;CACF,CAAA;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,cAAc,CAAA;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,eAAO,MAAM,WAAW,GACrB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,KAAK,MAC5D,sCAIE,oBAAoB,KAAG,cAAc,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO,CAgD5E,CAAA"}

package/dist/testing/event-factory.js

@@ -0,0 +1,78 @@
+/**
+ * Helpers for synthesizing LiveStore events in tests while keeping track of
+ * sequence numbers, parent pointers, and authoring client identity. Inspired
+ * by the effect-based schema utilities, the factory exposes a namespaced API
+ * where each event definition maps to a helper with `next`, `advanceTo`, and
+ * `setParent` functions that share a single sequence stream.
+ *
+ * @example
+ * ```ts
+ * import { EventFactory } from '@livestore/common/testing'
+ * import { events } from './schema'
+ *
+ * const eventFactory = EventFactory.makeFactory(events)({
+ *   client: EventFactory.clientIdentity('test-client'),
+ *   startSeq: 1,
+ *   initialParent: 'root',
+ * })
+ *
+ * const bootstrap = eventFactory.todoCreated.next({
+ *   id: 'todo-1',
+ *   text: 'write tests',
+ *   completed: false,
+ * })
+ *
+ * eventFactory.todoCreated.advanceTo(42)
+ * const branched = eventFactory.todoUpdated.next({
+ *   id: 'todo-1',
+ *   text: 'ship feature',
+ *   completed: true,
+ * })
+ * ```
+ */
+import { Schema } from '@livestore/utils/effect';
+import * as EventSequenceNumber from "../schema/EventSequenceNumber/mod.js";
+import * as LiveStoreEvent from "../schema/LiveStoreEvent/mod.js";
+export const clientIdentity = (label, session = `${label}-session`) => ({
+    clientId: label,
+    sessionId: session,
+});
+export const makeFactory = (eventDefs) => ({ client, startSeq = 1, initialParent = 'root', }) => {
+    let nextSeq = startSeq;
+    let parentRef = initialParent;
+    const advanceTo = (seq, parent = 'root') => {
+        nextSeq = seq;
+        parentRef = parent;
+    };
+    const setParent = (parent) => {
+        parentRef = parent;
+    };
+    const current = () => ({ seq: nextSeq, parent: parentRef });
+    const factories = {};
+    for (const [name, eventDef] of Object.entries(eventDefs)) {
+        const next = (args) => {
+            const decoded = eventDef(args);
+            const encodedArgs = Schema.encodeSync(eventDef.schema)(decoded.args);
+            const encoded = eventDef.encoded(encodedArgs);
+            const event = LiveStoreEvent.Global.Encoded.make({
+                name: encoded.name,
+                args: encoded.args,
+                seqNum: EventSequenceNumber.Global.make(nextSeq),
+                parentSeqNum: parentRef === 'root' ? EventSequenceNumber.Client.ROOT.global : EventSequenceNumber.Global.make(parentRef),
+                clientId: client.clientId,
+                sessionId: client.sessionId,
+            });
+            parentRef = nextSeq;
+            nextSeq = nextSeq + 1;
+            return event;
+        };
+        factories[name] = {
+            next,
+            advanceTo,
+            setParent,
+            current,
+        };
+    }
+    return factories;
+};
+//# sourceMappingURL=event-factory.js.map

package/dist/testing/event-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-factory.js","sourceRoot":"","sources":["../../src/testing/event-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAGhD,OAAO,KAAK,mBAAmB,MAAM,sCAAsC,CAAA;AAC3E,OAAO,KAAK,cAAc,MAAM,iCAAiC,CAAA;AAOjE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,OAAO,GAAG,GAAG,KAAK,UAAU,EAAkB,EAAE,CAAC,CAAC;IAC9F,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,OAAO;CACnB,CAAC,CAAA;AA6BF,MAAM,CAAC,MAAM,WAAW,GACtB,CAA6C,SAAgB,EAAE,EAAE,CACjE,CAAC,EACC,MAAM,EACN,QAAQ,GAAG,CAAC,EACZ,aAAa,GAAG,MAAM,GACD,EAAwD,EAAE;IAC/E,IAAI,OAAO,GAAG,QAAQ,CAAA;IACtB,IAAI,SAAS,GAAkB,aAAa,CAAA;IAE5C,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,SAAwB,MAAM,EAAE,EAAE;QAChE,OAAO,GAAG,GAAG,CAAA;QACb,SAAS,GAAG,MAAM,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,SAAS,GAAG,CAAC,MAAqB,EAAE,EAAE;QAC1C,SAAS,GAAG,MAAM,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;IAE3D,MAAM,SAAS,GAAkE,EAAE,CAAA;IAEnF,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAwC,EAAE,CAAC;QAChG,MAAM,IAAI,GAAG,CAAC,IAA4C,EAAE,EAAE;YAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;YAC9B,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;YAE7C,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC/C,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;gBAChD,YAAY,EACV,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;gBAC5G,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAA;YAEF,SAAS,GAAG,OAAO,CAAA;YACnB,OAAO,GAAG,OAAO,GAAG,CAAC,CAAA;YAErB,OAAO,KAAK,CAAA;QACd,CAAC,CAAA;QAED,SAAS,CAAC,IAAI,CAAC,GAAG;YAChB,IAAI;YACJ,SAAS;YACT,SAAS;YACT,OAAO;SAC6D,CAAA;IACxE,CAAC;IAED,OAAO,SAAiE,CAAA;AAC1E,CAAC,CAAA"}

package/dist/testing/mod.d.ts

@@ -0,0 +1,2 @@
+export * as EventFactory from './event-factory.ts';
+//# sourceMappingURL=mod.d.ts.map

package/dist/testing/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/testing/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA"}

package/dist/testing/mod.js

@@ -0,0 +1,2 @@
+export * as EventFactory from "./event-factory.js";
+//# sourceMappingURL=mod.js.map

package/dist/testing/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../src/testing/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA"}

package/dist/version.d.ts

@@ -1,10 +1,20 @@
-export declare const liveStoreVersion: "0.4.0-dev.2";
+export declare const liveStoreVersion: "0.4.0-dev.21";
 /**
- * This version number is incremented whenever the internal storage format changes in a breaking way.
- * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
+ * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.
  *
- * While LiveStore is in beta, this might happen more frequently.
- * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
+ * Used to generate database file names (e.g., `eventlog@6.db`, `state@6.db`) across all client adapters.
+ *
+ * Bump required when:
+ * - Modifying eventlog system tables (eventlogMetaTable, syncStatusTable) in schema/state/sqlite/system-tables/eventlog-tables.ts
+ * - Changing columns, types, constraints, or indexes in eventlog tables
+ *
+ * Bump NOT required when:
+ * - Modifying STATE table schemas (auto-migrated via hash-based detection and rebuilt from eventlog)
+ * - Changing query patterns or client-side implementation details
+ *
+ * ⚠️  CRITICAL: Eventlog changes without bumping this version cause permanent data loss!
+ *
+ * Impact: Version changes trigger a "soft reset" - old data becomes inaccessible but remains on disk.
  */
-export declare const liveStoreStorageFormatVersion = 5;
+export declare const liveStoreStorageFormatVersion = 6;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,EAAG,aAAsB,CAAA;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,EAAG,cAAuB,CAAA;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA"}

package/dist/version.js

@@ -1,13 +1,23 @@
 // TODO bring back when Expo and Playwright supports `with` imports
 // import packageJson from '../package.json' with { type: 'json' }
 // export const liveStoreVersion = packageJson.version
-export const liveStoreVersion = '0.4.0-dev.2';
+export const liveStoreVersion = '0.4.0-dev.21';
 /**
- * This version number is incremented whenever the internal storage format changes in a breaking way.
- * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
+ * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.
  *
- * While LiveStore is in beta, this might happen more frequently.
- * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
+ * Used to generate database file names (e.g., `eventlog@6.db`, `state@6.db`) across all client adapters.
+ *
+ * Bump required when:
+ * - Modifying eventlog system tables (eventlogMetaTable, syncStatusTable) in schema/state/sqlite/system-tables/eventlog-tables.ts
+ * - Changing columns, types, constraints, or indexes in eventlog tables
+ *
+ * Bump NOT required when:
+ * - Modifying STATE table schemas (auto-migrated via hash-based detection and rebuilt from eventlog)
+ * - Changing query patterns or client-side implementation details
+ *
+ * ⚠️  CRITICAL: Eventlog changes without bumping this version cause permanent data loss!
+ *
+ * Impact: Version changes trigger a "soft reset" - old data becomes inaccessible but remains on disk.
  */
-export const liveStoreStorageFormatVersion = 5;
+export const liveStoreStorageFormatVersion = 6;
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAsB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAuB,CAAA;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/common",
-  "version": "0.4.0-dev.2",
+  "version": "0.4.0-dev.21",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -8,20 +8,19 @@
     "./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"
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "graphology": "0.26.0-alpha1",
-    "graphology-dag": "0.4.1",
-    "graphology-types": "0.24.8",
-    "@livestore/utils": "0.4.0-dev.2",
-    "@livestore/webmesh": "0.4.0-dev.2"
+    "@livestore/utils": "0.4.0-dev.21",
+    "@livestore/webmesh": "0.4.0-dev.21"
   },
   "devDependencies": {
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.2"
+    "@livestore/utils-dev": "0.4.0-dev.21"
   },
   "files": [
     "package.json",

package/src/ClientSessionLeaderThreadProxy.ts

@@ -1,33 +1,41 @@
-import type { Effect, Stream } from '@livestore/utils/effect'
+import type { Effect, Stream, Subscribable } from '@livestore/utils/effect'
 
 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 { UnknownError } from './errors.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 { LeaderAheadError, 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 }, UnknownError>
     /** 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, UnknownError | LeaderAheadError>
+    /** Stream events with filtering */
+    stream(options: StreamEventsOptions): Stream.Stream<LiveStoreEvent.Client.Encoded, UnknownError>
   }
   /** 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
   }
-  export: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getSyncState: Effect.Effect<SyncState, UnexpectedError>
+  export: Effect.Effect<Uint8Array<ArrayBuffer>, UnknownError>
+  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>, UnknownError>
+  syncState: Subscribable.Subscribable<SyncState, UnknownError>
   /** 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, UnknownError>
+  /**
+   * 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/adapter-types.ts

@@ -10,15 +10,21 @@ import {
 
 import type { ClientSessionLeaderThreadProxy } from './ClientSessionLeaderThreadProxy.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { IntentionalShutdownCause, SyncError, 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.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
@@ -27,7 +33,9 @@ export interface ClientSession {
   sessionId: string
   /** Status info whether current session is leader or not */
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
-  shutdown: (cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) => Effect.Effect<void>
+  shutdown: (
+    cause: Exit.Exit<IntentionalShutdownCause, UnknownError | SyncError | MaterializeError>,
+  ) => Effect.Effect<void>
   /** A proxy API to communicate with the leader thread */
   leaderThread: ClientSessionLeaderThreadProxy
   /** A unique identifier for the current instance of the client session. Used for debugging purposes. */
@@ -111,9 +119,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
@@ -121,12 +129,16 @@ export interface AdapterArgs {
   devtoolsEnabled: boolean
   debugInstanceId: string
   bootStatusQueue: Queue.Queue<BootStatus>
-  shutdown: (exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) => Effect.Effect<void>
+  shutdown: (
+    exit: Exit.Exit<IntentionalShutdownCause, UnknownError | SyncError | MaterializeError | IsOfflineError>,
+  ) => Effect.Effect<void>
   connectDevtoolsToStore: ConnectDevtoolsToStore
   /**
    * Payload that will be passed to the sync backend when connecting
    *
    * @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/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)) {
           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)) {
+          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) || !isBoundArrayLike(b)) {
+            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)) {
+              return false
+            }
+          }
+          return true
+        }
+      },
     },
   )
 

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,
 }) {}
 

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

@@ -2,14 +2,7 @@ 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

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', {}) {}
@@ -133,7 +134,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 +143,7 @@ export const ResetAllData = LeaderReqResMessage('LSD.Leader.ResetAllData', {
 //     liveStoreVersion,
 //   },
 //   success: NetworkStatus,
-//   failure: UnexpectedError,
+//   failure: UnknownError,
 // }) {}
 
 // export const MessageToApp_ = Schema.Union(DatabaseFileInfo_, NetworkStatus_)

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 })
   })

package/src/devtools/mod.ts

@@ -34,7 +34,15 @@ export const makeNodeName = {
 }
 
 export const makeChannelName = {
-  sessionInfo: () => `session-info`,
+  /**
+   * SessionInfo channel for DevTools discovery.
+   * When an `origin` is provided, it is incorporated into the channel name to scope
+   * broadcasts per origin (e.g. `session-info::http%3A%2F%2Flocalhost%3A5173`).
+   * The `origin` is currently required only for the browser extension path; non‑browser
+   * publishers can pass `undefined` to use the legacy global channel name.
+   */
+  sessionInfo: ({ origin }: { origin: string | undefined }) =>
+    origin ? `session-info::${encodeURIComponent(origin)}` : `session-info`,
   devtoolsClientSession: ({ storeId, clientId, sessionId }: { storeId: string; clientId: string; sessionId: string }) =>
     `devtools-channel(client-session-${storeId}-${clientId}-${sessionId})`,
   devtoolsClientLeader: ({ storeId, clientId, sessionId }: { storeId: string; clientId: string; sessionId: string }) =>
@@ -52,8 +60,9 @@ export const isChannelName = {
 
 export const makeSessionInfoBroadcastChannel = (
   webmeshNode: MeshNode,
+  options: { origin: string | undefined },
 ): Effect.Effect<WebChannel.WebChannel<SessionInfo.Message, SessionInfo.Message>, never, Scope.Scope> =>
   webmeshNode.makeBroadcastChannel({
-    channelName: makeChannelName.sessionInfo(),
+    channelName: makeChannelName.sessionInfo({ origin: options?.origin }),
     schema: SessionInfo.Message,
   })