@livestore/livestore 0.4.0-dev.9 → 0.5.0-dev.0

package/src/store/store.ts

@@ -1,7 +1,8 @@
+import * as otel from '@opentelemetry/api'
+
 import {
   type Bindable,
   type ClientSession,
-  type ClientSessionSyncProcessor,
   Devtools,
   getExecStatementsFromMaterializer,
   getResultSchema,
@@ -12,18 +13,21 @@ import {
   MaterializeError,
   MaterializerHashMismatchError,
   makeClientSessionSyncProcessor,
-  type PreparedBindValues,
   prepareBindValues,
-  type QueryBuilder,
   QueryBuilderAstSymbol,
-  replaceSessionIdSymbol,
-  UnexpectedError,
+  resolveSessionIdSymbolInBindValues,
+  SqliteDbHelper,
+  StateHead,
+  type StorageMode,
+  type SyncState,
+  UnknownError,
 } from '@livestore/common'
+import type { StreamEventsOptions } from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
-import { getEventDef, LiveStoreEvent, SystemTables } from '@livestore/common/schema'
-import { assertNever, isDevEnv, notYetImplemented, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
-import type { Scope } from '@livestore/utils/effect'
+import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from '@livestore/common/schema'
+import { assertNever, isDevEnv, objectToString, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import {
+  type Scope,
   Cause,
   Effect,
   Exit,
@@ -31,20 +35,14 @@ import {
   Inspectable,
   Option,
   OtelTracer,
-  Runtime,
+  Queue,
+  Result,
   Schema,
   Stream,
 } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
-import * as otel from '@opentelemetry/api'
 
-import type {
-  LiveQuery,
-  LiveQueryDef,
-  ReactivityGraph,
-  ReactivityGraphContext,
-  SignalDef,
-} from '../live-queries/base-class.ts'
+import type { LiveQuery, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts'
 import { makeReactivityGraph } from '../live-queries/base-class.ts'
 import { makeExecBeforeFirstRun } from '../live-queries/client-document-get-query.ts'
 import { queryDb } from '../live-queries/db-query.ts'
@@ -52,52 +50,143 @@ import type { Ref } from '../reactive.ts'
 import { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
 import { ReferenceCountedSet } from '../utils/data-structures.ts'
 import { downloadBlob, exposeDebugUtils } from '../utils/dev.ts'
-import type { StackInfo } from '../utils/stack-info.ts'
-import type {
-  RefreshReason,
-  StoreCommitOptions,
-  StoreEventsOptions,
-  StoreOptions,
-  StoreOtel,
-  Unsubscribe,
+import {
+  type Queryable,
+  type RefreshReason,
+  type StoreCommitOptions,
+  type StoreConstructorParams,
+  type StoreEventsOptions,
+  type StoreInternals,
+  StoreInternalsSymbol,
+  type StoreOtel,
+  type SubscribeOptions,
+  type SyncStatus,
+  type Unsubscribe,
 } from './store-types.ts'
 
-if (isDevEnv()) {
+export type SubscribeFn = {
+  <TResult>(
+    query: Queryable<TResult>,
+    onUpdate: (value: TResult) => void,
+    options?: SubscribeOptions<TResult>,
+  ): Unsubscribe
+  <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): AsyncIterable<TResult>
+}
+
+if (isDevEnv() === true) {
   exposeDebugUtils()
 }
 
+/**
+ * Default parameters for the Store. Also used in `create-store.ts`
+ */
+export const STORE_DEFAULT_PARAMS = {
+  leaderPushBatchSize: 100,
+  eventQueryBatchSize: 100,
+}
+
+//
+/**
+ * Central interface to a LiveStore database providing reactive queries, event commits, and sync.
+ *
+ * A `Store` instance wraps a local SQLite database that is kept in sync with other clients via
+ * an event log. Instead of mutating state directly, you commit events that get materialized
+ * into database rows. Queries automatically re-run when their underlying tables change.
+ *
+ * ## Creating a Store
+ *
+ * Use `createStore` (Effect-based) or `createStorePromise` to obtain a Store instance.
+ * In React applications, use `StoreRegistry` with `<StoreRegistryProvider>` and the `useStore()` hook
+ * which manages the Store lifecycle.
+ *
+ * ## Querying Data
+ *
+ * Use {@link Store.query} for one-shot reads or {@link Store.subscribe} for reactive subscriptions.
+ * Both accept query builders (e.g. `tables.todo.where({ complete: true })`) or custom `LiveQueryDef`s.
+ *
+ * ## Committing Events
+ *
+ * Use {@link Store.commit} to persist events. Events are immediately materialized locally and
+ * asynchronously synced to other clients. Multiple events can be committed atomically.
+ *
+ * ## Lifecycle
+ *
+ * The Store must be shut down when no longer needed via {@link Store.shutdown} or
+ * {@link Store.shutdownPromise}. Framework integrations (React, Effect) handle this automatically.
+ *
+ * @typeParam TSchema - The LiveStore schema defining tables and events
+ * @typeParam TContext - Optional user-defined context attached to the Store (e.g. for dependency injection)
+ *
+ * @example
+ * ```ts
+ * // Query data
+ * const todos = store.query(tables.todo.where({ complete: false }))
+ *
+ * // Subscribe to changes
+ * const unsubscribe = store.subscribe(tables.todo.all(), (todos) => {
+ *   console.log('Todos updated:', todos)
+ * })
+ *
+ * // Commit an event
+ * store.commit(events.todoCreated({ id: nanoid(), text: 'Buy milk' }))
+ * ```
+ */
 export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> extends Inspectable.Class {
+  /** Unique identifier for this Store instance, stable for its lifetime. */
   readonly storeId: string
-  reactivityGraph: ReactivityGraph
-  sqliteDbWrapper: SqliteDbWrapper
-  clientSession: ClientSession
-  schema: LiveStoreSchema
-  context: TContext
-  otel: StoreOtel
-  /**
-   * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
-   * This only works in combination with `equal: () => false` which will always trigger a refresh.
-   */
-  tableRefs: { [key: string]: Ref<null, ReactivityGraphContext, RefreshReason> }
 
-  /** Tracks whether the store has been shut down */
-  private isShutdown = false
+  /** The LiveStore schema defining tables, events, and materializers. */
+  readonly schema: LiveStoreSchema
 
-  private effectContext: {
-    runtime: Runtime.Runtime<Scope.Scope>
-    lifetimeScope: Scope.Scope
-  }
+  /** User-defined context attached to this Store (e.g. for dependency injection). */
+  readonly context: TContext
 
-  /** RC-based set to see which queries are currently subscribed to */
-  activeQueries: ReferenceCountedSet<LiveQuery<any>>
+  /** Options provided to the Store constructor. */
+  readonly params: StoreConstructorParams<TSchema, TContext>['params']
 
-  // NOTE this is currently exposed for the Devtools databrowser to commit events
-  readonly __eventSchema
-  readonly syncProcessor: ClientSessionSyncProcessor
+  /**
+   * Reactive connectivity updates emitted by the backing sync backend.
+   *
+   * @example
+   * ```ts
+   * import { Effect, Stream } from 'effect'
+   *
+   * const status = await store.networkStatus.pipe(Effect.runPromise)
+   *
+   * await store.networkStatus.changes.pipe(
+   *   Stream.tap((next) => console.log('network status update', next)),
+   *   Stream.runDrain,
+   *   Effect.scoped,
+   *   Effect.runPromise,
+   * )
+   * ```
+   */
+  readonly networkStatus: ClientSession['leaderThread']['networkStatus']
 
-  readonly boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
+  /**
+   * Indicates how data is being stored.
+   *
+   * - `persisted`: Data is persisted to disk (e.g., via OPFS on web, SQLite file on native)
+   * - `in-memory`: Data is only stored in memory and will be lost on page refresh
+   *
+   * The store operates in `in-memory` mode when persistent storage is unavailable,
+   * such as in Safari/Firefox private browsing mode where OPFS is restricted.
+   *
+   * @example
+   * ```tsx
+   * if (store.storageMode === 'in-memory') {
+   *   showWarning('Data will not be persisted in private browsing mode')
+   * }
+   * ```
+   */
+  readonly storageMode: StorageMode
 
-  // #region constructor
+  /**
+   * Store internals. Not part of the public API — shapes and semantics may change without notice.
+   */
+  readonly [StoreInternalsSymbol]: StoreInternals
+
+  //#region constructor
   constructor({
     clientSession,
     schema,
@@ -109,40 +198,53 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     params,
     confirmUnsavedChanges,
     __runningInDevtools,
-  }: StoreOptions<TSchema, TContext>) {
+  }: StoreConstructorParams<TSchema, TContext>) {
     super()
 
     this.storeId = storeId
-
-    this.sqliteDbWrapper = new SqliteDbWrapper({ otel: otelOptions, db: clientSession.sqliteDb })
-    this.clientSession = clientSession
     this.schema = schema
     this.context = context
-
-    this.effectContext = effectContext
+    this.params = params
+    this.networkStatus = clientSession.leaderThread.networkStatus
+    this.storageMode = clientSession.leaderThread.initialState.storageMode
 
     const reactivityGraph = makeReactivityGraph()
+    const stateHead = StateHead.make({ dbState: clientSession.sqliteDb })
 
-    const syncSpan = otelOptions.tracer.startSpan('LiveStore:sync', {}, otelOptions.rootSpanContext)
-
-    this.syncProcessor = makeClientSessionSyncProcessor({
+    const syncProcessor = makeClientSessionSyncProcessor({
       schema,
       clientSession,
-      runtime: effectContext.runtime,
       materializeEvent: Effect.fn('client-session-sync-processor:materialize-event')(
-        (eventDecoded, { withChangeset, materializerHashLeader }) =>
+        (eventEncoded, { materializerHashLeader }) =>
           // We need to use `Effect.gen` (even though we're using `Effect.fn`) so that we can pass `this` to the function
-          Effect.gen(this, function* () {
-            const { eventDef, materializer } = getEventDef(schema, eventDecoded.name)
+          Effect.gen({ self: this }, function* () {
+            const resolution = yield* resolveEventDef(schema, {
+              operation: '@livestore/livestore:store:materializeEvent',
+              event: eventEncoded,
+            })
+
+            if (resolution._tag === 'unknown') {
+              // Runtime schema doesn't know this event yet; skip materialization but
+              // keep the log entry so upgraded clients can replay it later.
+              yield* stateHead.set(eventEncoded.seqNum)
+              return {
+                writeTables: new Set<string>(),
+                sessionChangeset: { _tag: 'no-op' as const },
+                materializerHash: Option.none(),
+              }
+            }
+
+            const { eventDef, materializer } = resolution
 
             const execArgsArr = getExecStatementsFromMaterializer({
               eventDef,
               materializer,
-              dbState: this.sqliteDbWrapper,
-              event: { decoded: eventDecoded, encoded: undefined },
+              dbState: this[StoreInternalsSymbol].sqliteDbWrapper,
+              event: { decoded: undefined, encoded: eventEncoded },
             })
 
-            const materializerHash = isDevEnv() ? Option.some(hashMaterializerResults(execArgsArr)) : Option.none()
+            const materializerHash =
+              isDevEnv() === true ? Option.some(hashMaterializerResults(execArgsArr)) : Option.none()
 
             // Hash mismatch detection only occurs during the pull path (when receiving events from the leader).
             // During push path (local commits), materializerHashLeader is always Option.none(), so this condition
@@ -153,7 +255,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
               materializerHash._tag === 'Some' &&
               materializerHashLeader.value !== materializerHash.value
             ) {
-              return yield* MaterializerHashMismatchError.make({ eventName: eventDecoded.name })
+              return yield* MaterializerHashMismatchError.make({ eventName: eventEncoded.name })
             }
 
             const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
@@ -165,15 +267,18 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
               for (const {
                 statementSql,
                 bindValues,
-                writeTables = this.sqliteDbWrapper.getTablesUsed(statementSql),
+                writeTables = this[StoreInternalsSymbol].sqliteDbWrapper.getTablesUsed(statementSql),
               } of execArgsArr) {
                 try {
-                  this.sqliteDbWrapper.cachedExecute(statementSql, bindValues, { otelContext, writeTables })
+                  this[StoreInternalsSymbol].sqliteDbWrapper.cachedExecute(statementSql, bindValues, {
+                    otelContext,
+                    writeTables,
+                  })
                 } catch (cause) {
                   // TOOD refactor with `SqliteError`
-                  throw UnexpectedError.make({
+                  throw UnknownError.make({
                     cause,
-                    note: `Error executing materializer for event "${eventDecoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
+                    note: `Error executing materializer for event "${eventEncoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
                   })
                 }
 
@@ -182,52 +287,42 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
                   writeTablesForEvent.add(table)
                 }
 
-                this.sqliteDbWrapper.debug.head = eventDecoded.seqNum
+                this[StoreInternalsSymbol].sqliteDbWrapper.debug.head = eventEncoded.seqNum
               }
             }
 
-            let sessionChangeset:
-              | { _tag: 'sessionChangeset'; data: Uint8Array<ArrayBuffer>; debug: any }
-              | { _tag: 'no-op' }
-              | { _tag: 'unset' } = { _tag: 'unset' }
-            if (withChangeset === true) {
-              sessionChangeset = this.sqliteDbWrapper.withChangeset(exec).changeset
-            } else {
-              exec()
-            }
+            const sessionChangeset = this[StoreInternalsSymbol].sqliteDbWrapper.withChangeset(exec).changeset
+            yield* stateHead.set(eventEncoded.seqNum)
 
             return { writeTables: writeTablesForEvent, sessionChangeset, materializerHash }
-          }).pipe(Effect.mapError((cause) => MaterializeError.make({ cause }))),
+          }).pipe(
+            SqliteDbHelper.withSavepoint(clientSession.sqliteDb),
+            Effect.mapError((cause) => MaterializeError.make({ cause })),
+          ),
       ),
       rollback: (changeset) => {
-        this.sqliteDbWrapper.rollback(changeset)
+        this[StoreInternalsSymbol].sqliteDbWrapper.rollback(changeset)
       },
       refreshTables: (tables) => {
         const tablesToUpdate = [] as [Ref<null, ReactivityGraphContext, RefreshReason>, null][]
         for (const tableName of tables) {
-          const tableRef = this.tableRefs[tableName]
+          const tableRef = this[StoreInternalsSymbol].tableRefs[tableName]
           assertNever(tableRef !== undefined, `No table ref found for ${tableName}`)
           tablesToUpdate.push([tableRef!, null])
         }
         reactivityGraph.setRefs(tablesToUpdate)
       },
-      span: syncSpan,
       params: {
         ...omitUndefineds({
           leaderPushBatchSize: params.leaderPushBatchSize,
         }),
-        ...(params.simulation?.clientSessionSyncProcessor !== undefined
-          ? { simulation: params.simulation.clientSessionSyncProcessor }
-          : {}),
       },
       confirmUnsavedChanges,
-    })
-
-    this.__eventSchema = LiveStoreEvent.makeEventDefSchemaMemo(schema)
+    }).pipe(Effect.provideService(StateHead.StateHead, stateHead), Effect.runSyncWith(effectContext.services))
 
     // TODO generalize the `tableRefs` concept to allow finer-grained refs
-    this.tableRefs = {}
-    this.activeQueries = new ReferenceCountedSet()
+    const tableRefs: { [key: string]: Ref<null, ReactivityGraphContext, RefreshReason> } = {}
+    const activeQueries = new ReferenceCountedSet<LiveQuery<any>>()
 
     const commitsSpan = otelOptions.tracer.startSpan('LiveStore:commits', {}, otelOptions.rootSpanContext)
     const otelMuationsSpanContext = otel.trace.setSpan(otel.context.active(), commitsSpan)
@@ -235,8 +330,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     const queriesSpan = otelOptions.tracer.startSpan('LiveStore:queries', {}, otelOptions.rootSpanContext)
     const otelQueriesSpanContext = otel.trace.setSpan(otel.context.active(), queriesSpan)
 
-    this.reactivityGraph = reactivityGraph
-    this.reactivityGraph.context = {
+    reactivityGraph.context = {
       store: this as unknown as Store<LiveStoreSchema>,
       defRcMap: new Map(),
       reactivityGraph: new WeakRef(reactivityGraph),
@@ -244,8 +338,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
       rootOtelContext: otelQueriesSpanContext,
       effectsWrapper: batchUpdates,
     }
-
-    this.otel = {
+    const otelObj: StoreOtel = {
       tracer: otelOptions.tracer,
       rootSpanContext: otelOptions.rootSpanContext,
       commitsSpanContext: otelMuationsSpanContext,
@@ -256,58 +349,93 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     const allTableNames = new Set(
       // NOTE we're excluding the LiveStore schema and events tables as they are not user-facing
       // unless LiveStore is running in the devtools
-      __runningInDevtools
+      __runningInDevtools === true
         ? this.schema.state.sqlite.tables.keys()
         : Array.from(this.schema.state.sqlite.tables.keys()).filter((_) => !SystemTables.isStateSystemTable(_)),
     )
     const existingTableRefs = new Map(
-      Array.from(this.reactivityGraph.atoms.values())
+      Array.from(reactivityGraph.atoms.values())
         .filter((_): _ is Ref<any, any, any> => _._tag === 'ref' && _.label?.startsWith('tableRef:') === true)
         .map((_) => [_.label!.slice('tableRef:'.length), _] as const),
     )
     for (const tableName of allTableNames) {
-      this.tableRefs[tableName] =
+      tableRefs[tableName] =
         existingTableRefs.get(tableName) ??
-        this.reactivityGraph.makeRef(null, {
+        reactivityGraph.makeRef(null, {
           equal: () => false,
-          label: `tableRef:${tableName}`,
+          label: `tableRef:${String(tableName)}`,
           meta: { liveStoreRefType: 'table' },
         })
     }
 
-    this.boot = Effect.gen(this, function* () {
+    const boot = Effect.gen({ self: this }, function* () {
       yield* Effect.addFinalizer(() =>
         Effect.sync(() => {
           // Remove all table refs from the reactivity graph
-          for (const tableRef of Object.values(this.tableRefs)) {
+          for (const tableRef of Object.values(tableRefs)) {
             for (const superComp of tableRef.super) {
-              this.reactivityGraph.removeEdge(superComp, tableRef)
+              this[StoreInternalsSymbol].reactivityGraph.removeEdge(superComp, tableRef)
             }
           }
 
           // End the otel spans
-          syncSpan.end()
           commitsSpan.end()
           queriesSpan.end()
         }),
       )
 
-      yield* this.syncProcessor.boot
+      yield* syncProcessor.boot
     })
+
+    // Build Sqlite wrapper last to avoid using getters before internals are set
+    const sqliteDbWrapper = new SqliteDbWrapper({ otel: otelOptions, db: clientSession.sqliteDb })
+
+    // Initialize internals bag
+    this[StoreInternalsSymbol] = {
+      eventSchema: LiveStoreEvent.Client.makeSchemaMemo(schema) as Schema.Codec<
+        LiveStoreEvent.Client.Decoded,
+        LiveStoreEvent.Client.Encoded
+      >,
+      clientSession,
+      sqliteDbWrapper,
+      effectContext,
+      otel: otelObj,
+      reactivityGraph,
+      tableRefs,
+      activeQueries,
+      syncProcessor,
+      boot,
+      isShutdown: false,
+    }
+
+    // Initialize stable network status property from client session
+    this.networkStatus = clientSession.leaderThread.networkStatus
   }
-  // #endregion constructor
+  //#endregion constructor
 
+  /**
+   * Current session identifier for this Store instance.
+   *
+   * - Stable for the lifetime of the Store
+   * - Useful for correlating events or scoping per-session data
+   */
   get sessionId(): string {
-    return this.clientSession.sessionId
+    return this[StoreInternalsSymbol].clientSession.sessionId
   }
 
+  /**
+   * Stable client identifier for the process/device using this Store.
+   *
+   * - Shared across Store instances created by the same client
+   * - Useful for diagnostics and multi-client correlation
+   */
   get clientId(): string {
-    return this.clientSession.clientId
+    return this[StoreInternalsSymbol].clientSession.clientId
   }
 
   private checkShutdown = (operation: string): void => {
-    if (this.isShutdown) {
-      throw new UnexpectedError({
+    if (this[StoreInternalsSymbol].isShutdown === true) {
+      throw new UnknownError({
         cause: `Store has been shut down (while performing "${operation}").`,
         note: `You cannot perform this operation after the store has been shut down.`,
       })
@@ -315,80 +443,109 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
   }
 
   /**
-   * Subscribe to the results of a query
-   * Returns a function to cancel the subscription.
+   * Subscribe to the results of a query.
+   *
+   * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
+   * - Without a callback it returns an {@link AsyncIterable} that yields query results.
    *
    * @example
    * ```ts
-   * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+   * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
+   * ```
+   *
+   * @example
+   * ```ts
+   * for await (const result of store.subscribe(query$)) {
+   *   console.log(result)
+   * }
    * ```
    */
-  subscribe = <TResult>(
-    query: LiveQueryDef<TResult, 'def' | 'signal-def'> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>,
-    options: {
-      /** Called when the query result has changed */
-      onUpdate: (value: TResult) => void
-      onSubscribe?: (query$: LiveQuery<TResult>) => void
-      /** Gets called after the query subscription has been removed */
-      onUnsubsubscribe?: () => void
-      label?: string
-      /**
-       * Skips the initial `onUpdate` callback
-       * @default false
-       */
-      skipInitialRun?: boolean
-      otelContext?: otel.Context
-      /** If provided, the stack info will be added to the `activeSubscriptions` set of the query */
-      stackInfo?: StackInfo
-    },
+  subscribe = (<TResult>(
+    query: Queryable<TResult>,
+    onUpdateOrOptions?: ((value: TResult) => void) | SubscribeOptions<TResult>,
+    maybeOptions?: SubscribeOptions<TResult>,
+  ): Unsubscribe | AsyncIterable<TResult> => {
+    if (typeof onUpdateOrOptions === 'function') {
+      return this.subscribeWithCallback(query, onUpdateOrOptions, maybeOptions)
+    }
+
+    return this.subscribeAsAsyncIterable(query, onUpdateOrOptions)
+  }) as SubscribeFn
+
+  private subscribeWithCallback = <TResult>(
+    query: Queryable<TResult>,
+    onUpdate: (value: TResult) => void,
+    options?: SubscribeOptions<TResult>,
   ): Unsubscribe => {
     this.checkShutdown('subscribe')
 
-    return this.otel.tracer.startActiveSpan(
+    return this[StoreInternalsSymbol].otel.tracer.startActiveSpan(
       `LiveStore.subscribe`,
-      { attributes: { label: options?.label, queryLabel: isQueryBuilder(query) ? query.toString() : query.label } },
-      options?.otelContext ?? this.otel.queriesSpanContext,
+      {
+        attributes: {
+          label: options?.label,
+          queryLabel: isQueryBuilder(query) === true ? query.toString() : query.label,
+        },
+      },
+      options?.otelContext ?? this[StoreInternalsSymbol].otel.queriesSpanContext,
       (span) => {
-        // console.debug('store sub', query$.id, query$.label)
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
-        const queryRcRef = isQueryBuilder(query)
-          ? queryDb(query).make(this.reactivityGraph.context!)
-          : query._tag === 'def' || query._tag === 'signal-def'
-            ? query.make(this.reactivityGraph.context!)
-            : {
-                value: query as LiveQuery<TResult>,
-                deref: () => {},
-              }
+        const queryRcRef =
+          isQueryBuilder(query) === true
+            ? queryDb(query).make(this[StoreInternalsSymbol].reactivityGraph.context!)
+            : query._tag === 'def' || query._tag === 'signal-def'
+              ? query.make(this[StoreInternalsSymbol].reactivityGraph.context!)
+              : {
+                  value: query,
+                  deref: () => {},
+                }
         const query$ = queryRcRef.value
 
         const label = `subscribe:${options?.label}`
-        const effect = this.reactivityGraph.makeEffect(
-          (get, _otelContext, debugRefreshReason) =>
-            options.onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
+        let suppressCallback = options?.skipInitialRun === true
+        const effect = this[StoreInternalsSymbol].reactivityGraph.makeEffect(
+          (get, _otelContext, debugRefreshReason) => {
+            const result = get(query$.results$, otelContext, debugRefreshReason)
+            if (suppressCallback === true) {
+              return
+            }
+            onUpdate(result)
+          },
           { label },
         )
+        const runInitialEffect = () => {
+          effect.doEffect(otelContext, {
+            _tag: 'subscribe.initial',
+            label: `subscribe-initial-run:${options?.label}`,
+          })
+        }
 
-        if (options?.stackInfo) {
+        if (options?.stackInfo !== undefined) {
           query$.activeSubscriptions.add(options.stackInfo)
         }
 
         options?.onSubscribe?.(query$)
 
-        this.activeQueries.add(query$ as LiveQuery<TResult>)
+        this[StoreInternalsSymbol].activeQueries.add(query$ as LiveQuery<TResult>)
 
-        // Running effect right away to get initial value (unless `skipInitialRun` is set)
-        if (options?.skipInitialRun !== true && !query$.isDestroyed) {
-          effect.doEffect(otelContext, { _tag: 'subscribe.initial', label: `subscribe-initial-run:${options?.label}` })
+        if (query$.isDestroyed === false) {
+          if (suppressCallback === true) {
+            // We still run once to register dependencies in the reactive graph, but suppress the initial callback so the
+            // caller truly skips the first emission; subsequent runs (after commits) will call the callback.
+            runInitialEffect()
+            suppressCallback = false
+          } else {
+            runInitialEffect()
+          }
         }
 
         const unsubscribe = () => {
-          // console.debug('store unsub', query$.id, query$.label)
           try {
-            this.reactivityGraph.destroyNode(effect)
-            this.activeQueries.remove(query$ as LiveQuery<TResult>)
+            this[StoreInternalsSymbol].reactivityGraph.destroyNode(effect)
+            this[StoreInternalsSymbol].activeQueries.remove(query$ as LiveQuery<TResult>)
 
-            if (options?.stackInfo) {
+            if (options?.stackInfo !== undefined) {
               query$.activeSubscriptions.delete(options.stackInfo)
             }
 
@@ -405,23 +562,117 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     )
   }
 
-  subscribeStream = <TResult>(
-    query$: LiveQueryDef<TResult>,
-    options?: { label?: string; skipInitialRun?: boolean } | undefined,
-  ): Stream.Stream<TResult> =>
-    Stream.asyncPush<TResult>((emit) =>
-      Effect.gen(this, function* () {
+  private subscribeAsAsyncIterable = <TResult>(
+    query: Queryable<TResult>,
+    options?: SubscribeOptions<TResult>,
+  ): AsyncIterable<TResult> => {
+    this.checkShutdown('subscribe')
+
+    // This used to delegate to `Stream.toAsyncIterable(this.subscribeStream(...))`.
+    // With Effect v4, the callback-backed stream producer is forked during stream startup, so a caller could request
+    // `next()`, commit an update, and race the actual subscription registration. Register directly here so the first
+    // pending `next()` observes post-subscription updates. In the future, this should be refactored back toward a shared
+    // stream/async-iterable bridge if Effect exposes a primitive with that synchronous registration guarantee.
+    return {
+      [Symbol.asyncIterator]: () => {
+        const services = this[StoreInternalsSymbol].effectContext.services
+        const runSync = Effect.runSyncWith(services)
+        const runPromiseExit = Effect.runPromiseExitWith(services)
+        let queue: Queue.Queue<TResult, Cause.Done> | undefined
+        let isDone = false
+        let unsubscribe: Unsubscribe | undefined
+
+        const done = (): IteratorResult<TResult> => ({ done: true, value: undefined })
+        const isClosed = () => isDone
+        const isQueueDone = (cause: Cause.Cause<Cause.Done>) => {
+          const error = Cause.findError(cause)
+          return Result.isSuccess(error) && Cause.isDone(error.success)
+        }
+
+        const ensureQueue = () => {
+          // Lazily allocate the queue so creating an async iterator without consuming it has no subscription-side work.
+          queue ??= Queue.unbounded<TResult, Cause.Done>().pipe(runSync)
+          return queue
+        }
+
+        const emit = (value: TResult) => {
+          if (isDone === true) return
+
+          Queue.offerUnsafe(ensureQueue(), value)
+        }
+
+        const ensureSubscribed = () => {
+          // Subscribe from the first `next()` call so callers that request a value before
+          // committing updates don't race the asynchronous Stream-to-iterator startup path.
+          unsubscribe ??= this.subscribeWithCallback(query, emit, options)
+        }
+
+        const close = (): IteratorResult<TResult> => {
+          if (isDone === false) {
+            isDone = true
+            unsubscribe?.()
+            unsubscribe = undefined
+
+            if (queue !== undefined) {
+              // Wake any pending `next()` call and prevent later callback emissions from being buffered.
+              Queue.shutdown(queue).pipe(runSync)
+            }
+          }
+
+          return done()
+        }
+
+        return {
+          next: async () => {
+            if (isDone === true) {
+              return done()
+            }
+
+            ensureSubscribed()
+
+            // Delegate buffering and pending-consumer wakeups to Effect's queue implementation.
+            const exit = await runPromiseExit(Queue.take(ensureQueue()))
+            if (Exit.isSuccess(exit) === true) {
+              return { done: false, value: exit.value }
+            }
+
+            if (isClosed() === true || isQueueDone(exit.cause) === true) {
+              return done()
+            }
+
+            throw Cause.squash(exit.cause)
+          },
+          return: () => Promise.resolve(close()),
+          throw: (cause) => {
+            close()
+            return Promise.reject(cause)
+          },
+        }
+      },
+    }
+  }
+
+  subscribeStream = <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): Stream.Stream<TResult> =>
+    Stream.callback<TResult>((emit) =>
+      Effect.gen({ self: this }, function* () {
         const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(
-          Effect.catchTag('NoSuchElementException', () => Effect.succeed(undefined)),
+          Effect.catchTag('NoSuchElementError', () => Effect.void),
         )
-        const otelContext = otelSpan ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active()
+        const otelContext =
+          otelSpan !== undefined ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active()
 
         yield* Effect.acquireRelease(
           Effect.sync(() =>
-            this.subscribe(query$, {
-              onUpdate: (result) => emit.single(result),
-              ...omitUndefineds({ otelContext, label: options?.label }),
-            }),
+            this.subscribe(
+              query,
+              (result) => {
+                Queue.offerUnsafe(emit, result)
+              },
+              {
+                ...options,
+                otelContext,
+              },
+            ),
           ),
           (unsub) => Effect.sync(() => unsub()),
         )
@@ -443,25 +694,24 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    * ```
    */
   query = <TResult>(
-    query:
-      | QueryBuilder<TResult, any, any>
-      | LiveQuery<TResult>
-      | LiveQueryDef<TResult>
-      | SignalDef<TResult>
-      | { query: string; bindValues: Bindable; schema?: Schema.Schema<TResult> },
+    query: Queryable<TResult> | { query: string; bindValues: Bindable; schema?: Schema.Decoder<TResult> },
     options?: { otelContext?: otel.Context; debugRefreshReason?: RefreshReason },
   ): TResult => {
     this.checkShutdown('query')
 
     if (typeof query === 'object' && 'query' in query && 'bindValues' in query) {
-      const res = this.sqliteDbWrapper.cachedSelect(query.query, prepareBindValues(query.bindValues, query.query), {
-        ...omitUndefineds({ otelContext: options?.otelContext }),
-      }) as any
-      if (query.schema) {
-        return Schema.decodeSync(query.schema)(res)
+      const res = this[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(
+        query.query,
+        prepareBindValues(query.bindValues, query.query),
+        {
+          ...omitUndefineds({ otelContext: options?.otelContext }),
+        },
+      ) as any
+      if (query.schema !== undefined) {
+        return Schema.decodeUnknownSync(query.schema)(res)
       }
       return res
-    } else if (isQueryBuilder(query)) {
+    } else if (isQueryBuilder(query) === true) {
       const ast = query[QueryBuilderAstSymbol]
       if (ast._tag === 'RowQuery') {
         makeExecBeforeFirstRun({
@@ -469,42 +719,48 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
           id: ast.id,
           explicitDefaultValues: ast.explicitDefaultValues,
           otelContext: options?.otelContext,
-        })(this.reactivityGraph.context!)
+        })(this[StoreInternalsSymbol].reactivityGraph.context!)
       }
 
       const sqlRes = query.asSql()
       const schema = getResultSchema(query)
 
-      // Replace SessionIdSymbol in bind values before executing the query
-      if (sqlRes.bindValues) {
-        replaceSessionIdSymbol(sqlRes.bindValues, this.clientSession.sessionId)
-      }
-
-      const rawRes = this.sqliteDbWrapper.cachedSelect(sqlRes.query, sqlRes.bindValues as any as PreparedBindValues, {
-        ...omitUndefineds({ otelContext: options?.otelContext }),
-        queriedTables: new Set([query[QueryBuilderAstSymbol].tableDef.sqliteDef.name]),
-      })
+      // Query builders preserve SessionIdSymbol so client-document queries can be reused across sessions.
+      // SQLite bind values must be concrete primitives, so resolve the symbol only at execution time.
+      const resolvedBindValues =
+        sqlRes.bindValues === undefined
+          ? undefined
+          : resolveSessionIdSymbolInBindValues(sqlRes.bindValues, this[StoreInternalsSymbol].clientSession.sessionId)
+
+      const rawRes = this[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(
+        sqlRes.query,
+        resolvedBindValues === undefined ? undefined : prepareBindValues(resolvedBindValues, sqlRes.query),
+        {
+          ...omitUndefineds({ otelContext: options?.otelContext }),
+          queriedTables: new Set([query[QueryBuilderAstSymbol].tableDef.sqliteDef.name]),
+        },
+      )
 
-      const decodeResult = Schema.decodeEither(schema)(rawRes)
-      if (decodeResult._tag === 'Right') {
-        return decodeResult.right
+      const decodeResult = Schema.decodeResult(schema)(rawRes)
+      if (Result.isSuccess(decodeResult) === true) {
+        return decodeResult.success
       } else {
         return shouldNeverHappen(
-          `Failed to decode query result with for schema:`,
-          schema.toString(),
+          'Failed to decode query result with for schema:',
+          objectToString(schema),
           'raw result:',
           rawRes,
           'decode error:',
-          decodeResult.left,
+          decodeResult.failure,
         )
       }
     } else if (query._tag === 'def') {
-      const query$ = query.make(this.reactivityGraph.context!)
+      const query$ = query.make(this[StoreInternalsSymbol].reactivityGraph.context!)
       const result = this.query(query$.value, options)
       query$.deref()
       return result
     } else if (query._tag === 'signal-def') {
-      const signal$ = query.make(this.reactivityGraph.context!)
+      const signal$ = query.make(this[StoreInternalsSymbol].reactivityGraph.context!)
       return signal$.value.get()
     } else {
       return query.run({
@@ -531,7 +787,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
   setSignal = <T>(signalDef: SignalDef<T>, value: T | ((prev: T) => T)): void => {
     this.checkShutdown('setSignal')
 
-    const signalRef = signalDef.make(this.reactivityGraph.context!)
+    const signalRef = signalDef.make(this[StoreInternalsSymbol].reactivityGraph.context!)
     const newValue: T = typeof value === 'function' ? (value as any)(signalRef.value.get()) : value
     signalRef.value.set(newValue)
 
@@ -545,7 +801,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     }
   }
 
-  // #region commit
+  //#region commit
   /**
    * Commit a list of events to the store which will immediately update the local database
    * and sync the events across other clients (similar to a `git commit`).
@@ -598,19 +854,19 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    * ```
    */
   commit: {
-    <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(...list: TCommitArg): void
+    <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(...list: TCommitArg): void
     (
-      txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(
+      txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(
         ...list: TCommitArg
       ) => void,
     ): void
-    <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(
+    <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(
       options: StoreCommitOptions,
       ...list: TCommitArg
     ): void
     (
       options: StoreCommitOptions,
-      txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(
+      txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(
         ...list: TCommitArg
       ) => void,
     ): void
@@ -619,41 +875,34 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
 
     const { events, options } = this.getCommitArgs(firstEventOrTxnFnOrOptions, restEvents)
 
-    Effect.gen(this, function* () {
-      const commitsSpan = otel.trace.getSpan(this.otel.commitsSpanContext)
+    Effect.gen({ self: this }, function* () {
+      const commitsSpan = otel.trace.getSpan(this[StoreInternalsSymbol].otel.commitsSpanContext)
       commitsSpan?.addEvent('commit')
       const currentSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
       commitsSpan?.addLink({ context: currentSpan.spanContext() })
 
-      for (const event of events) {
-        replaceSessionIdSymbol(event.args, this.clientSession.sessionId)
-      }
-
       if (events.length === 0) return
 
-      const localRuntime = yield* Effect.runtime()
+      const localServices = yield* Effect.context()
 
-      const materializeEventsTx = Effect.try({
-        try: () => {
-          const runMaterializeEvents = () => {
-            return this.syncProcessor.push(events).pipe(Runtime.runSync(localRuntime))
-          }
+      const encodedEvents = yield* this[StoreInternalsSymbol].syncProcessor.encodeEvents(events)
 
-          if (events.length > 1) {
-            return this.sqliteDbWrapper.txn(runMaterializeEvents)
-          } else {
-            return runMaterializeEvents()
-          }
+      const { writeTables } = yield* Effect.try({
+        try: () => {
+          const materialize = () =>
+            this[StoreInternalsSymbol].syncProcessor
+              .materializeEvents(encodedEvents)
+              .pipe(Effect.runSyncWith(localServices))
+          return events.length > 1 ? this[StoreInternalsSymbol].sqliteDbWrapper.txn(materialize) : materialize()
         },
-        catch: (cause) => UnexpectedError.make({ cause }),
+        catch: (cause) => UnknownError.make({ cause }),
       })
 
-      // Materialize events to state
-      const { writeTables } = yield* materializeEventsTx
+      yield* this[StoreInternalsSymbol].syncProcessor.push(encodedEvents)
 
       const tablesToUpdate: [Ref<null, ReactivityGraphContext, RefreshReason>, null][] = []
       for (const tableName of writeTables) {
-        const tableRef = this.tableRefs[tableName]
+        const tableRef = this[StoreInternalsSymbol].tableRefs[tableName]
         assertNever(tableRef !== undefined, `No table ref found for ${tableName}`)
         tablesToUpdate.push([tableRef!, null])
       }
@@ -666,7 +915,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
       const skipRefresh = options?.skipRefresh ?? false
 
       // Update all table refs together in a batch, to only trigger one reactive update
-      this.reactivityGraph.setRefs(tablesToUpdate, {
+      this[StoreInternalsSymbol].reactivityGraph.setRefs(tablesToUpdate, {
         debugRefreshReason,
         skipRefresh,
         otelContext: otel.trace.setSpan(otel.context.active(), currentSpan),
@@ -681,46 +930,204 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
         },
         links: [
           // Span link to LiveStore:commits
-          OtelTracer.makeSpanLink({ context: otel.trace.getSpanContext(this.otel.commitsSpanContext)! }),
+          OtelTracer.makeSpanLink({
+            context: otel.trace.getSpanContext(this[StoreInternalsSymbol].otel.commitsSpanContext)!,
+          }),
           // User-provided span links
           ...(options?.spanLinks?.map(OtelTracer.makeSpanLink) ?? []),
         ],
       }),
-      Effect.tapErrorCause(Effect.logError),
-      Effect.catchAllCause((cause) => Effect.fork(this.shutdown(cause))),
-      Runtime.runSync(this.effectContext.runtime),
+      Effect.tapCause(Effect.logError),
+      Effect.catchCause((cause) => Effect.forkChild(this.shutdown(cause))),
+      Effect.runSyncWith(this[StoreInternalsSymbol].effectContext.services),
     )
   }
-  // #endregion commit
+  //#endregion commit
 
   /**
-   * Returns an async iterable of events.
+   * Returns an async iterable of events from the eventlog.
+   * Currently only events confirmed by the sync backend is supported.
+   *
+   * Defaults to tracking upstreamHead as it advances. If an `until` event is
+   * supplied the stream finalizes upon reaching it.
+   *
+   * To start streaming from a specific point in the eventlog
+   * you can provide a `since` event.
+   *
+   * Allows filtering by:
+   *  - `filter`: event types
+   *  - `clientIds`: client identifiers
+   *  - `sessionIds`: session identifiers
+   *
+   * The batchSize option controls the maximum amount of events that are fetched
+   * from the eventlog in each query. Defaults to 100 and has a max allowed
+   * value of 1000.
+   *
+   * TODO:
+   * - Support streaming unconfirmed events
+   *  - Leader level
+   *  - Session level
+   * - Support streaming client-only events
    *
    * @example
    * ```ts
-   * for await (const event of store.events()) {
+   * // Stream todoCompleted events from the start
+   * for await (const event of store.events(filter: ['todoCompleted'])) {
    *   console.log(event)
    * }
    * ```
    *
    * @example
    * ```ts
-   * // Get all events from the beginning of time
-   * for await (const event of store.events({ cursor: EventSequenceNumber.ROOT })) {
+   * // Start streaming from a specific event
+   * for await (const event of store.events({ since: EventSequenceNumber.Client.fromString('e3') })) {
    *   console.log(event)
    * }
    * ```
    */
-  events = (_options?: StoreEventsOptions<TSchema>): AsyncIterable<LiveStoreEvent.ForSchema<TSchema>> => {
-    this.checkShutdown('events')
+  events = (options?: StoreEventsOptions<TSchema>): AsyncIterable<LiveStoreEvent.Client.ForSchema<TSchema>> => {
+    const stream = this.eventsStream(options)
+    return {
+      async *[Symbol.asyncIterator]() {
+        const iterator = Stream.toAsyncIterable(stream)
+        for await (const event of iterator) {
+          yield event
+        }
+      },
+    }
+  }
+
+  /**
+   * Returns an Effect Stream of events from the eventlog.
+   * See `store.events` for details on options and behaviour.
+   */
+  eventsStream = (
+    options?: StoreEventsOptions<TSchema>,
+  ): Stream.Stream<LiveStoreEvent.Client.ForSchema<TSchema>, UnknownError> => {
+    const { clientSession } = this[StoreInternalsSymbol]
+    const eventSchema = LiveStoreEvent.Client.makeSchema(this.schema)
+
+    const preferredBatchSize =
+      options?.batchSize ?? this.params.eventQueryBatchSize ?? STORE_DEFAULT_PARAMS.eventQueryBatchSize
+
+    const baseOptions: StreamEventsOptions = {
+      ...options,
+      filter: options?.filter as readonly string[],
+      batchSize: preferredBatchSize,
+    }
 
-    return notYetImplemented(`store.events() is not yet implemented but planned soon`)
+    return clientSession.leaderThread.events.stream(baseOptions).pipe(
+      Stream.mapEffect((event) => Schema.decodeEffect(eventSchema)(event)),
+      Stream.catchTag('SchemaError', (cause) => Stream.fail(UnknownError.make({ cause }))),
+      Stream.tapError((error) => Effect.logError('Error in eventsStream', error)),
+    )
   }
 
-  eventsStream = (_options?: StoreEventsOptions<TSchema>): Stream.Stream<LiveStoreEvent.ForSchema<TSchema>> => {
-    this.checkShutdown('eventsStream')
+  /**
+   * Returns the current synchronization status of the store.
+   *
+   * This is a synchronous operation that returns the sync state between the
+   * client session and the leader thread. Use this to display sync indicators
+   * or check if local changes have been pushed to the leader.
+   *
+   * @example
+   * ```ts
+   * const status = store.syncStatus()
+   * console.log(status.isSynced ? 'Synced' : `${status.pendingCount} pending`)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Health check for backend connectivity
+   * const status = store.syncStatus()
+   * if (!status.isSynced && status.pendingCount > 100) {
+   *   console.warn('Large backlog of unsynced events')
+   * }
+   * ```
+   */
+  syncStatus = (): SyncStatus => {
+    this.checkShutdown('syncStatus')
+
+    const syncState = this[StoreInternalsSymbol].syncProcessor.syncState.pipe(Effect.runSync)
+    const pendingCount = syncState.pending.length
+
+    return {
+      localHead: EventSequenceNumber.Client.toString(syncState.localHead),
+      upstreamHead: EventSequenceNumber.Client.toString(syncState.upstreamHead),
+      pendingCount,
+      isSynced: pendingCount === 0,
+    }
+  }
+
+  /**
+   * Returns an Effect Stream of sync status updates.
+   *
+   * Emits the current status immediately and then whenever the sync state changes.
+   * Use this for Effect-based workflows or when you need more control over the stream.
+   *
+   * @example
+   * ```ts
+   * store.syncStatusStream().pipe(
+   *   Stream.tap((status) => Effect.log(`Sync status: ${status.isSynced}`)),
+   *   Stream.runDrain,
+   * )
+   * ```
+   */
+  syncStatusStream = (): Stream.Stream<SyncStatus> => {
+    const syncStateSubscribable = this[StoreInternalsSymbol].syncProcessor.syncState
+
+    return Stream.concat(
+      Stream.fromEffect(syncStateSubscribable.pipe(Effect.map(this.makeSyncStatus))),
+      syncStateSubscribable.changes.pipe(Stream.map(this.makeSyncStatus)),
+    )
+  }
+
+  /**
+   * Subscribes to sync status changes.
+   *
+   * The callback is invoked immediately with the current status and then
+   * whenever the sync state changes (e.g., when events are pushed or confirmed).
+   *
+   * @param onUpdate - Callback invoked with the current sync status
+   * @returns Unsubscribe function to stop receiving updates
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = store.subscribeSyncStatus((status) => {
+   *   updateUI(status.isSynced ? 'Synced' : 'Syncing...')
+   * })
+   *
+   * // Later, stop listening
+   * unsubscribe()
+   * ```
+   */
+  subscribeSyncStatus = (onUpdate: (status: SyncStatus) => void): Unsubscribe => {
+    this.checkShutdown('subscribeSyncStatus')
+
+    const fiber = this.syncStatusStream().pipe(
+      Stream.tap((status) => Effect.sync(() => onUpdate(status))),
+      Stream.runDrain,
+      this.runEffectFork,
+    )
 
-    return notYetImplemented(`store.eventsStream() is not yet implemented but planned soon`)
+    return () => {
+      Fiber.interrupt(fiber).pipe(Effect.runForkWith(this[StoreInternalsSymbol].effectContext.services))
+    }
+  }
+
+  private makeSyncStatus = (syncState: {
+    localHead: EventSequenceNumber.Client.Composite
+    upstreamHead: EventSequenceNumber.Client.Composite
+    pending: readonly any[]
+  }): SyncStatus => {
+    const pendingCount = syncState.pending.length
+
+    return {
+      localHead: EventSequenceNumber.Client.toString(syncState.localHead),
+      upstreamHead: EventSequenceNumber.Client.toString(syncState.upstreamHead),
+      pendingCount,
+      isSynced: pendingCount === 0,
+    }
   }
 
   /**
@@ -731,13 +1138,13 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     this.checkShutdown('manualRefresh')
 
     const { label } = options ?? {}
-    this.otel.tracer.startActiveSpan(
+    this[StoreInternalsSymbol].otel.tracer.startActiveSpan(
       'LiveStore:manualRefresh',
       { attributes: { 'livestore.manualRefreshLabel': label } },
-      this.otel.commitsSpanContext,
+      this[StoreInternalsSymbol].otel.commitsSpanContext,
       (span) => {
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
-        this.reactivityGraph.runDeferredEffects({ otelContext })
+        this[StoreInternalsSymbol].reactivityGraph.runDeferredEffects({ otelContext })
         span.end()
       },
     )
@@ -748,11 +1155,15 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    *
    * This is called automatically when the store was created using the React or Effect API.
    */
-  shutdownPromise = async (cause?: UnexpectedError) => {
+  shutdownPromise = async (cause?: UnknownError) => {
     this.checkShutdown('shutdownPromise')
 
-    this.isShutdown = true
-    await this.shutdown(cause ? Cause.fail(cause) : undefined).pipe(this.runEffectFork, Fiber.join, Effect.runPromise)
+    this[StoreInternalsSymbol].isShutdown = true
+    await this.shutdown(cause !== undefined ? Cause.fail(cause) : undefined).pipe(
+      this.runEffectFork,
+      Fiber.join,
+      Effect.runPromise,
+    )
   }
 
   /**
@@ -760,10 +1171,10 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    *
    * This is called automatically when the store was created using the React or Effect API.
    */
-  shutdown = (cause?: Cause.Cause<UnexpectedError | MaterializeError>): Effect.Effect<void> => {
-    this.isShutdown = true
-    return this.clientSession.shutdown(
-      cause ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })),
+  shutdown = (cause?: Cause.Cause<UnknownError | MaterializeError>): Effect.Effect<void> => {
+    this[StoreInternalsSymbol].isShutdown = true
+    return this[StoreInternalsSymbol].clientSession.shutdown(
+      cause !== undefined ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })),
     )
   }
 
@@ -774,31 +1185,34 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    */
   _dev = {
     downloadDb: (source: 'local' | 'leader' = 'local') => {
-      Effect.gen(this, function* () {
-        const data = source === 'local' ? this.sqliteDbWrapper.export() : yield* this.clientSession.leaderThread.export
+      Effect.gen({ self: this }, function* () {
+        const data =
+          source === 'local'
+            ? this[StoreInternalsSymbol].sqliteDbWrapper.export()
+            : yield* this[StoreInternalsSymbol].clientSession.leaderThread.export
         downloadBlob(data, `livestore-${Date.now()}.db`)
       }).pipe(this.runEffectFork)
     },
 
     downloadEventlogDb: () => {
-      Effect.gen(this, function* () {
-        const data = yield* this.clientSession.leaderThread.getEventlogData
+      Effect.gen({ self: this }, function* () {
+        const data = yield* this[StoreInternalsSymbol].clientSession.leaderThread.getEventlogData
         downloadBlob(data, `livestore-eventlog-${Date.now()}.db`)
       }).pipe(this.runEffectFork)
     },
 
     hardReset: (mode: 'all-data' | 'only-app-db' = 'all-data') => {
-      Effect.gen(this, function* () {
-        const clientId = this.clientSession.clientId
-        yield* this.clientSession.leaderThread.sendDevtoolsMessage(
+      Effect.gen({ self: this }, function* () {
+        const clientId = this[StoreInternalsSymbol].clientSession.clientId
+        yield* this[StoreInternalsSymbol].clientSession.leaderThread.sendDevtoolsMessage(
           Devtools.Leader.ResetAllData.Request.make({ liveStoreVersion, mode, requestId: nanoid(), clientId }),
         )
       }).pipe(this.runEffectFork)
     },
 
     overrideNetworkStatus: (status: 'online' | 'offline') => {
-      const clientId = this.clientSession.clientId
-      this.clientSession.leaderThread
+      const clientId = this[StoreInternalsSymbol].clientSession.clientId
+      this[StoreInternalsSymbol].clientSession.leaderThread
         .sendDevtoolsMessage(
           Devtools.Leader.SetSyncLatch.Request.make({
             clientId,
@@ -810,56 +1224,60 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
         .pipe(this.runEffectFork)
     },
 
-    syncStates: () =>
-      Effect.gen(this, function* () {
-        const session = yield* this.syncProcessor.syncState
-        const leader = yield* this.clientSession.leaderThread.getSyncState
+    // NOTE: Explicit return type needed to avoid TS2742 (inferred type references internal path)
+    syncStates: (): Promise<{ session: SyncState.SyncState; leader: SyncState.SyncState }> =>
+      Effect.gen({ self: this }, function* () {
+        const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState
+        const leader = yield* this[StoreInternalsSymbol].clientSession.leaderThread.syncState
         return { session, leader }
       }).pipe(this.runEffectPromise),
 
     printSyncStates: () => {
-      Effect.gen(this, function* () {
-        const session = yield* this.syncProcessor.syncState
+      Effect.gen({ self: this }, function* () {
+        const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState
         yield* Effect.log(
-          `Session sync state: ${session.localHead} (upstream: ${session.upstreamHead})`,
+          `Session sync state: ${objectToString(session.localHead)} (upstream: ${objectToString(session.upstreamHead)})`,
           session.toJSON(),
         )
-        const leader = yield* this.clientSession.leaderThread.getSyncState
-        yield* Effect.log(`Leader sync state: ${leader.localHead} (upstream: ${leader.upstreamHead})`, leader.toJSON())
+        const leader = yield* this[StoreInternalsSymbol].clientSession.leaderThread.syncState
+        yield* Effect.log(
+          `Leader sync state: ${objectToString(leader.localHead)} (upstream: ${objectToString(leader.upstreamHead)})`,
+          leader.toJSON(),
+        )
       }).pipe(this.runEffectFork)
     },
 
     version: liveStoreVersion,
 
     otel: {
-      rootSpanContext: () => otel.trace.getSpan(this.otel.rootSpanContext)?.spanContext(),
+      rootSpanContext: () => otel.trace.getSpan(this[StoreInternalsSymbol].otel.rootSpanContext)?.spanContext(),
     },
   }
 
   // NOTE This is needed because when booting a Store via Effect it seems to call `toJSON` in the error path
   toJSON = () => ({
     _tag: 'livestore.Store',
-    reactivityGraph: this.reactivityGraph.getSnapshot({ includeResults: true }),
+    reactivityGraph: this[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true }),
   })
 
   private runEffectFork = <A, E>(effect: Effect.Effect<A, E, Scope.Scope>) =>
     effect.pipe(
-      Effect.forkIn(this.effectContext.lifetimeScope),
+      Effect.forkIn(this[StoreInternalsSymbol].effectContext.lifetimeScope),
       Effect.tapCauseLogPretty,
-      Runtime.runFork(this.effectContext.runtime),
+      Effect.runForkWith(this[StoreInternalsSymbol].effectContext.services),
     )
 
   private runEffectPromise = <A, E>(effect: Effect.Effect<A, E, Scope.Scope>) =>
-    effect.pipe(Effect.tapCauseLogPretty, Runtime.runPromise(this.effectContext.runtime))
+    effect.pipe(Effect.tapCauseLogPretty, Effect.runPromiseWith(this[StoreInternalsSymbol].effectContext.services))
 
   private getCommitArgs = (
     firstEventOrTxnFnOrOptions: any,
     restEvents: any[],
   ): {
-    events: LiveStoreEvent.PartialForSchema<TSchema>[]
+    events: LiveStoreEvent.Input.ForSchema<TSchema>[]
     options: StoreCommitOptions | undefined
   } => {
-    let events: LiveStoreEvent.PartialForSchema<TSchema>[]
+    let events: LiveStoreEvent.Input.ForSchema<TSchema>[]
     let options: StoreCommitOptions | undefined
 
     if (typeof firstEventOrTxnFnOrOptions === 'function') {
@@ -880,12 +1298,6 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
       events = [firstEventOrTxnFnOrOptions, ...restEvents]
     }
 
-    // for (const event of events) {
-    //   if (event.args.id === SessionIdSymbol) {
-    //     event.args.id = this.clientSession.sessionId
-    //   }
-    // }
-
     return { events, options }
   }
 }