@evolu/common 8.10.0 → 8.12.0

package/src/local-first/Evolu.ts

@@ -15,9 +15,12 @@ import {
   assertNonEmptyReadonlyArray,
   assertNotUndefined,
 } from "../Assert.ts";
+import { createBuffer } from "../Bytes.ts";
 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 {
@@ -26,11 +29,20 @@ import {
   type LockManagerDep,
 } from "../LockManager.ts";
 import { createMicrotaskBatch } from "../Microtask.ts";
+import {
+  createMutableRecord,
+  objectToEntries,
+  type ReadonlyRecord,
+} from "../Object.ts";
 import type { FlushSyncDep, ReloadAppDep } from "../Platform.ts";
 import { createRefCountByKey } from "../RefCount.ts";
 import { err, ok } from "../Result.ts";
 import { isNonEmptySet } from "../Set.ts";
-import { SqliteBoolean, sqliteBooleanToBoolean } from "../Sqlite.ts";
+import {
+  SqliteBoolean,
+  sqliteBooleanToBoolean,
+  type SqliteValue,
+} from "../Sqlite.ts";
 import type { Listener, ReadonlyStore, Unsubscribe } from "../Store.ts";
 import { createStore } from "../Store.ts";
 import type { Task } from "../Task.ts";
@@ -39,17 +51,18 @@ import {
   createId,
   createIdFromString,
   type ExtractTyped,
-  type Id,
+  Id,
   Name,
+  PositiveInt,
   type TypeError,
   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 +72,12 @@ import type {
   SyncOwner,
 } from "./Owner.ts";
 import { createOwnerWebSocketTransport } from "./Owner.ts";
+import {
+  encodeDbChange,
+  type ProtocolError,
+  type ProtocolQuotaError,
+  type ProtocolVersionError,
+} from "./Protocol.ts";
 import type {
   Queries,
   QueriesToQueryRowsPromises,
@@ -73,30 +92,50 @@ import type {
   IndexesConfig,
   Mutation,
   MutationChange,
+  MutationOptions,
+  MutationValues,
   ValidateSchema,
 } from "./Schema.ts";
-import { evoluSchemaToSqliteSchema } from "./Schema.ts";
+import { evoluSchemaToSqliteSchema, isLocalOnlyTable } from "./Schema.ts";
 import type {
   ConsoleEntryOrError,
   EvoluInput,
   EvoluOutput,
+  OtherBuildRunningError,
   SharedWorkerDep,
+  SyncState,
+  syncStateToOwnerSyncStates,
 } from "./Shared.ts";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
-import { DbChange } from "./Storage.ts";
-import type { Timestamp } from "./Timestamp.ts";
+import { DbChange, type StorageQuotaError } from "./Storage.ts";
+import { createTimestamp, 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.
+   *
+   * 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.
    *
-   * 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.
+   * 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 +171,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 +275,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 +300,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 +322,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 +336,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.
+ *
+ * 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.
  *
- * TODO: Better docs.
+ * @group Core
  */
 export interface Evolu<
   S extends EvoluSchema = EvoluSchema,
@@ -340,32 +386,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 +422,7 @@ export interface Evolu<
    *     ReturnType<typeof insertTodo>,
    *     ReturnType<typeof insertTodoAndNotify>,
    *   ],
-   *   [TodoId, TodoId]
+   *   [TestTodoId, TestTodoId]
    * >();
    * ```
    *
@@ -397,30 +440,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,41 +489,77 @@ 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}
    */
   readonly upsert: Mutation<S, "upsert">;
 
+  /**
+   * Returns the size of a mutation of `table` with `values`, measured as
+   * {@link maxMutationSize} describes.
+   *
+   * Use it to check values that column Types do not bound before mutating, or
+   * to show how much of the limit a mutation uses. It accepts any of the
+   * table's columns, so the values of an insert, update, or upsert fit, and it
+   * ignores `id` and `isDeleted`, which are not columns. Mutations of
+   * local-only tables are measured too, although they are exempt from the
+   * limit.
+   *
+   * ### Example
+   *
+   * ```ts
+   * import {
+   *   assertType,
+   *   type Evolu,
+   *   maxMutationSize,
+   *   type NonEmptyTrimmedString100,
+   *   type TestEvoluSchema,
+   * } from "@evolu/common";
+   *
+   * const fitsTodo = (
+   *   evolu: Evolu<TestEvoluSchema>,
+   *   title: NonEmptyTrimmedString100,
+   * ) => evolu.getMutationSize("todo", { title }) <= maxMutationSize;
+   *
+   * assertType<ReturnType<typeof fitsTodo>, boolean>();
+   * ```
+   */
+  readonly getMutationSize: <TableName extends keyof S>(
+    table: TableName,
+    values: Partial<MutationValues<S[TableName], "update">>,
+  ) => PositiveInt;
+
   /**
    * 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 +570,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 +605,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 +639,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 +683,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 +711,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 +768,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 +812,168 @@ 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}.
+ *
+ * Apps show them from {@link EvoluErrorDep.evoluError}.
+ *
+ * An error that leaves the app unusable deserves a modal dialog, which moves
+ * focus into itself and restores it when closed. Any other error is a status
+ * message: show it in a region with `role="alert"`, which screen readers
+ * announce without moving focus, so the user keeps working and a background tab
+ * shows it when the user returns. Avoid `alert()`, which blocks the page, once
+ * in every open tab.
+ *
+ * - {@link UnsupportedDbVersionError} blocks the app: the local data needs a newer
+ *   version of it. Ask the user to update the app or close all its tabs.
+ * - {@link OtherBuildRunningError} blocks the app while it lasts: another version
+ *   of the app holds the local data. Ask the user to close the app's other
+ *   tabs. It clears when the wait ends.
+ * - {@link ProtocolError} does not block the app: sync with a relay failed for an
+ *   owner, because the relay rejected or failed a request, or sent data that
+ *   could not be decoded or verified; sync state shows the affected routes. A
+ *   {@link ProtocolQuotaError} needs more relay quota, then
+ *   {@link Evolu.requestSync}; a {@link ProtocolVersionError} needs an app or
+ *   relay update.
+ * - {@link StorageQuotaError} does not block the app: a storage or billing quota
+ *   was exceeded, so a batch of an owner's changes was not stored. The built-in
+ *   client storage does not report it yet; a relay's quota arrives as
+ *   {@link ProtocolQuotaError}.
+ * - {@link DecryptWithXChaCha20Poly1305Error} does not block the app: changes
+ *   received for an owner could not be decrypted, so none of their batch was
+ *   stored.
+ * - {@link UnknownError} does not block the app: Evolu logged an unexpected
+ *   failure. Show a generic message.
+ *
+ * @group Core
+ */
+export type EvoluError =
+  | DecryptWithXChaCha20Poly1305Error
+  | OtherBuildRunningError
+  | ProtocolError
+  | StorageQuotaError
+  | UnknownError
+  | UnsupportedDbVersionError;
+
+/**
+ * The largest {@link Mutation}, in bytes.
+ *
+ * A mutation's size is its change as encoded for sync: the table name, the ID,
+ * and every column name and value, with a few bytes of overhead. A string takes
+ * at most three bytes per UTF-16 code unit. Every mutation within the limit
+ * fits one protocol message, so it can always sync. A larger mutation throws
+ * and is not saved. Mutations of local-only tables are exempt, because they
+ * never sync. Measure a mutation in advance with {@link Evolu.getMutationSize}.
+ *
+ * @group Core
+ */
+export const maxMutationSize: PositiveInt =
+  /*#__PURE__*/ PositiveInt.orThrow(640_000);
+
+/** Measures a mutation as {@link maxMutationSize} describes. */
+const measureMutation = (
+  table: string,
+  values: ReadonlyRecord<string, SqliteValue | undefined>,
+): PositiveInt => {
+  const columns = createMutableRecord<string, SqliteValue>();
+  for (const [column, value] of objectToEntries(values)) {
+    if (value !== undefined && column !== "id" && column !== "isDeleted") {
+      columns[column] = value;
+    }
+  }
+
+  // Measuring with the protocol's encoding keeps the limit and the message size
+  // from disagreeing. A separate formula would save the tab about 3 KB
+  // compressed, but it would be a second encoding to keep in sync, and it
+  // would have to overcount.
+  const buffer = createBuffer();
+  encodeDbChange(buffer, {
+    // Every timestamp and ID takes 16 bytes, and the flags always take one.
+    timestamp: createTimestamp(),
+    change: DbChange.orThrow({
+      table,
+      id: mutationSizeId,
+      values: columns,
+      isInsert: true,
+      isDelete: null,
+    }),
+  });
+  return buffer.getLength() as PositiveInt;
+};
+
+const mutationSizeId = /*#__PURE__*/ Id.orThrow("A".repeat(22));
+
+/**
+ * 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 +981,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 +1095,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 +1113,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 +1167,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 +1238,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 +1418,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;
@@ -1202,6 +1526,41 @@ export const createEvolu =
           `Invalid DbChange for table '${String(table)}'.`,
         );
 
+        // Copy binary values, so what is saved is what was passed: the caller
+        // can change a Uint8Array before the batch is sent, a view of a
+        // resizable buffer can grow, and a view of a shared buffer cannot be
+        // sent to a SharedWorker at all. Node's Buffer passes validation and
+        // its slice shares memory, so only the constructor copies reliably.
+        for (const [column, value] of objectToEntries(dbChange.values)) {
+          if (typeof value === "object" && value !== null) {
+            changeValues[column] = new Uint8Array(value);
+          }
+        }
+
+        // A change over maxMutationSize could never sync, and a shared worker
+        // hosting two databases would stop all work of that database. Correct
+        // apps bound column Types, so it is a programmer error and throws like
+        // the DbChange check above, before batching: it gets no timestamp, the
+        // database worker never sees it, and the code after the call does not
+        // run, so a form keeps its input and no row refers to the missing one.
+        //
+        // Rejected: reporting it through evoluError, which lets that code run
+        // as if the mutation was saved; checking in the database worker, which
+        // gets it already batched and cannot reach the call site; quarantine,
+        // which holds changes stored for sync; and skipping it in sync, which
+        // keeps range fingerprints disagreeing. Received changes are not
+        // checked, and oversized changes stored before this limit are not
+        // recovered, which needs a history-aware design.
+        //
+        // Local-only tables never sync, so they have no limit.
+        if (!isLocalOnlyTable(dbChange.table)) {
+          const size = measureMutation(dbChange.table, dbChange.values);
+          assert(
+            size <= maxMutationSize,
+            `The mutation of table '${dbChange.table}' is ${size} bytes, over maxMutationSize (${maxMutationSize}). Bound the Types of its columns or check it with evolu.getMutationSize.`,
+          );
+        }
+
         mutateBatch.push({
           change: { ...dbChange, ownerId: options?.ownerId ?? appOwner.id },
           onComplete: options?.onComplete,
@@ -1290,6 +1649,12 @@ export const createEvolu =
           update: createMutation("update"),
           upsert: createMutation("upsert"),
 
+          getMutationSize: (table, values) =>
+            measureMutation(
+              String(table),
+              values as ReadonlyRecord<string, SqliteValue | undefined>,
+            ),
+
           loadQuery,
           loadQueries: <Q extends Queries<S>>(
             queries: [...Q],
@@ -1311,6 +1676,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 +1733,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,
       ),