@evolu/common 8.12.0 → 8.14.0

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

@@ -53,7 +53,9 @@
  * still waiting after three seconds reports {@link OtherBuildRunningError} to
  * its tabs. Every build broadcasts console entries and errors on
  * {@link consoleEntryOrErrorBroadcastChannelName}, so a waiting tab also prints
- * the running build's output and reports its errors as its own `evoluError`.
+ * the running build's output, reports each {@link UnknownError} it sends as its
+ * own `evoluError`, and only logs any other error, such as an older build's
+ * sync error.
  *
  * The tabs of one worker elect the host of its DbWorkers among themselves, with
  * a lock scoped to the worker, so a tab of another worker never hosts them.
@@ -67,13 +69,20 @@
  *
  * ## Storage
  *
- * A platform that can lack persistent storage, as a browser does in Safari's
- * Private Browsing, provides {@link PersistentStorageDep}. The worker checks it
- * once, after it takes the build lock and before any DbWorker starts. Without
- * persistent storage, every DbWorker it starts keeps its database in memory,
- * replacements included, and each tab that connects is told with
- * `StorageUnavailable`. The decision holds for the worker's lifetime, so all
- * its tabs see one mode, and the next worker checks again.
+ * The platform tells the worker with {@link DevicePersistenceDep} what it can
+ * promise about stored databases. The worker asks once, after it takes the
+ * build lock and before any DbWorker starts. A browser checks whether it can
+ * open the origin private file system, which Safari's Private Browsing and
+ * Firefox's private windows refuse. Without persistent storage, every DbWorker
+ * the worker starts keeps its database in memory, replacements included. The
+ * decision holds for the worker's lifetime, so all its tabs see one mode, and
+ * the next worker checks again.
+ *
+ * A tenant tells each instance it adds its {@link Evolu.devicePersistence}:
+ * `NotPersisted` when its database is kept in memory, because of the platform
+ * or {@link EvoluConfig.memoryOnly}, otherwise what the platform promised.
+ * Instances of one name share the tenant, so a later instance gets the mode the
+ * first one chose.
  *
  * The check cannot tell a private session from a storage failure, but memory
  * loses nothing that refusing to start would have kept, and the persistent
@@ -100,7 +109,8 @@
  * writable registrations for its owner, whichever instance made it, even one
  * disposed before the database worker answered. When a relay frame stores new
  * messages, the tenant requests a round through each other transport claimed
- * for the owner, so data learned from one relay reaches the others. A closed
+ * for the owner, so data learned from one relay reaches the others, except
+ * through a route that skipped a message, as described below. A closed
  * transport reconciles when it opens, and a replacement leader reconciles every
  * transport again, because a response reporting stored messages may have been
  * lost.
@@ -109,26 +119,34 @@
  * also delivers it as local Broadcast frames to every other tenant with
  * writable access to the owner, even while sockets are closed. A copy keeps the
  * uploader's target, and a recipient that stores new continuation messages
- * reconciles them through the transports outside that target. Local delivery
- * forwards uploads, including historical messages sent during reconciliation,
- * but does not reconcile local database histories with each other. That waits
- * until replication scopes and retention semantics are defined.
+ * reconciles them through the transports outside that target, except through a
+ * route that skipped a message. Local delivery forwards uploads, including
+ * historical messages sent during reconciliation, but does not reconcile local
+ * database histories with each other. That waits until replication scopes and
+ * retention semantics are defined.
  *
  * ## Sync state
  *
  * The shared worker publishes one plain snapshot, {@link SyncState}, of every
  * transport it manages and every database and owner registration it holds, with
- * one route per writable registration and transport, as specified below.
- * {@link syncStateToOwnerSyncStates} derives one state per database and owner.
+ * one route per writable registration and transport, as specified below. Each
+ * part is a union of the states the worker keeps for it: a transport's
+ * connection, a database that is active or refused startup, a writable or
+ * readonly owner, and a pending, settled, or complete route. A transport's
+ * events drive its connection, so publishing never reads a socket.
+ *
+ * Apps show users an owner's {@link OwnerSyncStatus}, which
+ * {@link syncStateToOwnerSyncStatus} derives. A view of each relay pairs each
+ * route with its transport by {@link syncStateToRelaySyncStates} and tells the
+ * relay's status by {@link relaySyncStateToStatus}. Snapshots store neither, so
+ * a status never disagrees with the routes it comes from.
  *
  * Each worker broadcasts snapshots on its own channel, whose name a connecting
  * tab receives through its port, so a tab never hears another worker, such as
  * one of a different app version, and
  * {@link SyncStateDep.syncState | deps.syncState} keeps the last snapshot. The
- * worker publishes after every change it observes; a transition without an
- * event, such as a closed socket starting to reconnect, appears with the next
- * snapshot. The snapshot lives in worker memory only, so a new worker starts
- * empty.
+ * worker publishes after every change it observes. The snapshot lives in worker
+ * memory only, so a new worker starts empty.
  *
  * ## Synchronization completion
  *
@@ -156,27 +174,51 @@
  * - The tenant has sent a round through the transport since the last event that
  *   requires one: its first use of the transport for the owner, the socket
  *   opening, an explicit request, a replacement leader, or storing messages
