@evolu/common 8.9.0 → 8.11.0

package/src/local-first/Evolu.ts

@@ -18,6 +18,8 @@ import {
 import { createCallbacks } from "../Callbacks.ts";
 import type { ConsoleDep } from "../Console.ts";
 import { createConsole } from "../Console.ts";
+import type { DecryptWithXChaCha20Poly1305Error } from "../Crypto.ts";
+import type { UnknownError } from "../Error.ts";
 import { createUnknownError } from "../Error.ts";
 import { disposable, exhaustiveCheck, todo } from "../Function.ts";
 import {
@@ -45,11 +47,11 @@ import {
   UrlSafeString,
 } from "../Type.ts";
 import type {
+  BroadcastChannel,
   CreateBroadcastChannelDep,
   CreateMessageChannelDep,
 } from "../Worker.ts";
-import type { CreateDbWorkerDep } from "./Db.ts";
-import type { EvoluError } from "./Error.ts";
+import type { CreateDbWorkerDep, UnsupportedDbVersionError } from "./Db.ts";
 import type {
   AppOwner,
   Owner,
@@ -59,6 +61,7 @@ import type {
   SyncOwner,
 } from "./Owner.ts";
 import { createOwnerWebSocketTransport } from "./Owner.ts";
+import type { ProtocolError, ProtocolQuotaError } from "./Protocol.ts";
 import type {
   Queries,
   QueriesToQueryRowsPromises,
@@ -73,6 +76,7 @@ import type {
   IndexesConfig,
   Mutation,
   MutationChange,
+  MutationOptions,
   ValidateSchema,
 } from "./Schema.ts";
 import { evoluSchemaToSqliteSchema } from "./Schema.ts";
@@ -80,23 +84,41 @@ import type {
   ConsoleEntryOrError,
   EvoluInput,
   EvoluOutput,
+  OtherBuildRunningError,
   SharedWorkerDep,
+  SyncState,
+  syncStateToOwnerSyncStates,
 } from "./Shared.ts";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
-import { DbChange } from "./Storage.ts";
+import { DbChange, type StorageQuotaError } from "./Storage.ts";
 import type { Timestamp } from "./Timestamp.ts";
 
+/**
+ * Configuration for {@link createEvolu}.
+ *
+ * @group Configuration
+ */
 export interface EvoluConfig {
   /**
-   * The app name. Evolu is multitenant - it can run multiple instances
-   * concurrently. The same app can have multiple instances for different
-   * accounts.
+   * An application name used in logs and local database names.
+   *
+   * Evolu combines `appName` with the {@link AppOwner} identity to identify the
+   * local database. Changing either opens a different database. Keep `appName`
+   * stable across ordinary application updates.
    *
-   * Evolu derives the final instance name from `appName` and `appOwner` in
-   * {@link EvoluConfig}. The derived instance name is used as the SQLite
-   * database filename and as the log prefix. This ensures that each
-   * {@link Owner} gets a separate local database while preserving a readable app
-   * prefix.
+   * Instances that share an `appName` and AppOwner open the same database and
+   * must use the same schema. Evolu applies the schema of the first instance
+   * and later instances join it.
+   *
+   * A different app name lets you create a separate local replica for the same
+   * AppOwner—for example, to test a different SQLite implementation or index
+   * configuration, or rebuild a replica for debugging while preserving the
+   * existing database.
+   *
+   * Evolu supports running these databases concurrently. Their local separation
+   * does not isolate synchronization: replicas synchronizing the same owners
+   * through the same relay can still exchange changes. Changing `appName`
+   * neither migrates existing local data nor isolates incompatible schemas.
    *
    * ### Example
    *
@@ -132,6 +154,73 @@ export interface EvoluConfig {
    */
   readonly appOwner: AppOwner;
 
+  /**
+   * Keep the database in memory instead of persisting it on this device.
+   *
+   * This option controls device persistence independently of synchronization.
+   * When synchronization is enabled, data can still be synchronized and
+   * persisted remotely.
+   *
+   * Useful for testing or temporary sessions. Data that exists only in this
+   * database is lost when the database closes.
+   *
+   * The default value is: `false`.
+   */
+  readonly memoryOnly?: boolean;
+
+  /**
+   * Use the `indexes` option to define SQLite indexes.
+   *
+   * Table and column names are not typed because Kysely doesn't support it.
+   *
+   * https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346
+   *
+   * ### Example
+   *
+   * ```ts
+   * import {
+   *   createEvolu,
+   *   id,
+   *   testAppName,
+   *   testAppOwner,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   todo: { id: id("Todo") },
+   *   todoCategory: { id: id("TodoCategory") },
+   * };
+   *
+   * const _createTodoEvolu = createEvolu(Schema, {
+   *   appName: testAppName,
+   *   appOwner: testAppOwner,
+   *   transports: [],
+   *   indexes: (create) => [
+   *     create("todoCreatedAt").on("todo").column("createdAt"),
+   *     create("todoCategoryCreatedAt")
+   *       .on("todoCategory")
+   *       .column("createdAt"),
+   *   ],
+   * });
+   * ```
+   */
+  readonly indexes?: IndexesConfig;
+
+  /**
+   * Called when this instance's local database is deleted.
+   *
+   * Apps can use this to update UI immediately because the corresponding
+   * {@link Evolu} instance becomes unusable after local database deletion.
+   */
+  readonly onDatabaseDeleted?: () => void;
+
+  /**
+   * Called when local data for an {@link Owner} is deleted.
+   *
+   * Apps can use this to update UI immediately because that owner stops being
+   * used across tabs and instances.
+   */
+  readonly onOwnerDeleted?: (owner: Owner) => void;
+
   /**
    * Transport configuration for sync and backup.
    *
@@ -169,18 +258,11 @@ export interface EvoluConfig {
    * ```ts
    * import {
    *   assertEqual,
-   *   createAppOwner,
    *   createOwnerWebSocketTransport,
-   *   createOwnerSecret,
-   *   createRandomBytes,
+   *   testAppOwner,
    *   type OwnerTransport,
    * } from "@evolu/common";
    *
-   * // Create once, persist the mnemonic securely, and restore it on later runs.
-   * const appOwner = createAppOwner(
-   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
-   * );
-   *
    * // Use one relay.
    * const _singleRelay = [
    *   { type: "WebSocket", url: "wss://relay1.example.com" },
@@ -201,91 +283,17 @@ export interface EvoluConfig {
    * const authenticatedRelay = [
    *   createOwnerWebSocketTransport({
    *     url: "wss://relay.example.com",
-   *     ownerId: appOwner.id,
+   *     ownerId: testAppOwner.id,
    *   }),
    * ];
    *
    * assertEqual(
    *   authenticatedRelay[0]?.url,
-   *   `wss://relay.example.com?ownerId=${appOwner.id}`,
+   *   `wss://relay.example.com?ownerId=${testAppOwner.id}`,
    * );
    * ```
    */
   readonly transports?: ReadonlyArray<OwnerTransport>;
-
-  /**
-   * Keep local data only in memory instead of persisting it on this device.
-   * Useful for testing, temporary data, or sensitive data that should not be
-   * recoverable from local storage after the process ends.
-   *
-   * Local data stored in memory is completely destroyed when the process ends.
-   * Sync can still persist data remotely when transports are enabled.
-   *
-   * The default value is: `false`.
-   */
-  readonly memoryOnly?: boolean;
-
-  /**
-   * Use the `indexes` option to define SQLite indexes.
-   *
-   * Table and column names are not typed because Kysely doesn't support it.
-   *
-   * https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346
-   *
-   * ### Example
-   *
-   * ```ts
-   * import {
-   *   AppName,
-   *   assertTrue,
-   *   createAppOwner,
-   *   createEvolu,
-   *   createOwnerSecret,
-   *   createRandomBytes,
-   *   id,
-   * } from "@evolu/common";
-   *
-   * const Schema = {
-   *   todo: { id: id("Todo") },
-   *   todoCategory: { id: id("TodoCategory") },
-   * };
-   * // Create once, persist the mnemonic securely, and restore it on later runs.
-   * const appOwner = createAppOwner(
-   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
-   * );
-   *
-   * const createTodoEvolu = createEvolu(Schema, {
-   *   appName: AppName.orThrow("IndexedTodos"),
-   *   appOwner,
-   *   transports: [],
-   *   indexes: (create) => [
-   *     create("todoCreatedAt").on("todo").column("createdAt"),
-   *     create("todoCategoryCreatedAt")
-   *       .on("todoCategory")
-   *       .column("createdAt"),
-   *   ],
-   * });
-   *
-   * assertTrue(typeof createTodoEvolu === "function");
-   * ```
-   */
-  readonly indexes?: IndexesConfig;
-
-  /**
-   * Called when this instance's local database is deleted.
-   *
-   * Apps can use this to update UI immediately because the corresponding
-   * {@link Evolu} instance becomes unusable after local database deletion.
-   */
-  readonly onDatabaseDeleted?: () => void;
-
-  /**
-   * Called when local data for an {@link Owner} is deleted.
-   *
-   * Apps can use this to update UI immediately because that owner stops being
-   * used across tabs and instances.
-   */
-  readonly onOwnerDeleted?: (owner: Owner) => void;
 }
 
 /**
@@ -297,6 +305,8 @@ export interface EvoluConfig {
  *
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
  * `_`) and must be between 1 and 41 characters.
+ *
+ * @group Configuration
  */
 export const AppName = /*#__PURE__*/ brand(
   "AppName",
@@ -309,16 +319,35 @@ export const AppName = /*#__PURE__*/ brand(
     `The value ${JSON.stringify(error.value)} is not between 1 and 41 characters.`,
 );
 export type AppName = typeof AppName.Output;
+/**
+ * Error produced when a value is not a valid {@link AppName}.
+ *
+ * @group Configuration
+ */
 export interface AppNameError extends TypeError<"AppName"> {
   readonly value: UrlSafeString;
 }
 
+/**
+ * Stable valid {@link AppName} for tests and examples.
+ *
+ * @group Testing
+ */
 export const testAppName = /*#__PURE__*/ AppName.orThrow("AppName");
 
 /**
- * Local-first SQL database with typed queries, mutations, and sync.
+ * A local-first SQL database.
+ *
+ * Stores application data in SQLite on the device, so reads and writes work
+ * offline. Provides typed queries, mutations, and reactive subscriptions, with
+ * synchronization between devices. Persistent SQLite is encrypted with the
+ * {@link AppOwner} key, and synchronized data is end-to-end encrypted.
  *
- * TODO: Better docs.
+ * Tables whose names start with `_` stay local, even when the instance
+ * synchronizes other data. Use them for device-local data such as application
+ * settings or an app-owner registry.
+ *
+ * @group Core
  */
 export interface Evolu<
   S extends EvoluSchema = EvoluSchema,
@@ -340,32 +369,29 @@ export interface Evolu<
    * every row has a globally unique, conflict-free identifier without
    * coordination.
    *
-   * Pass `onComplete` when follow-up work must wait until the mutation and its
-   * query patches have been applied.
+   * Pass `onComplete` when follow-up work must wait until the mutation is
+   * stored and subscribed queries reflect it. It never runs when the database
+   * is unavailable; see {@link Evolu.loadQuery}. A stored change is not always
+   * visible; see {@link MutationOptions.onComplete}.
    *
    * ### Example
    *
    * ```ts
    * import {
    *   assertType,
-   *   id,
+   *   type TestEvoluSchema,
    *   NonEmptyTrimmedString100,
    *   type Evolu,
+   *   type TestTodoId,
    * } from "@evolu/common";
    *
-   * const TodoId = id("Todo");
-   * type TodoId = typeof TodoId.Output;
-   * const Schema = {
-   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
-   * };
-   *
-   * const insertTodo = (evolu: Evolu<typeof Schema>) =>
+   * const insertTodo = (evolu: Evolu<TestEvoluSchema>) =>
    *   evolu.insert("todo", {
    *     title: NonEmptyTrimmedString100.orThrow("Learn Evolu"),
    *   }).id;
    *
    * const insertTodoAndNotify = (
-   *   evolu: Evolu<typeof Schema>,
+   *   evolu: Evolu<TestEvoluSchema>,
    *   onComplete: () => void,
    * ) =>
    *   evolu.insert(
@@ -379,7 +405,7 @@ export interface Evolu<
    *     ReturnType<typeof insertTodo>,
    *     ReturnType<typeof insertTodoAndNotify>,
    *   ],
-   *   [TodoId, TodoId]
+   *   [TestTodoId, TestTodoId]
    * >();
    * ```
    *
@@ -397,30 +423,30 @@ export interface Evolu<
    * ```ts
    * import {
    *   assertType,
-   *   id,
+   *   type TestEvoluSchema,
    *   NonEmptyTrimmedString100,
    *   sqliteTrue,
    *   type Evolu,
+   *   type TestTodoId,
    * } from "@evolu/common";
    *
-   * const TodoId = id("Todo");
-   * type TodoId = typeof TodoId.Output;
-   * const Schema = {
-   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
-   * };
-   *
-   * const renameTodo = (evolu: Evolu<typeof Schema>, todoId: TodoId) =>
+   * const renameTodo = (
+   *   evolu: Evolu<TestEvoluSchema>,
+   *   todoId: TestTodoId,
+   * ) =>
    *   evolu.update("todo", {
    *     id: todoId,
    *     title: NonEmptyTrimmedString100.orThrow("Updated title"),
    *   }).id;
    *
-   * const softDeleteTodo = (evolu: Evolu<typeof Schema>, todoId: TodoId) =>
-   *   evolu.update("todo", { id: todoId, isDeleted: sqliteTrue }).id;
+   * const softDeleteTodo = (
+   *   evolu: Evolu<TestEvoluSchema>,
+   *   todoId: TestTodoId,
+   * ) => evolu.update("todo", { id: todoId, isDeleted: sqliteTrue }).id;
    *
    * assertType<
    *   [ReturnType<typeof renameTodo>, ReturnType<typeof softDeleteTodo>],
-   *   [TodoId, TodoId]
+   *   [TestTodoId, TestTodoId]
    * >();
    * ```
    *
@@ -446,24 +472,20 @@ export interface Evolu<
    * import {
    *   assertType,
    *   createIdFromString,
-   *   id,
+   *   type TestEvoluSchema,
    *   NonEmptyTrimmedString100,
    *   type Evolu,
+   *   TestTodoId,
    * } from "@evolu/common";
    *
-   * const TodoId = id("Todo");
-   * type TodoId = typeof TodoId.Output;
-   * const Schema = {
-   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
-   * };
-   * const stableId = TodoId.orThrow(createIdFromString("my-todo-1"));
-   * const upsertTodo = (evolu: Evolu<typeof Schema>) =>
+   * const stableId = TestTodoId.orThrow(createIdFromString("my-todo-1"));
+   * const upsertTodo = (evolu: Evolu<TestEvoluSchema>) =>
    *   evolu.upsert("todo", {
    *     id: stableId,
    *     title: NonEmptyTrimmedString100.orThrow("Learn Evolu"),
    *   }).id;
    *
-   * assertType<ReturnType<typeof upsertTodo>, TodoId>();
+   * assertType<ReturnType<typeof upsertTodo>, TestTodoId>();
    * ```
    *
    * @see {@link Mutation}
@@ -473,14 +495,19 @@ export interface Evolu<
   /**
    * Load {@link Query} and return a promise with {@link QueryRows}.
    *
-   * The returned promise always resolves successfully because there is no
-   * reason why loading should fail. All data are local, and the query is
-   * typed.
+   * The returned promise always resolves successfully because all data are
+   * local and the query is typed. If the database refuses startup, unanswered
+   * loads stay pending until disposal resolves them with empty rows. Observe
+   * {@link EvoluErrorDep.evoluError} to display the refusal independently of
+   * query loading.
    *
    * Loading is batched. Returned promises are cached while pending and can be
-   * reused after fulfillment until mutation-driven invalidation, which prevents
-   * redundant database queries and supports React Suspense (stable references
-   * while pending).
+   * reused after fulfillment, which prevents redundant database queries and
+   * supports React Suspense (stable references while pending). A mutation or
+   * incoming sync invalidates the cache of an unsubscribed query, so its next
+   * load reads again. A subscribed query keeps its cached rows and the
+   * subscription refreshes them, so a load can return rows that a pending
+   * refresh is about to replace.
    *
    * To subscribe a query for automatic updates, use
    * {@link Evolu.subscribeQuery}.
@@ -491,20 +518,17 @@ export interface Evolu<
    * import {
    *   assertType,
    *   createQueryBuilder,
-   *   id,
-   *   NonEmptyTrimmedString100,
+   *   testEvoluSchema,
+   *   type TestEvoluSchema,
    *   type Evolu,
    *   type QueryRows,
    * } from "@evolu/common";
    *
-   * const Schema = {
-   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
-   * };
-   * const createQuery = createQueryBuilder(Schema);
+   * const createQuery = createQueryBuilder(testEvoluSchema);
    * const allTodos = createQuery((db) =>
    *   db.selectFrom("todo").selectAll(),
    * );
-   * const loadTodos = async (evolu: Evolu<typeof Schema>) => {
+   * const loadTodos = async (evolu: Evolu<TestEvoluSchema>) => {
    *   const rows = await evolu.loadQuery(allTodos);
    *   return rows;
    * };
@@ -529,31 +553,22 @@ export interface Evolu<
    * ```ts
    * import {
    *   assertType,
-   *   createIdFromString,
    *   createQueryBuilder,
-   *   id,
-   *   NonEmptyTrimmedString100,
+   *   testEvoluSchema,
+   *   type TestEvoluSchema,
+   *   testTodoId,
    *   type Evolu,
    *   type QueryRows,
    * } from "@evolu/common";
    *
-   * const TodoId = id("Todo");
-   * type TodoId = typeof TodoId.Output;
-   * const Schema = {
-   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
-   * };
-   * const createQuery = createQueryBuilder(Schema);
+   * const createQuery = createQueryBuilder(testEvoluSchema);
    * const allTodos = createQuery((db) =>
    *   db.selectFrom("todo").select(["id", "title"]),
    * );
-   * const todoById = (todoId: TodoId) =>
-   *   createQuery((db) =>
-   *     db.selectFrom("todo").select("title").where("id", "=", todoId),
-   *   );
-   * const firstTodo = todoById(
-   *   TodoId.orThrow(createIdFromString("first-todo")),
+   * const firstTodo = createQuery((db) =>
+   *   db.selectFrom("todo").select("title").where("id", "=", testTodoId),
    * );
-   * const loadTodoQueries = (evolu: Evolu<typeof Schema>) =>
+   * const loadTodoQueries = (evolu: Evolu<TestEvoluSchema>) =>
    *   evolu.loadQueries([allTodos, firstTodo]);
    *
    * assertType<
@@ -572,28 +587,28 @@ export interface Evolu<
   /**
    * Subscribe to {@link Query} {@link QueryRows} changes.
    *
+   * Cached rows invalidated before subscription are refreshed. Subscribing
+   * alone does not load a query that has no cached rows.
+   *
    * ### Example
    *
    * ```ts
    * import {
    *   assertType,
    *   createQueryBuilder,
-   *   id,
-   *   NonEmptyTrimmedString100,
+   *   testEvoluSchema,
+   *   type TestEvoluSchema,
    *   type Evolu,
    *   type QueryRows,
    *   type Unsubscribe,
    * } from "@evolu/common";
    *
-   * const Schema = {
-   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
-   * };
-   * const createQuery = createQueryBuilder(Schema);
+   * const createQuery = createQueryBuilder(testEvoluSchema);
    * const allTodos = createQuery((db) =>
    *   db.selectFrom("todo").select("title"),
    * );
    * const subscribeToTodos = (
-   *   evolu: Evolu<typeof Schema>,
+   *   evolu: Evolu<TestEvoluSchema>,
    *   onRows: (rows: QueryRows<typeof allTodos.Row>) => void,
    * ) =>
    *   evolu.subscribeQuery(allTodos)(() => {
@@ -616,20 +631,17 @@ export interface Evolu<
    * import {
    *   assertType,
    *   createQueryBuilder,
-   *   id,
-   *   NonEmptyTrimmedString100,
+   *   testEvoluSchema,
+   *   type TestEvoluSchema,
    *   type Evolu,
    *   type QueryRows,
    * } from "@evolu/common";
    *
-   * const Schema = {
-   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
-   * };
-   * const createQuery = createQueryBuilder(Schema);
+   * const createQuery = createQueryBuilder(testEvoluSchema);
    * const allTodos = createQuery((db) =>
    *   db.selectFrom("todo").select("title"),
    * );
-   * const getTodos = (evolu: Evolu<typeof Schema>) =>
+   * const getTodos = (evolu: Evolu<TestEvoluSchema>) =>
    *   evolu.getQueryRows(allTodos);
    *
    * assertType<
@@ -647,7 +659,8 @@ export interface Evolu<
    * of starting parallel exports.
    *
    * The pending promise rejects if this {@link Evolu} instance is disposed
-   * before export completion.
+   * before export completion. If the database refuses startup, export stays
+   * pending until disposal; see {@link Evolu.loadQuery}.
    */
   readonly exportDatabase: () => Promise<Uint8Array<ArrayBuffer>>;
 
@@ -703,21 +716,15 @@ export interface Evolu<
    * ```ts
    * import {
    *   assertEqual,
-   *   createAppOwner,
    *   createOwnerWebSocketTransport,
-   *   createOwnerSecret,
-   *   createRandomBytes,
    *   deriveShardOwner,
+   *   testAppOwner,
    *   type Evolu,
    *   type ReadonlyOwner,
    *   type UnuseOwner,
    * } from "@evolu/common";
    *
-   * // Create once, persist the mnemonic securely, and restore it on later runs.
-   * const appOwner = createAppOwner(
-   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
-   * );
-   * const shardOwner = deriveShardOwner(appOwner, ["todos", 1]);
+   * const shardOwner = deriveShardOwner(testAppOwner, ["todos", 1]);
    * const shardTransport = createOwnerWebSocketTransport({
    *   url: "wss://relay.example.com",
    *   ownerId: shardOwner.id,
@@ -753,17 +760,90 @@ export interface Evolu<
     owner: ReadonlyOwner | Owner,
     transports?: NonEmptyReadonlyArray<OwnerTransport>,
   ) => UnuseOwner;
+
+  /**
+   * Requests a new synchronization round for an active {@link OwnerId}.
+   *
+   * Reconciles locally stored changes, including writes previously rejected
+   * with {@link ProtocolQuotaError}, through the owner's active transports. Call
+   * this after the relay provider confirms additional quota is available.
+   * Existing connections and {@link Evolu.useOwner} registrations are retained,
+   * including registrations shared by multiple instances or tabs.
+   *
+   * The owner must have an active writable registration in this database.
+   * Unregistered or read-only owners are ignored. Requests are skipped while
+   * all of the owner's transports are closed; they synchronize when they
+   * reopen. Disposal drops locally buffered requests. Calling a disposed
+   * instance throws, like other Evolu operations.
+   *
+   * Returns immediately, without waiting for synchronization to complete.
+   * Errors are reported through {@link EvoluErrorDep.evoluError}.
+   *
+   * ### Example
+   *
+   * ```ts
+   * import { assertType, type Evolu, type OwnerId } from "@evolu/common";
+   *
+   * // Call after successfully increasing the affected owner's relay quota.
+   * const onQuotaIncreased = (evolu: Evolu, ownerId: OwnerId) => {
+   *   evolu.requestSync(ownerId);
+   * };
+   *
+   * assertType<
+   *   typeof onQuotaIncreased,
+   *   (evolu: Evolu, ownerId: OwnerId) => void
+   * >();
+   * ```
+   */
+  readonly requestSync: (ownerId: OwnerId) => void;
 }
 
-/** Function returned by {@link Evolu.useOwner} to stop using an Owner for sync. */
+/**
+ * Function returned by {@link Evolu.useOwner} to stop using an Owner for sync.
+ *
+ * @group Core
+ */
 export type UnuseOwner = () => void;
 
+/**
+ * Represents errors that can occur in {@link Evolu}.
+ *
+ * @group Core
+ */
+export type EvoluError =
+  | DecryptWithXChaCha20Poly1305Error
+  | OtherBuildRunningError
+  | ProtocolError
+  | StorageQuotaError
+  | UnknownError
+  | UnsupportedDbVersionError;
+
+/**
+ * Dependency wrapper for the shared {@link EvoluError} store.
+ *
+ * @group Construction
+ */
 export interface EvoluErrorDep {
   /**
    * {@link ReadonlyStore} of {@link EvoluError} shared by all {@link Evolu}
    * instances created from the same {@link createEvoluDeps} result.
    *
+   * Starts at `null` and otherwise holds the latest reported error until the
+   * first {@link UnsupportedDbVersionError}. That refusal remains for the
+   * lifetime of these dependencies, even if a tenant is disposed and recreated.
+   * Later errors are still logged but do not replace it or notify this store's
+   * subscribers. Fresh dependencies start with a fresh error store. An
+   * {@link OtherBuildRunningError} reports a wait, so the store returns to
+   * `null` when the wait ends, unless another error replaced it.
+   *
    * Subscribe once to show user-facing error messages across all instances.
+   * While a refused database's tenant remains alive, the SharedWorker sends the
+   * refusal to each tab once, including tabs that connect later, and starts no
+   * replacement database workers. After all instances release that tenant and
+   * it is disposed when idle, creating another instance retries startup and may
+   * send the refusal again. On the web, a refused tab first reloads once
+   * instead; see {@link UnsupportedDbVersionError}. Show that blocking message
+   * outside any query-loading boundary, so pending queries do not hide it.
    *
    * ### Example
    *
@@ -771,60 +851,113 @@ export interface EvoluErrorDep {
    * import {
    *   assertEqual,
    *   createStore,
-   *   Millis,
    *   type EvoluError,
    * } from "@evolu/common";
    * import type { EvoluErrorDep } from "@evolu/common/local-first";
    *
+   * // The message for the current error, or null for none.
+   * const errorMessage = (error: EvoluError | null): string | null => {
+   *   if (!error) return null;
+   *   // oxlint-disable-next-line typescript/switch-exhaustiveness-check -- The default handles every other EvoluError.
+   *   switch (error.type) {
+   *     case "UnsupportedDbVersionError":
+   *       return "Your data requires a newer version of this app. Please update it.";
+   *     case "OtherBuildRunningError":
+   *       return "This app is open in another tab with a different version. Close that tab to continue.";
+   *     default:
+   *       return "Something went wrong. Please try again.";
+   *   }
+   * };
+   *
    * // Stand-in for run.deps.evoluError from createEvoluDeps.
    * using evoluError = createStore<EvoluError | null>(null);
    * const deps = { evoluError } satisfies EvoluErrorDep;
-   * let displayedMessage = "";
-   * const showMessage = (message: string) => {
-   *   displayedMessage = message;
-   * };
+   * // What the app showed over time; null hides the message.
+   * const shown: Array<string | null> = [];
    *
    * deps.evoluError.subscribe(() => {
-   *   const error = deps.evoluError.get();
-   *   if (!error) return;
-   *
-   *   // oxlint-disable-next-line typescript/switch-exhaustiveness-check -- The default intentionally handles every other EvoluError.
-   *   switch (error.type) {
-   *     case "TimestampDriftError":
-   *       // Show guidance specific to the detected error.
-   *       showMessage(
-   *         "Your system clock appears incorrect. Please fix it.",
-   *       );
-   *       break;
-   *     default:
-   *       // Show a generic user message for other operational errors.
-   *       showMessage("Something went wrong. Please try again.");
-   *   }
+   *   shown.push(errorMessage(deps.evoluError.get()));
    * });
    *
-   * deps.evoluError.set({
-   *   type: "TimestampDriftError",
-   *   next: Millis.orThrow(360000),
-   *   now: Millis.orThrow(0),
-   * });
-   * assertEqual(
-   *   displayedMessage,
-   *   "Your system clock appears incorrect. Please fix it.",
-   * );
+   * // Another version keeps this tab waiting, then the wait ends.
+   * deps.evoluError.set({ type: "OtherBuildRunningError" });
+   * deps.evoluError.set(null);
+   *
+   * assertEqual(shown, [
+   *   "This app is open in another tab with a different version. Close that tab to continue.",
+   *   null,
+   * ]);
    * ```
    */
   readonly evoluError: ReadonlyStore<EvoluError | null>;
 }
 
+/**
+ * Dependency wrapper for the shared {@link SyncState} store.
+ *
+ * @group Construction
+ */
+export interface SyncStateDep {
+  /**
+   * {@link ReadonlyStore} of the latest {@link SyncState} shared by all
+   * {@link Evolu} instances, or null before the shared worker sends its first
+   * snapshot. Derive what to show from it, such as one indicator per relay, or
+   * use {@link syncStateToOwnerSyncStates} for one state per owner.
+   *
+   * ### Example
+   *
+   * ```ts
+   * import {
+   *   assertEqual,
+   *   createId,
+   *   createStore,
+   *   testCreateDeps,
+   * } from "@evolu/common";
+   * import type {
+   *   SyncState,
+   *   SyncStateDep,
+   * } from "@evolu/common/local-first";
+   *
+   * const openRelayLabels = (deps: SyncStateDep): ReadonlyArray<string> =>
+   *   (deps.syncState.get()?.transports ?? [])
+   *     .filter(({ readyState }) => readyState === "open")
+   *     .map(({ label }) => label);
+   *
+   * using syncState = createStore<SyncState | null>(null);
+   * assertEqual(openRelayLabels({ syncState }), []);
+   *
+   * const deps = testCreateDeps();
+   * syncState.set({
+   *   transports: [
+   *     {
+   *       id: createId<"SyncTransport">(deps),
+   *       label: "wss://relay.example",
+   *       readyState: "open",
+   *       openedAt: null,
+   *       closedAt: null,
+   *       error: null,
+   *     },
+   *   ],
+   *   tenants: [],
+   * });
+   * assertEqual(openRelayLabels({ syncState }), ["wss://relay.example"]);
+   * ```
+   */
+  readonly syncState: ReadonlyStore<SyncState | null>;
+}
+
 /**
  * Shared platform dependencies for creating {@link Evolu} instances.
  *
  * Includes platform adapters, the shared {@link EvoluErrorDep.evoluError} store,
  * and disposal for owned resources.
+ *
+ * @group Construction
  */
 export type EvoluDeps = EvoluPlatformDeps &
   ConsoleDep &
   EvoluErrorDep &
+  SyncStateDep &
   Disposable;
 
 /**
@@ -832,6 +965,8 @@ export type EvoluDeps = EvoluPlatformDeps &
  *
  * Provides worker and channel adapters plus optional platform integrations for
  * logging and synchronous UI flush.
+ *
+ * @group Construction
  */
 export type EvoluPlatformDeps = CreateDbWorkerDep &
   CreateBroadcastChannelDep &
@@ -848,36 +983,50 @@ export type EvoluPlatformDeps = CreateDbWorkerDep &
  *
  * Call this once per platform and reuse the returned deps when creating
  * multiple Evolu instances. The returned deps object owns long-lived resources
- * such as worker channels and the shared {@link EvoluErrorDep.evoluError}
- * store.
+ * such as worker channels and the shared {@link EvoluErrorDep.evoluError} and
+ * {@link SyncStateDep.syncState} stores.
  *
  * Dispose it only during app shutdown.
+ *
+ * @group Construction
  */
 export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
   const { createBroadcastChannel, sharedWorker } = deps;
   const console = deps.console ?? createConsole();
+  // Opened when the worker connects.
+  let syncStateBroadcastChannel: BroadcastChannel<SyncState> | null = null;
+  let tabLeaderElection: Disposable | null = null;
 
   using disposer = new DisposableStack();
   disposer.use(sharedWorker);
   const evoluError = disposer.use(createStore<EvoluError | null>(null));
+  const syncState = disposer.use(createStore<SyncState | null>(null));
+  disposer.defer(() => {
+    syncStateBroadcastChannel?.[Symbol.dispose]();
+  });
 
   const consoleEntryOrErrorBroadcastChannel = disposer.use(
     createBroadcastChannel<ConsoleEntryOrError>(
       consoleEntryOrErrorBroadcastChannelName,
     ),
   );
+  const setEvoluError = (error: EvoluError): void => {
+    if (evoluError.get()?.type === "UnsupportedDbVersionError") return;
+    evoluError.set(error);
+  };
+
   consoleEntryOrErrorBroadcastChannel.onMessage = (message) => {
     switch (message.type) {
       case "ConsoleEntry":
         console.write(message.entry);
         // Fallback channel for unexpected errors without EvoluError typing.
         if (message.entry.method === "error") {
-          evoluError.set(createUnknownError(message.entry.args));
+          setEvoluError(createUnknownError(message.entry.args));
         }
         break;
 
       case "Error":
-        evoluError.set(message.error);
+        setEvoluError(message.error);
         // Keep typed errors visible in logs as operational failures.
         console.error(message.error);
         break;
@@ -888,23 +1037,69 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
   };
 
   sharedWorker.port.onMessage = (message) => {
-    deps.createDbWorker().postMessage(message, [message.port]);
+    switch (message.type) {
+      case "DbWorkerInit":
+        deps.createDbWorker().postMessage(message, [message.port]);
+        break;
+
+      case "Error":
+        // Sent to this tab only: its database refused startup, or its worker
+        // still waits for another build.
+        setEvoluError(message.error);
+        console.error(message.error);
+        break;
+
+      case "Waiting":
+      case "StorageUnavailable":
+        // Platform adapters act on these; see Builds and Storage in the Shared
+        // module.
+        break;
+
+      case "Connected": {
+        assert(!syncStateBroadcastChannel, "The shared worker connects once.");
+        // The wait the error reported is over.
+        if (evoluError.get()?.type === "OtherBuildRunningError") {
+          evoluError.set(null);
+        }
+        // The worker is the channel's only sender, and one sender's messages
+        // arrive in order, so the last one is current.
+        syncStateBroadcastChannel = createBroadcastChannel<SyncState>(
+          message.syncStateChannelName,
+        );
+        syncStateBroadcastChannel.onMessage = (state) => {
+          syncState.set(state);
+        };
+        // Asking only after listening misses no snapshot.
+        sharedWorker.port.postMessage({ type: "RequestSyncState" });
+        // Only this worker's tabs compete, so a tab of another worker never
+        // hosts its DbWorkers.
+        tabLeaderElection = acquireLeaderLockCallback(deps)(
+          `tab-${message.workerId}`,
+          () => {
+            sharedWorker.port.postMessage({
+              type: "AnnounceTabLeader",
+              consoleLevel: console.getLevel(),
+            });
+          },
+        );
+        break;
+      }
+
+      default:
+        exhaustiveCheck(message);
+    }
   };
 
-  disposer.use(
-    acquireLeaderLockCallback(deps)("tab", () => {
-      sharedWorker.port.postMessage({
-        type: "AnnounceTabLeader",
-        consoleLevel: console.getLevel(),
-      });
-    }),
-  );
+  disposer.defer(() => {
+    tabLeaderElection?.[Symbol.dispose]();
+  });
 
   return disposable<EvoluDeps>(
     {
       ...deps,
       console,
       evoluError,
+      syncState,
     },
     disposer,
   );
@@ -913,6 +1108,8 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
 /**
  * Creates an {@link Evolu} instance from {@link EvoluSchema} and
  * {@link EvoluConfig}.
+ *
+ * @group Construction
  */
 export const createEvolu =
   <S extends EvoluSchema>(
@@ -1091,10 +1288,7 @@ export const createEvolu =
           case "RefreshQueries": {
             releaseUnsubscribedLoadingPromises();
 
-            const queries = new Set<Query>([
-              ...loadingPromisesByQuery.keys(),
-              ...subscribedQueriesRefCount.keys(),
-            ]);
+            const queries = new Set<Query>(subscribedQueriesRefCount.keys());
 
             if (isNonEmptySet(queries)) postMessage({ type: "Query", queries });
             break;
@@ -1311,6 +1505,27 @@ export const createEvolu =
               listener();
             });
 
+            // Invalidation can happen after loading but before a framework
+            // subscribes. Register first so subsequent invalidations also
+            // refresh this query.
+            const loadingPromise = loadingPromisesByQuery.get(query);
+            if (loadingPromise?.releaseOnResolve) {
+              // Retain the pending promise for its awaiters, but queue a read
+              // after the mutation or sync that invalidated its result.
+              loadingPromise.releaseOnResolve = false;
+              queryBatch.push(query);
+            } else if (!loadingPromise) {
+              const rows = rowsByQueryMapStore.get().get(query);
+              if (rows) {
+                // Queue a read, but keep cached rows available to React use()
+                // so a render before the worker responds does not suspend.
+                void loadQuery(query);
+                const entry = loadingPromisesByQuery.get(query);
+                assertNotUndefined(entry);
+                fulfillLoadingPromise(entry, rows);
+              }
+            }
+
             return () => {
               assert(
                 isSubscribed,
@@ -1347,6 +1562,13 @@ export const createEvolu =
           },
 
           useOwner,
+          requestSync: (ownerId) => {
+            // Do not let the forced mutation flush overtake pending owner actions.
+            useOwnerBatch.flushNow();
+            // Queue preceding mutations before the reconciliation request.
+            mutateBatch.flushNow();
+            useOwnerBatch.push({ action: "sync", ownerId });
+          },
         },
         disposer,
       ),