@evolu/common 8.10.0 → 8.12.0

package/dist/src/local-first/Evolu.d.ts

@@ -5,29 +5,47 @@
  */
 import { type NonEmptyReadonlyArray } from "../Array.ts";
 import type { ConsoleDep } from "../Console.ts";
+import type { DecryptWithXChaCha20Poly1305Error } from "../Crypto.ts";
+import type { UnknownError } from "../Error.ts";
 import { type LockManagerDep } from "../LockManager.ts";
 import type { FlushSyncDep, ReloadAppDep } from "../Platform.ts";
 import type { Listener, ReadonlyStore, Unsubscribe } from "../Store.ts";
 import type { Task } from "../Task.ts";
-import { Name, type TypeError, UrlSafeString } from "../Type.ts";
+import { Name, PositiveInt, type TypeError, UrlSafeString } from "../Type.ts";
 import type { CreateBroadcastChannelDep, CreateMessageChannelDep } from "../Worker.ts";
-import type { CreateDbWorkerDep } from "./Db.ts";
-import type { EvoluError } from "./Error.ts";
-import type { AppOwner, Owner, OwnerTransport, ReadonlyOwner } from "./Owner.ts";
+import type { CreateDbWorkerDep, UnsupportedDbVersionError } from "./Db.ts";
+import type { AppOwner, Owner, OwnerId, OwnerTransport, ReadonlyOwner } from "./Owner.ts";
+import { type ProtocolError } from "./Protocol.ts";
 import type { Queries, QueriesToQueryRowsPromises, Query, QueryRows, Row } from "./Query.ts";
-import type { EvoluSchema, IndexesConfig, Mutation, ValidateSchema } from "./Schema.ts";
-import type { SharedWorkerDep } from "./Shared.ts";
+import type { EvoluSchema, IndexesConfig, Mutation, MutationValues, ValidateSchema } from "./Schema.ts";
+import type { OtherBuildRunningError, SharedWorkerDep, SyncState } from "./Shared.ts";
+import { type StorageQuotaError } from "./Storage.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
      *
@@ -61,6 +79,69 @@ export interface EvoluConfig {
      *   flow).
      */
     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.
      *
@@ -98,18 +179,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" },
@@ -130,87 +204,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;
 }
 /**
  * Application name.
@@ -221,17 +225,38 @@ export interface EvoluConfig {
  *
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
  * `_`) and must be between 1 and 41 characters.
+ *
+ * @group Configuration
  */
 export declare const AppName: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, "UrlSafeString", import("../Type.ts").RegexError<"UrlSafeString">>, "AppName", AppNameError>;
 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 declare const testAppName: string & import("../Brand.ts").Brand<"UrlSafeString"> & import("../Brand.ts").Brand<"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> extends AsyncDisposable {
     /**
@@ -249,32 +274,29 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * 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(
@@ -288,7 +310,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      *     ReturnType<typeof insertTodo>,
      *     ReturnType<typeof insertTodoAndNotify>,
      *   ],
-     *   [TodoId, TodoId]
+     *   [TestTodoId, TestTodoId]
      * >();
      * ```
      *
@@ -305,30 +327,30 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * ```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]
      * >();
      * ```
      *
@@ -353,40 +375,72 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * 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}.
@@ -397,20 +451,17 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * 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;
      * };
@@ -432,31 +483,22 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * ```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<
@@ -472,28 +514,28 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
     /**
      * 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)(() => {
@@ -513,20 +555,17 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * 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<
@@ -543,7 +582,8 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * 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>>;
     /**
@@ -594,21 +634,15 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * ```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,
@@ -641,15 +675,123 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposa
      * ```
      */
     readonly useOwner: (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 declare const maxMutationSize: PositiveInt;
+/**
+ * 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
      *
@@ -657,62 +799,115 @@ 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 & Disposable;
+export type EvoluDeps = EvoluPlatformDeps & ConsoleDep & EvoluErrorDep & SyncStateDep & Disposable;
 /**
  * Platform-specific dependencies required to create {@link EvoluDeps}.
  *
  * Provides worker and channel adapters plus optional platform integrations for
  * logging and synchronous UI flush.
+ *
+ * @group Construction
  */
 export type EvoluPlatformDeps = CreateDbWorkerDep & CreateBroadcastChannelDep & CreateMessageChannelDep & LockManagerDep & ReloadAppDep & SharedWorkerDep & Partial<ConsoleDep> & Partial<FlushSyncDep>;
 /**
@@ -721,15 +916,19 @@ export type EvoluPlatformDeps = CreateDbWorkerDep & CreateBroadcastChannelDep &
  *
  * 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 declare const createEvoluDeps: (deps: EvoluPlatformDeps) => EvoluDeps;
 /**
  * Creates an {@link Evolu} instance from {@link EvoluSchema} and
  * {@link EvoluConfig}.
+ *
+ * @group Construction
  */
 export declare const createEvolu: <S extends EvoluSchema>(schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>, config: EvoluConfig) => Task<Evolu<S>, never, EvoluPlatformDeps>;
 //# sourceMappingURL=Evolu.d.ts.map