- *   from another transport. No failed or aborted result has arrived on the
- *   route since.
+ *   from another transport, unless the route skipped a message. No failed or
+ *   aborted result has arrived on the route since.
+ * - No result that skipped a received message has arrived on the route since a
+ *   round was last requested through it, and since that request, no messages
+ *   have been stored from another transport, directly or through a sibling copy
+ *   uploaded outside this transport, and no sibling copy has failed to apply or
+ *   skipped a message.
+ *
+ * A route is settled when every condition except the last holds, so a complete
+ * route is settled too. A settled route that is incomplete has ended its
+ * reconciliation, but its relay may offer a message the database skipped, or
+ * messages stored elsewhere may not have reached it; it is published as
+ * {@link SettledSyncRoute}.
  *
  * A reconciliation chain ends only with a converged result, a failure, an
  * abort, a dropped frame, or a continuation that finds the socket closed, and
  * relay errors reach every applying tenant, so these conditions mean every
  * chain, including this tenant's, converged. A local Broadcast from a sibling
  * tenant holds every route of its owner until it is applied, because it arrives
- * without a request of its own; one that fails to apply requires a round
- * through every transport.
+ * without a request of its own; one that fails to apply or skips a message
+ * requires a round through every transport whose route has not skipped one.
  *
  * A failed result on a route requests one round through it. Any further failure
- * before the route completes waits for an explicit request or a reopen, so a
+ * before the route settles waits for an explicit request or a reopen, so a
  * persistent failure cannot loop; a converged reply in between does not end the
  * wait, because it may answer another tenant's round on the shared socket. An
  * aborted apply leaves its routes incomplete without a retry. An exception
  * while the database worker creates a round is logged there and fails the
- * round's routes with `SyncFailed` without a retry; other unexpected SQLite
- * exceptions remain unsupported and can panic the database worker. A frame the
- * relay silently drops, such as invalid data, leaves the count above zero until
- * the liveness rule below replaces the socket.
+ * round's routes with `SyncFailed` without a retry. A mutation that throws is
+ * rolled back and reported as an {@link UnknownError} to the tab that made it,
+ * or to every tab when its Evolu instance was disposed first. Other unexpected
+ * SQLite exceptions remain unsupported and can panic the database worker. A
+ * frame the relay silently drops, such as invalid data, leaves the count above
+ * zero until the liveness rule below replaces the socket.
+ *
+ * A result that skipped a received message the database could not decrypt,
+ * verify, or decode records the error on the route as its `skippedError`,
+ * without ending its chain, so it requests no round, and the relay offers the
+ * message again in every round through the route until the database stores a
+ * message with that timestamp. The messages received elsewhere that the last
+ * condition names request no round through such a route, even while a requested
+ * round checks it again, because each round would download every skipped
+ * message again. The next round that a first use of the transport for the
+ * owner, an explicit request, a reopen, a replacement leader, or a failure
+ * sends through the route reconciles them.
  *
  * ### Liveness
  *
@@ -196,11 +238,13 @@
  * The timeout belongs to the transport, not to an owner, because a small reply
  * for one owner can wait behind another owner's large frame on the socket. A
  * grown timeout lasts while a request is outstanding on the socket or a
- * database that has not refused startup has an incomplete route through it,
- * including one waiting after a failure, and ends with the transport. A reply's
- * speed proves nothing, because a recovery on a slow link starts with small
- * replies that arrive quickly. The reopen resets the counts and starts the open
- * rounds, so a dropped frame delays a route instead of stranding it.
+ * database that has not refused startup has an unsettled route through it,
+ * including one waiting after a failure, and ends with the transport. A settled
+ * route that is incomplete does not count, because its reconciliation has
+ * ended. A reply's speed proves nothing, because a recovery on a slow link
+ * starts with small replies that arrive quickly. The reopen resets the counts
+ * and starts the open rounds, so a dropped frame delays a route instead of
+ * stranding it.
  *
  * The shared worker sends nothing while idle, so a path that dies then may go
  * unnoticed until its next request; until then, changes from other devices stop
@@ -213,7 +257,8 @@
 import { type NonEmptyReadonlyArray } from "../Array.ts";
 import type { Brand } from "../Brand.ts";
 import type { ConsoleEntry, ConsoleLevel } from "../Console.ts";
-import type { EncryptionKey } from "../Crypto.ts";
+import type { DecryptWithXChaCha20Poly1305Error, EncryptionKey } from "../Crypto.ts";
+import { type UnknownError } from "../Error.ts";
 import { type LockManagerDep } from "../LockManager.ts";
 import { type Result } from "../Result.ts";
 import type { NonEmptyReadonlySet } from "../Set.ts";
@@ -221,12 +266,12 @@ import type { SqliteSchema } from "../Sqlite.ts";
 import { AbortError, type Task } from "../Task.ts";
 import { type Millis } from "../Time.ts";
 import { type ExtractTyped, type Id, type InferType, type LiteralType, type Name, type ObjectType, type Typed } from "../Type.ts";
-import type { CreateWebSocketDep, WebSocketError, WebSocketReadyState } from "../WebSocket.ts";
+import type { CreateWebSocketDep, WebSocketError } from "../WebSocket.ts";
 import type { SharedWorker as CommonSharedWorker, CreateBroadcastChannelDep, CreateMessageChannelDep, NativeMessagePort, SharedWorkerSelf, WorkerDeps } from "../Worker.ts";
 import type { DbWorkerInit, UnsupportedDbVersionError } from "./Db.ts";
-import type { EvoluError } from "./Evolu.ts";
+import type { DevicePersistence } from "./Evolu.ts";
 import type { Owner, OwnerId, SyncOwner } from "./Owner.ts";
-import { type ApplyProtocolMessageAsClientResult, type ProtocolError, type ProtocolMessage } from "./Protocol.ts";
+import { type ApplyProtocolMessageAsClientResult, type ProtocolError, type ProtocolInvalidDataError, type ProtocolMessage, type ProtocolTimestampMismatchError } from "./Protocol.ts";
 import { type Patch, type Query, type RowsByQueryMap } from "./Query.ts";
 import { type MutationChange } from "./Schema.ts";
 import type { CrdtMessage, StorageWriteMessagesError } from "./Storage.ts";
@@ -256,11 +301,11 @@ export type SharedWorkerInput = {
 };
 export type SharedWorkerOutput = DbWorkerInit | {
     /**
-     * Sent to one tab only: its database refused startup, or another build
-     * keeps this worker waiting.
+     * Sent to one tab only: its database refused startup, a mutation it made
+     * could not be stored, or another build keeps this worker waiting.
      */
     readonly type: "Error";
-    readonly error: UnsupportedDbVersionError | OtherBuildRunningError;
+    readonly error: OtherBuildRunningError | UnknownError | UnsupportedDbVersionError;
 } | {
     /**
      * Sent to a tab that connects while the worker waits for the build lock;
@@ -278,20 +323,13 @@ export type SharedWorkerOutput = DbWorkerInit | {
     readonly type: "Connected";
     readonly workerId: SharedWorkerId;
     readonly syncStateChannelName: string;
-} | {
-    /**
-     * Sent to a connecting tab after `Connected` when the platform offers no
-     * persistent storage, so the worker keeps every database in memory; see
-     * Storage in this module's documentation.
-     */
-    readonly type: "StorageUnavailable";
 };
 export type ConsoleEntryOrError = {
     readonly type: "ConsoleEntry";
     readonly entry: ConsoleEntry;
 } | {
     readonly type: "Error";
-    readonly error: EvoluError;
+    readonly error: UnknownError;
 };
 export declare const consoleEntryOrErrorBroadcastChannelName = "evolu:console-entry-or-error";
 /** Identifies one running SharedWorker instance. */
@@ -337,126 +375,467 @@ export interface BuildWaitingRequest extends InferType<typeof BuildWaitingReques
 export interface OtherBuildRunningError extends Typed<"OtherBuildRunningError"> {
 }
 /**
- * A snapshot of the transports and databases the shared worker manages.
- *
- * See the Sync state section of this module's documentation.
+ * A snapshot of the transports and databases the shared worker manages. Each
+ * part is a union of the states the worker keeps for it, so each part holds
+ * only the fields valid for its state. Apps derive what to show with
+ * {@link syncStateToOwnerSyncStatus}; see Sync state in this module's
+ * documentation.
  */
 export interface SyncState {
     readonly transports: ReadonlyArray<SyncTransport>;
     readonly tenants: ReadonlyArray<SyncTenant>;
 }
-/** One WebSocket, shared by every owner and database claiming it. */
-export interface SyncTransport {
-    /** Opaque and stable for the transport's lifetime, across socket replacements. */
+/**
+ * One transport, shared by every owner and database claiming it. Its `type` is
+ * the kind of transport, and its {@link SyncConnection} tells whether it is
+ * connected.
+ */
+export type SyncTransport = WebSocketSyncTransport;
+/** A WebSocket {@link SyncTransport}. */
+export interface WebSocketSyncTransport extends Typed<"WebSocket"> {
+    /** Opaque and stable for the transport's lifetime, across reconnects. */
     readonly id: SyncTransportId;
-    /** The URL without its query, which carries the owner ID. */
+    /** The relay URL without the owner-specific query. */
     readonly label: string;
-    readonly readyState: WebSocketReadyState;
-    /** When the connection last opened, or null before its first open. */
-    readonly openedAt: Millis | null;
-    /** When the connection last closed, or null before its first close. */
-    readonly closedAt: Millis | null;
-    /**
-     * The last error, retained after a successful reconnect; null if none. Errors
-     * while reconnecting are routine.
-     */
-    readonly error: SyncTransportError | null;
+    readonly connection: SyncConnection;
 }
 export type SyncTransportId = Id & Brand<"SyncTransport">;
 export interface SyncTransportError {
     readonly type: WebSocketError["type"];
     readonly at: Millis;
 }
-/** One named local database and the owners it registered. */
-export interface SyncTenant {
+/**
+ * The connection of a {@link SyncTransport}: `Connecting` until its first
+ * connection opens or fails, `Open` while a connection is open, and
+ * `Disconnected` from a close, a failure, or an unanswered request that
+ * replaced the connection, until a connection opens again. It never returns to
+ * `Connecting`. The transport's events drive these states.
+ */
+export type SyncConnection = ConnectingSyncConnection | OpenSyncConnection | DisconnectedSyncConnection;
+/**
+ * A first connection, which has neither opened nor failed. A connection to a
+ * host that drops packets stays here until the operating system or browser
+ * gives up on it, which can take a minute or more.
+ */
+export interface ConnectingSyncConnection extends Typed<"Connecting"> {
+}
+/** An open connection. */
+export interface OpenSyncConnection extends Typed<"Open"> {
+    /** When this connection opened. */
+    readonly openedAt: Millis;
+    /** The last error of an earlier connection or attempt, or null. */
+    readonly error: SyncTransportError | null;
+}
+/**
+ * No connection: a connection closed or failed, or the relay did not answer a
+ * request in time. The transport reconnects by itself.
+ */
+export interface DisconnectedSyncConnection extends Typed<"Disconnected"> {
+    /** When it disconnected. Failed reconnect attempts leave it unchanged. */
+    readonly disconnectedAt: Millis;
+    /** When the last connection opened, or null when none has. */
+    readonly openedAt: Millis | null;
+    /**
+     * The last error, or null. A close or an unanswered request records none, so
+     * it can come from an earlier connection. Errors while reconnecting are
+     * routine.
+     */
+    readonly error: SyncTransportError | null;
+}
+/** One named local database: `Active`, or `Refused` when it refused startup. */
+export type SyncTenant = ActiveSyncTenant | RefusedSyncTenant;
+/**
+ * A database that has not refused startup, including one still starting, with
+ * the owners its instances registered.
+ */
+export interface ActiveSyncTenant extends Typed<"Active"> {
     readonly name: Name;
-    /** The database refused startup, so nothing it holds synchronizes. */
-    readonly refused: boolean;
     readonly owners: ReadonlyArray<SyncTenantOwner>;
 }
-export interface SyncTenantOwner {
+/**
+ * A database that refused startup, so nothing it holds syncs. Its tabs also
+ * receive the error through `evoluError`.
+ */
+export interface RefusedSyncTenant extends Typed<"Refused"> {
+    readonly name: Name;
+    readonly error: UnsupportedDbVersionError;
+}
+/**
+ * An owner registered by any instance of an {@link ActiveSyncTenant}: `Writable`
+ * when any registration holds its write key, otherwise `Readonly`.
+ */
+export type SyncTenantOwner = WritableSyncTenantOwner | ReadonlySyncTenantOwner;
+/**
+ * An owner the database syncs, with one route per transport claimed for it by
+ * this or any other database. Routes are briefly empty while the owner's
+ * transports are being claimed.
+ */
+export interface WritableSyncTenantOwner extends Typed<"Writable"> {
+    readonly ownerId: OwnerId;
+    readonly routes: ReadonlyArray<SyncRoute>;
+}
+/**
+ * An owner registered only without its write key. Its registrations hold
+ * transports, which other databases' routes for the owner use, but this
+ * database does not sync it.
+ */
+export interface ReadonlySyncTenantOwner extends Typed<"Readonly"> {
     readonly ownerId: OwnerId;
-    /** A readonly registration holds transports but never synchronizes. */
-    readonly writable: boolean;
     /** Every transport claimed for the owner, by any database. */
     readonly transportIds: ReadonlyArray<SyncTransportId>;
-    /** One route per transport for a writable owner; none for a readonly one. */
-    readonly routes: ReadonlyArray<SyncRoute>;
 }
 /**
- * One database's use of one owner through one transport. See the
- * Synchronization completion section of this module's documentation.
+ * One database's use of one owner through one transport: `Pending` until its
+ * reconciliation ends, then `Complete`, or `Settled` while its relay offers a
+ * change the database skipped. See Synchronization completion in this module's
+ * documentation.
+ */
+export type SyncRoute = PendingSyncRoute | SettledSyncRoute | CompleteSyncRoute;
+/**
+ * A route whose reconciliation has not ended: its transport is not open, a
+ * request or a received frame is outstanding, a replicated write is queued, or
+ * a round must still be sent through it.
  */
-export interface SyncRoute {
+export interface PendingSyncRoute extends Typed<"Pending"> {
     readonly transportId: SyncTransportId;
-    /** Whether the database is reconciled with the relay for the owner. */
-    readonly complete: boolean;
+    /**
+     * The failure since the route last settled, or null. The first one requests a
+     * round; a further one waits for {@link Evolu.requestSync} or a reopen.
+     */
+    readonly failure: SyncRouteError | null;
+    /**
+     * The first change skipped in the latest reply that skipped one, or null. The
+     * relay offers it again in every round through the route until this database
+     * stores a change with that timestamp.
+     */
+    readonly skippedError: SyncRouteError | null;
     /** When the route last became complete, or null. */
     readonly completeAt: Millis | null;
     /** When this database last sent a request through the route, or null. */
     readonly lastSentAt: Millis | null;
     /**
      * When processing a frame from the route last finished, successfully or with
-     * a failure, or null. Aborted processing does not update this timestamp.
+     * a failure, or null. Aborted processing does not update it.
      */
     readonly lastReceivedAt: Millis | null;
-    /** The last failed result on the route; cleared when the route completes. */
-    readonly error: SyncRouteError | null;
 }
-export interface SyncRouteError {
-    readonly type: SyncRouteErrorType;
-    readonly at: Millis;
-}
-/**
- * A {@link ProtocolError} or the original {@link StorageWriteMessagesError} type
- * for a rejected write. `WriteFailed` means a `writeMessages` call that threw,
- * logged by the protocol, and `SyncFailed` means a logged failure while
- * creating a round or reconciling ranges.
- */
-export type SyncRouteErrorType = ProtocolError["type"] | StorageWriteMessagesError["type"] | "WriteFailed" | "SyncFailed";
 /**
- * One owner's standing with its relays in one database, derived from
- * {@link SyncState} by {@link syncStateToOwnerSyncStates}.
+ * A route whose reconciliation ended while its relay offers a change the
+ * database skipped, so it is incomplete. Changes stored from other relays
+ * request no round through it; the next round requested through it, such as by
+ * {@link Evolu.requestSync} or a reopen, checks it again.
  */
-export interface OwnerSyncState {
-    readonly name: Name;
-    readonly ownerId: OwnerId;
-    readonly status: OwnerSyncStatus;
-    /** When a route of the owner last became complete, or null. */
-    readonly syncedAt: Millis | null;
-    /** The newest route error of the owner, or null. */
-    readonly error: SyncRouteError | null;
-    /** Each relay of the owner, in the order of its routes. */
-    readonly relays: ReadonlyArray<RelaySyncState>;
+export interface SettledSyncRoute extends Typed<"Settled"> {
+    readonly transportId: SyncTransportId;
+    /** The first change skipped in the latest reply that skipped one. */
+    readonly skippedError: SyncRouteError;
+    /** When the route last became complete, or null. */
+    readonly completeAt: Millis | null;
+    /** When this database last sent a request through the route. */
+    readonly lastSentAt: Millis;
+    /** When processing a frame from the route last finished, or null. */
+    readonly lastReceivedAt: Millis | null;
+}
+/** A route on which the database is reconciled with the relay for the owner. */
+export interface CompleteSyncRoute extends Typed<"Complete"> {
+    readonly transportId: SyncTransportId;
+    /** When the route became complete. */
+    readonly completeAt: Millis;
+    /** When this database last sent a request through the route. */
+    readonly lastSentAt: Millis;
+    /** When processing a frame from the route last finished, or null. */
+    readonly lastReceivedAt: Millis | null;
 }
 /**
- * The status of an {@link OwnerSyncState}: the first of `error`, `syncing`,
- * `synced`, and `offline` that one of its relays has, or `initial` before the
- * owner has a relay. Work in progress on an open transport shows before a relay
- * that is already up to date.
+ * A failure or a skipped change of a {@link SyncRoute}, with the time it
+ * arrived.
+ *
+ * It is the error itself, so it carries its details, such as the expected and
+ * actual timestamps of a {@link ProtocolTimestampMismatchError}. A skipped
+ * message adds {@link DecryptWithXChaCha20Poly1305Error}. A
+ * {@link ProtocolInvalidDataError} leaves out its data, which can be a whole
+ * frame. The caught value in the `error` of either is an {@link UnknownError}.
+ * `WriteFailed` means a `writeMessages` call that threw, logged by the
+ * protocol, and `SyncFailed` means a logged failure while creating a round or
+ * reconciling ranges.
  */
-export type OwnerSyncStatus = "initial" | RelaySyncStatus;
+export type SyncRouteError = (Exclude<ProtocolError, ProtocolInvalidDataError> | Omit<ProtocolInvalidDataError, "data"> | StorageWriteMessagesError | DecryptWithXChaCha20Poly1305Error | Typed<"WriteFailed"> | Typed<"SyncFailed">) & {
+    readonly at: Millis;
+};
+/** The type of a {@link SyncRouteError}. */
+export type SyncRouteErrorType = SyncRouteError["type"];
 /**
- * One relay of an {@link OwnerSyncState}: a transport and the database's route
- * through it.
+ * One relay of an owner in one database: a transport and the database's route
+ * through it, from {@link syncStateToRelaySyncStates}. Its status comes from
+ * {@link relaySyncStateToStatus} and is not stored beside them.
  */
 export interface RelaySyncState {
     readonly transport: SyncTransport;
     readonly route: SyncRoute;
-    readonly status: RelaySyncStatus;
 }
 /**
- * The status of a {@link RelaySyncState}: `error` when its route failed and has
- * not completed since, `synced` when the route is complete, `syncing` while the
- * transport is open, and `offline` otherwise.
+ * What an app shows users about syncing one owner of one database, from
+ * {@link syncStateToOwnerSyncStatus} or the React and Vue `useOwnerSyncStatus`.
+ *
+ * Its variants:
+ *
+ * - `NoRelays`: nothing syncs the owner here. There is no snapshot yet, the
+ *   owner's transports are still being set up, the app uses no relays for it,
+ *   it is registered only as readonly, or the database refused startup, which
+ *   `evoluError` reports.
+ * - `Syncing`: a relay connects for the first time or reconciles. A first
+ *   connection to a host that drops packets stays `Syncing` until the platform
+ *   gives up on it, which can take a minute.
+ * - `Synced`: a relay is up to date, and none syncs.
+ * - `Offline`: every relay is disconnected. Evolu keeps reconnecting, up to 30
+ *   seconds apart, so `Offline` can briefly outlast the outage.
+ * - `Error`: a relay failed or offers a change this database skipped. `error` is
+ *   the newest failure, or without one, the newest skipped change: a failure
+ *   stops syncing through its relay, while a skipped change leaves out only
+ *   that change.
+ *
+ * Evolu stores changes in the local database before they sync, so sync needs no
+ * UI while it works: show nothing for `NoRelays`, `Syncing`, and `Synced`. An
+ * indicator that changes with every edit distracts, and screen readers announce
+ * each change.
+ *
+ * For `Offline` and `Error`, show one quiet line that lasts as long as the
+ * status, not a dialog, which interrupts, or a toast, which disappears while
+ * the problem lasts. Do not say that changes are saved on this device unless
+ * {@link Evolu.devicePersistence} is `Persisted`: a browser may keep them only
+ * for a private session or delete them later. Evolu reports `Offline` at once;
+ * an app may wait a few seconds before showing it, because brief
+ * disconnections, such as waking from sleep, reconnect quickly. For `Error`,
+ * write actionable text for the error types the app can act on, such as a
+ * {@link ProtocolQuotaError}: the relay stores no more data for the owner, so
+ * offer more quota, such as a plan upgrade, then call {@link Evolu.requestSync}
+ * with the owner's ID. For any other error, show generic text that names the
+ * error type, which helps when the user reports it.
+ *
+ * Render the line inside one element with `role="status"` that stays mounted:
+ * screen readers announce changes only in a live region that already exists,
+ * and a polite announcement fits a status that loses nothing. Do not use
+ * `role="alert"`.
+ *
+ * Show the app owner's status once for the whole app, such as below the header,
+ * and another owner's status where the app shows that owner's data. Each Evolu
+ * instance finds its own status by {@link Evolu.name}, so an app with several
+ * databases shows the status of the one the user works in.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, Millis } from "@evolu/common";
+ * import {
+ *   testAppOwner,
+ *   type OwnerSyncStatus,
+ * } from "@evolu/common/local-first";
+ *
+ * // What to tell the user, or null while sync works or is not used.
+ * const syncStatusToMessage = (status: OwnerSyncStatus): string | null => {
+ *   switch (status.type) {
+ *     case "NoRelays":
+ *     case "Syncing":
+ *     case "Synced":
+ *       return null;
+ *     case "Offline":
+ *       return "Offline. Changes will sync when you're back online.";
+ *     case "Error":
+ *       return status.error.type === "ProtocolQuotaError"
+ *         ? "Sync is paused because the sync server is full."
+ *         : `Sync error: ${status.error.type}.`;
+ *   }
+ * };
+ *
+ * assertEqual(syncStatusToMessage({ type: "Synced" }), null);
+ * assertEqual(
+ *   syncStatusToMessage({ type: "Offline" }),
+ *   "Offline. Changes will sync when you're back online.",
+ * );
+ * assertEqual(
+ *   syncStatusToMessage({
+ *     type: "Error",
+ *     error: {
+ *       type: "ProtocolQuotaError",
+ *       ownerId: testAppOwner.id,
+ *       at: Millis.orThrow(1000),
+ *     },
+ *   }),
+ *   "Sync is paused because the sync server is full.",
+ * );
+ * assertEqual(
+ *   syncStatusToMessage({
+ *     type: "Error",
+ *     error: { type: "SyncFailed", at: Millis.orThrow(1000) },
+ *   }),
+ *   "Sync error: SyncFailed.",
+ * );
+ * ```
+ */
+export type OwnerSyncStatus = NoRelaysSyncStatus | RelaySyncStatus;
+/**
+ * The status of a {@link RelaySyncState}, from {@link relaySyncStateToStatus}:
+ * `Error` when its route has a failure or a skipped change, the failure first;
+ * otherwise `Synced` when the route is complete, `Syncing` while the
+ * transport's connection is `Connecting` or `Open`, and `Offline` while it is
+ * `Disconnected`.
+ */
+export type RelaySyncStatus = SyncingSyncStatus | SyncedSyncStatus | OfflineSyncStatus | ErrorSyncStatus;
+/** Evolu reports no relay syncing the owner in the database. */
+export interface NoRelaysSyncStatus extends Typed<"NoRelays"> {
+}
+/** A relay makes its first connection or reconciles. */
+export interface SyncingSyncStatus extends Typed<"Syncing"> {
+}
+/** A relay is reconciled with the database for the owner. */
+export interface SyncedSyncStatus extends Typed<"Synced"> {
+}
+/** Relays are disconnected and reconnecting, so changes wait on this device. */
+export interface OfflineSyncStatus extends Typed<"Offline"> {
+}
+/** A route failed or holds a change the database skipped. */
+export interface ErrorSyncStatus extends Typed<"Error"> {
+    /**
+     * The failure, or without one, the skipped change. For an owner, the newest
+     * failure of any relay, or without one, the newest skipped change.
+     */
+    readonly error: SyncRouteError;
+}
+/**
+ * Tells what an app shows about syncing an owner in a database: `Error` when a
+ * relay has one, holding the newest failure of any relay or, without one, the
+ * newest skipped change; otherwise the first of `Syncing`, `Synced`, and
+ * `Offline` that a relay has, or `NoRelays`. Accepts null, the store's value
+ * before the first snapshot. See {@link OwnerSyncStatus} for what to show.
+ *
+ * The same status is the same object: statuses other than `Error` are shared
+ * constants, and an `Error` status is the same object for the same error
+ * object, which {@link SyncStateDep.syncState} keeps between snapshots while it
+ * is unchanged. So compare statuses with `===`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertSame,
+ *   createId,
+ *   createUnknownError,
+ *   Millis,
+ *   testCreateDeps,
+ *   testName,
+ * } from "@evolu/common";
+ * import {
+ *   syncStateToOwnerSyncStatus,
+ *   testAppOwner,
+ *   type PendingSyncRoute,
+ *   type SyncConnection,
+ *   type SyncRoute,
+ *   type SyncState,
+ *   type SyncTransportId,
+ * } from "@evolu/common/local-first";
+ *
+ * const deps = testCreateDeps();
+ * const primaryId = createId<"SyncTransport">(deps);
+ * const backupId = createId<"SyncTransport">(deps);
+ *
+ * const stateOf = (
+ *   connections: ReadonlyArray<SyncConnection>,
+ *   routes: ReadonlyArray<SyncRoute>,
+ * ): SyncState => ({
+ *   transports: connections.map((connection, index) => ({
+ *     type: "WebSocket",
+ *     id: index === 0 ? primaryId : backupId,
+ *     label: "wss://relay.example",
+ *     connection,
+ *   })),
+ *   tenants: [
+ *     {
+ *       type: "Active",
+ *       name: testName,
+ *       owners: [{ type: "Writable", ownerId: testAppOwner.id, routes }],
+ *     },
+ *   ],
+ * });
+ * const pending = (transportId: SyncTransportId): PendingSyncRoute => ({
+ *   type: "Pending",
+ *   transportId,
+ *   failure: null,
+ *   skippedError: null,
+ *   completeAt: null,
+ *   lastSentAt: null,
+ *   lastReceivedAt: null,
+ * });
+ * const statusOf = (state: SyncState | null) =>
+ *   syncStateToOwnerSyncStatus(state, testName, testAppOwner.id);
+ *
+ * // Before the first snapshot, nothing syncs the owner.
+ * assertEqual(statusOf(null), { type: "NoRelays" });
+ *
+ * // A first connection is syncing; a lost one is offline.
+ * const connecting: SyncConnection = { type: "Connecting" };
+ * assertEqual(statusOf(stateOf([connecting], [pending(primaryId)])), {
+ *   type: "Syncing",
+ * });
+ * const disconnected: SyncConnection = {
+ *   type: "Disconnected",
+ *   disconnectedAt: Millis.orThrow(2000),
+ *   openedAt: Millis.orThrow(1000),
+ *   error: null,
+ * };
+ * assertEqual(statusOf(stateOf([disconnected], [pending(primaryId)])), {
+ *   type: "Offline",
+ * });
+ *
+ * // A quota failure on one relay shows before a newer skipped change on
+ * // another, because the app can act on it.
+ * const quotaError = {
+ *   type: "ProtocolQuotaError",
+ *   ownerId: testAppOwner.id,
+ *   at: Millis.orThrow(3000),
+ * } as const;
+ * const open: SyncConnection = {
+ *   type: "Open",
+ *   openedAt: Millis.orThrow(3400),
+ *   error: null,
+ * };
+ * assertEqual(
+ *   statusOf(
+ *     stateOf(
+ *       [disconnected, open],
+ *       [
+ *         { ...pending(primaryId), failure: quotaError },
+ *         {
+ *           type: "Settled",
+ *           transportId: backupId,
+ *           skippedError: {
+ *             type: "DecryptWithXChaCha20Poly1305Error",
+ *             error: createUnknownError(new Error("invalid tag")),
+ *             at: Millis.orThrow(4000),
+ *           },
+ *           completeAt: null,
+ *           lastSentAt: Millis.orThrow(3500),
+ *           lastReceivedAt: Millis.orThrow(4000),
+ *         },
+ *       ],
+ *     ),
+ *   ),
+ *   { type: "Error", error: quotaError },
+ * );
+ *
+ * // The same error gives the same status object.
+ * const quotaState = stateOf(
+ *   [disconnected],
+ *   [{ ...pending(primaryId), failure: quotaError }],
+ * );
+ * assertSame(statusOf(quotaState), statusOf(quotaState));
+ * ```
  */
-export type RelaySyncStatus = "syncing" | "synced" | "offline" | "error";
+export declare const syncStateToOwnerSyncStatus: (state: SyncState | null, name: Name, ownerId: OwnerId) => OwnerSyncStatus;
 /**
- * Folds the routes of every writable owner registration of every running
- * database in a {@link SyncState} into one {@link OwnerSyncState} per database
- * and owner, which pairs each route with its transport as a
- * {@link RelaySyncState}. A database that refused startup and a readonly
- * registration synchronize nothing, so they are left out.
+ * Pairs each route of an owner in a database with its transport, in route
+ * order. Returns none for a null snapshot, a missing or refused database, and a
+ * missing or readonly owner.
  *
  * ### Example
  *
@@ -469,7 +848,8 @@ export type RelaySyncStatus = "syncing" | "synced" | "offline" | "error";
  *   testName,
  * } from "@evolu/common";
  * import {
- *   syncStateToOwnerSyncStates,
+ *   relaySyncStateToStatus,
+ *   syncStateToRelaySyncStates,
  *   testAppOwner,
  *   type SyncRoute,
  *   type SyncState,
@@ -478,52 +858,51 @@ export type RelaySyncStatus = "syncing" | "synced" | "offline" | "error";
  *
  * const deps = testCreateDeps();
  * const transport: SyncTransport = {
+ *   type: "WebSocket",
  *   id: createId<"SyncTransport">(deps),
  *   label: "wss://relay.example",
- *   readyState: "open",
- *   openedAt: null,
- *   closedAt: null,
- *   error: null,
+ *   connection: {
+ *     type: "Open",
+ *     openedAt: Millis.orThrow(800),
+ *     error: null,
+ *   },
  * };
  * const route: SyncRoute = {
+ *   type: "Complete",
  *   transportId: transport.id,
- *   complete: true,
  *   completeAt: Millis.orThrow(1000),
  *   lastSentAt: Millis.orThrow(900),
  *   lastReceivedAt: Millis.orThrow(1000),
- *   error: null,
  * };
  * const state: SyncState = {
  *   transports: [transport],
  *   tenants: [
  *     {
+ *       type: "Active",
  *       name: testName,
- *       refused: false,
  *       owners: [
- *         {
- *           ownerId: testAppOwner.id,
- *           writable: true,
- *           transportIds: [transport.id],
- *           routes: [route],
- *         },
+ *         { type: "Writable", ownerId: testAppOwner.id, routes: [route] },
  *       ],
  *     },
  *   ],
  * };
  *
- * assertEqual(syncStateToOwnerSyncStates(state), [
- *   {
- *     name: testName,
- *     ownerId: testAppOwner.id,
- *     status: "synced",
- *     syncedAt: Millis.orThrow(1000),
- *     error: null,
- *     relays: [{ transport, route, status: "synced" }],
- *   },
- * ]);
+ * const relays = syncStateToRelaySyncStates(
+ *   state,
+ *   testName,
+ *   testAppOwner.id,
+ * );
+ * assertEqual(relays, [{ transport, route }]);
+ * assertEqual(relays.map(relaySyncStateToStatus), [{ type: "Synced" }]);
+ * assertEqual(
+ *   syncStateToRelaySyncStates(null, testName, testAppOwner.id),
+ *   [],
+ * );
  * ```
  */
-export declare const syncStateToOwnerSyncStates: (state: SyncState) => ReadonlyArray<OwnerSyncState>;
+export declare const syncStateToRelaySyncStates: (state: SyncState | null, name: Name, ownerId: OwnerId) => ReadonlyArray<RelaySyncState>;
+/** Tells the status of one relay; a failure shows before a skipped change. */
+export declare const relaySyncStateToStatus: ({ transport, route, }: RelaySyncState) => RelaySyncStatus;
 export type EvoluInput = {
     readonly type: "Mutate";
     readonly changes: NonEmptyReadonlyArray<MutationChange>;
@@ -553,6 +932,14 @@ export type EvoluOutput = {
 } | {
     readonly type: "OnExport";
     readonly file: Uint8Array<ArrayBuffer>;
+} | {
+    /** The mutation with these onComplete callbacks could not be stored. */
+    readonly type: "OnMutateFailed";
+    readonly onCompleteIds: ReadonlyArray<Id>;
+} | {
+    /** Sent once, when the tenant adds the instance; see Storage. */
+    readonly type: "OnDevicePersistence";
+    readonly devicePersistence: DevicePersistence;
 };
 export type DbWorkerInput = (Typed<"Request"> & {
     readonly attemptId: Id;
@@ -609,6 +996,10 @@ export type DbWorkerQueuedResponse = {
         readonly clock: Timestamp;
         readonly messagesByOwnerId: ReadonlyMap<OwnerId, NonEmptyReadonlyArray<CrdtMessage>>;
         readonly rowsByQuery: RowsByQueryMap;
+    } | {
+        /** The mutation threw, so it rolled back and nothing was stored. */
+        readonly type: "MutateFailed";
+        readonly error: UnknownError;
     } | {
         readonly type: "Query";
         readonly rowsByQuery: RowsByQueryMap;
@@ -628,19 +1019,25 @@ export type DbWorkerQueuedResponse = {
         readonly clock: Timestamp;
         readonly ownerId: OwnerId;
         readonly didWriteMessages: boolean;
+        /**
+         * The first error of a received message the DbWorker skipped while
+         * storing the rest, or null. It does not end the round.
+         */
+        readonly skippedError: DecryptWithXChaCha20Poly1305Error | ProtocolInvalidDataError | ProtocolTimestampMismatchError | null;
         readonly result: Result<ApplyProtocolMessageAsClientResult, ProtocolError | StorageWriteMessagesError | AbortError>;
     };
 };
 /**
- * Tells whether the platform can store databases persistently.
+ * Tells what the platform can promise about the databases it stores.
  *
- * Only a platform that can lack persistent storage provides it, as a browser
- * does in Safari's Private Browsing; see Storage in the Shared module.
+ * `NotPersisted` means the platform offers no persistent storage now, as a
+ * browser does in Safari's Private Browsing or a Firefox private window, so the
+ * worker keeps every database in memory; see Storage in the Shared module.
  */
-export interface PersistentStorageDep {
-    readonly isPersistentStorageAvailable: () => Promise<boolean>;
+export interface DevicePersistenceDep {
+    readonly getDevicePersistence: () => Promise<DevicePersistence>;
 }
-export type SharedWorkerDeps = WorkerDeps & CreateBroadcastChannelDep & CreateMessageChannelDep & CreateWebSocketDep & LockManagerDep & Partial<PersistentStorageDep>;
+export type SharedWorkerDeps = WorkerDeps & CreateBroadcastChannelDep & CreateMessageChannelDep & CreateWebSocketDep & DevicePersistenceDep & LockManagerDep;
 export type EvoluInstanceId = Id & Brand<"EvoluInstance">;
 /**
  * Initializes the platform-agnostic Evolu SharedWorker.