@evolu/common 8.10.0 → 8.12.0

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

@@ -1,6 +1,213 @@
 /**
  * Platform-agnostic Evolu SharedWorker.
  *
+ * ## Builds
+ *
+ * Tabs of different app builds can be open at once, for example an old tab
+ * during a deploy. Bundlers derive the worker script's URL from its content, so
+ * every build whose worker code differs gets its own SharedWorker, and all of
+ * them open the same databases. Only one may use them at a time: a request
+ * retried after another worker wrote from the same stored clock can reuse that
+ * write's timestamps and then is skipped as already stored.
+ *
+ * The worker therefore takes an origin-wide lock before it answers any tab and
+ * holds it for its lifetime. A worker of another build waits, with its tabs'
+ * messages buffered, until every tab of the first one is closed or reloaded and
+ * the browser ends it. The lock is the one that earlier releases take in their
+ * leader tab, so they are excluded too. An earlier release's worker can outlive
+ * its leader tab and resume once the lock is free; it computes new timestamps
+ * when it retries, so it cannot reuse another worker's. A tab of an earlier
+ * release that opens while a worker of this release runs gets no response to
+ * its database requests until it reloads, and until then it also blocks workers
+ * that start after this one ends.
+ *
+ * On the web, the wait is usually short, because tabs of the running build
+ * reload to load the build the server now serves:
+ *
+ * 1. A worker tells the tabs that connect before it holds the lock that they wait,
+ *    and such a tab announces the worker with {@link BuildWaiting}. It announces
+ *    again when a tab that connects asks with {@link BuildWaitingRequest}, so a
+ *    tab that started or connected after the first announcement learns of it
+ *    too.
+ * 2. A tab connected to another worker reloads with {@link ReloadApp}: at once if
+ *    the user is not in it, otherwise once they leave it, so a tab never
+ *    reloads while the user works in it. Focus can leave a page from a frame
+ *    without a window event, so such a tab checks once a second whether it
+ *    still has focus. A tab that still waits itself keeps the announcements it
+ *    receives and handles them once it connects, because the lock can pass to
+ *    its worker first.
+ * 3. A page that such a reload loaded never announces, and a tab reloads at most
+ *    once for each waiting worker, so two builds cannot keep reloading each
+ *    other, even when a reload loads the running build again. A tab without
+ *    session storage cannot record its reloads, so it does not reload.
+ *
+ * Only the web platform does this, because only there do builds coexist. A
+ * reload loses UI state the app did not persist, so apps keep drafts in
+ * local-only tables. A write a background tab has in flight can be lost, as
+ * when a tab crashes.
+ *
+ * The wait lasts while a tab of the running build does not reload: a tab of an
+ * earlier release, a tab Safari has frozen, a tab without session storage, or a
+ * tab whose reload loads the running build again, for example because another
+ * Evolu app shares the origin or a cache still serves the old build. A worker
+ * 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 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.
+ * Builds that differ only in DbWorker code share one SharedWorker, and a tab of
+ * either can host its DbWorkers.
+ *
+ * Safari suspends, rather than ends, a worker whose tabs are all in its
+ * back-forward cache, and the suspended worker keeps the lock. There, a waiting
+ * build also waits until Safari drops those pages, or until the user goes back
+ * to one of them, which reloads it on the web.
+ *
+ * ## 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 check cannot tell a private session from a storage failure, but memory
+ * loses nothing that refusing to start would have kept, and the persistent
+ * database stays untouched. Each DbWorker keeps its own memory, so when the tab
+ * hosting it closes, or on the web navigates away, data that exists only
+ * locally or has not synced yet is lost, even though its replacement starts in
+ * memory too.
+ *
+ * ## Synchronization routing
+ *
+ * WebSocket transports are shared resources keyed by their configuration and
+ * claimed by owner ID, so every tenant (one named local database) using an
+ * owner shares that owner's sockets, whichever tenant claimed them. An incoming
+ * frame is offered to every tenant with a writable registration for its owner,
+ * and each tenant reconciles independently: the protocol exchange is stateless
+ * per message and message writes are idempotent, so a response that answered
+ * another tenant's request is still a valid reconciliation step.
+ *
+ * Traffic goes only where it is needed. A continuation returns to the transport
+ * that produced the response, and a round started by a socket opening or by a
+ * tenant's first use of a transport for an owner goes through that transport.
+ * Explicit synchronization requests and mutation uploads go to every open
+ * transport claimed for the owner. A write uploads through the database's
+ * 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
+ * transport reconciles when it opens, and a replacement leader reconciles every
+ * transport again, because a response reporting stored messages may have been
+ * lost.
+ *
+ * Relays omit the sending socket when broadcasting an upload, so the uploader
+ * 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.
+ *
+ * ## 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.
+ *
+ * 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.
+ *
+ * ## Synchronization completion
+ *
+ * A protocol frame carries the owner ID and the message type but nothing that
+ * correlates it with a request, and a relay answers a converged round, an
+ * upload that fits one frame, and an Unsubscribe alike with a header-only
+ * Response. Every tenant with a writable registration applies every frame for
+ * its owner, so a tenant cannot tell which response answered its own request.
+ *
+ * Completion is therefore counted, not attributed. The shared worker counts
+ * outstanding requests per owner and socket: every Request sent on an open
+ * socket, including an Unsubscribe, increments the count; every Response,
+ * including a relay's version-mismatch reply, which has no message type,
+ * decrements it; and an opening socket resets it, because requests on the
+ * previous connection are never answered. A route, one tenant's use of one
+ * owner through one transport, is complete when:
+ *
+ * - The tenant has not refused startup and the socket is open.
+ * - The count is zero.
+ * - The tenant has no apply for the owner queued for that transport or for every
+ *   transport, because a frame is applied asynchronously, so the count reads
+ *   zero in the middle of a chain.
+ * - The tenant has no replicated write for the owner queued, because its upload
+ *   is sent only after the database worker answers it.
+ * - 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.
+ *
+ * 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.
+ *
+ * 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
+ * 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.
+ *
+ * ### Liveness
+ *
+ * An open socket can be dead without a close event, when a NAT drops an idle
+ * mapping or the path fails while nothing is sent. The relay pings every
+ * connection and terminates one from which nothing has arrived since the
+ * previous ping, which also keeps NAT mappings alive. The shared worker
+ * reconnects a socket when a request for an owner has been outstanding for
+ * ninety seconds, enough for a 1 MB frame at about 90 kbit/s, with no Response
+ * for that owner since. Frames for other owners do not count: they prove the
+ * socket alive, not that the request was received.
+ *
+ * A slow link looks like a dead one, because the browser reports no transfer
+ * progress and a large frame saves nothing until it arrives whole. Each timeout
+ * therefore doubles the transport's timeout, up to twenty-four minutes: a
+ * connection that reopens but times out again is more likely slow than dead.
+ * 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.
+ *
+ * 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
+ * arriving while routes still read complete. A periodic empty request would
+ * notice it without waiting for the app to send. That is deferred, because
+ * relay pings already keep NAT mappings alive, the common cause.
+ *
  * @module
  */
 import { type NonEmptyReadonlyArray } from "../Array.ts";
@@ -12,16 +219,18 @@ import { type Result } from "../Result.ts";
 import type { NonEmptyReadonlySet } from "../Set.ts";
 import type { SqliteSchema } from "../Sqlite.ts";
 import { AbortError, type Task } from "../Task.ts";
-import type { Id, Name, Typed } from "../Type.ts";
-import type { CreateWebSocketDep } from "../WebSocket.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 { SharedWorker as CommonSharedWorker, CreateBroadcastChannelDep, CreateMessageChannelDep, NativeMessagePort, SharedWorkerSelf, WorkerDeps } from "../Worker.ts";
-import type { DbWorkerInit } from "./Db.ts";
-import type { EvoluError } from "./Error.ts";
+import type { DbWorkerInit, UnsupportedDbVersionError } from "./Db.ts";
+import type { EvoluError } from "./Evolu.ts";
 import type { Owner, OwnerId, SyncOwner } from "./Owner.ts";
 import { type ApplyProtocolMessageAsClientResult, type ProtocolError, type ProtocolMessage } from "./Protocol.ts";
 import { type Patch, type Query, type RowsByQueryMap } from "./Query.ts";
-import type { MutationChange } from "./Schema.ts";
-import type { CrdtMessage } from "./Storage.ts";
+import { type MutationChange } from "./Schema.ts";
+import type { CrdtMessage, StorageWriteMessagesError } from "./Storage.ts";
+import { type Timestamp } from "./Timestamp.ts";
 export type SharedWorker = CommonSharedWorker<SharedWorkerInput, SharedWorkerOutput>;
 export interface SharedWorkerDep {
     readonly sharedWorker: SharedWorker;
@@ -29,6 +238,12 @@ export interface SharedWorkerDep {
 export type SharedWorkerInput = {
     readonly type: "AnnounceTabLeader";
     readonly consoleLevel: ConsoleLevel;
+} | {
+    /**
+     * Asks the worker to broadcast a {@link SyncState} on its channel, which
+     * the tab opened after receiving its name.
+     */
+    readonly type: "RequestSyncState";
 } | {
     readonly type: "CreateEvolu";
     readonly name: Name;
@@ -39,7 +254,38 @@ export type SharedWorkerInput = {
     readonly memoryOnly: boolean;
     readonly evoluPort: NativeMessagePort<EvoluOutput, EvoluInput>;
 };
-export type SharedWorkerOutput = DbWorkerInit;
+export type SharedWorkerOutput = DbWorkerInit | {
+    /**
+     * Sent to one tab only: its database refused startup, or another build
+     * keeps this worker waiting.
+     */
+    readonly type: "Error";
+    readonly error: UnsupportedDbVersionError | OtherBuildRunningError;
+} | {
+    /**
+     * Sent to a tab that connects while the worker waits for the build lock;
+     * see Builds. `Connected` follows once the worker holds it.
+     */
+    readonly type: "Waiting";
+    readonly workerId: SharedWorkerId;
+} | {
+    /**
+     * Sent to a connecting tab once the worker holds the build lock; see
+     * Builds in this module's documentation. The tab elects the host of the
+     * worker's DbWorkers among the worker's tabs, scoped by `workerId`, and
+     * listens for {@link SyncState} on `syncStateChannelName`.
+     */
+    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;
@@ -48,6 +294,236 @@ export type ConsoleEntryOrError = {
     readonly error: EvoluError;
 };
 export declare const consoleEntryOrErrorBroadcastChannelName = "evolu:console-entry-or-error";
+/** Identifies one running SharedWorker instance. */
+export declare const SharedWorkerId: import("../Type.ts").TableId<"SharedWorker">;
+export type SharedWorkerId = typeof SharedWorkerId.Output;
+/**
+ * The channel on which a tab announces its waiting worker with
+ * {@link BuildWaiting}; see Builds. Builds of different releases share it, so
+ * its name and messages never change.
+ */
+export declare const buildsBroadcastChannelName = "evolu:builds";
+/**
+ * Posted on {@link buildsBroadcastChannelName} by a tab whose worker waits for
+ * the build lock, unless an automatic reload loaded the page, when it starts
+ * waiting and for each {@link BuildWaitingRequest}. A tab connected to another
+ * worker reloads for it; see Builds.
+ */
+export declare const BuildWaiting: ObjectType<{
+    readonly type: LiteralType<"BuildWaiting">;
+    readonly workerId: typeof SharedWorkerId;
+}>;
+export interface BuildWaiting extends InferType<typeof BuildWaiting> {
+}
+/**
+ * Posted on {@link buildsBroadcastChannelName} by a tab once it connects, asking
+ * tabs whose worker waits to post {@link BuildWaiting} again; see Builds.
+ */
+export declare const BuildWaitingRequest: ObjectType<{
+    readonly type: LiteralType<"BuildWaitingRequest">;
+}>;
+export interface BuildWaitingRequest extends InferType<typeof BuildWaitingRequest> {
+}
+/**
+ * Another build of the app holds the local databases, and this tab waits until
+ * every tab of that build is closed or reloaded; see Builds.
+ *
+ * Tabs of the other build usually reload by themselves, so this is reported
+ * only when the wait lasts, for example because the user is still in a tab of
+ * the other build, or that tab runs an earlier release or is frozen by Safari.
+ * Apps can ask the user to close the app's other tabs. It is cleared once the
+ * wait ends.
+ */
+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.
+ */
+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. */
+    readonly id: SyncTransportId;
+    /** The URL without its query, which carries the owner ID. */
+    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;
+}
+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 {
+    readonly name: Name;
+    /** The database refused startup, so nothing it holds synchronizes. */
+    readonly refused: boolean;
+    readonly owners: ReadonlyArray<SyncTenantOwner>;
+}
+export interface SyncTenantOwner {
+    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.
+ */
+export interface SyncRoute {
+    readonly transportId: SyncTransportId;
+    /** Whether the database is reconciled with the relay for the owner. */
+    readonly complete: boolean;
+    /** 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.
+     */
+    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}.
+ */
+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>;
+}
+/**
+ * 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.
+ */
+export type OwnerSyncStatus = "initial" | RelaySyncStatus;
+/**
+ * One relay of an {@link OwnerSyncState}: a transport and the database's route
+ * through it.
+ */
+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.
+ */
+export type RelaySyncStatus = "syncing" | "synced" | "offline" | "error";
+/**
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createId,
+ *   Millis,
+ *   testCreateDeps,
+ *   testName,
+ * } from "@evolu/common";
+ * import {
+ *   syncStateToOwnerSyncStates,
+ *   testAppOwner,
+ *   type SyncRoute,
+ *   type SyncState,
+ *   type SyncTransport,
+ * } from "@evolu/common/local-first";
+ *
+ * const deps = testCreateDeps();
+ * const transport: SyncTransport = {
+ *   id: createId<"SyncTransport">(deps),
+ *   label: "wss://relay.example",
+ *   readyState: "open",
+ *   openedAt: null,
+ *   closedAt: null,
+ *   error: null,
+ * };
+ * const route: SyncRoute = {
+ *   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: [
+ *     {
+ *       name: testName,
+ *       refused: false,
+ *       owners: [
+ *         {
+ *           ownerId: testAppOwner.id,
+ *           writable: true,
+ *           transportIds: [transport.id],
+ *           routes: [route],
+ *         },
+ *       ],
+ *     },
+ *   ],
+ * };
+ *
+ * assertEqual(syncStateToOwnerSyncStates(state), [
+ *   {
+ *     name: testName,
+ *     ownerId: testAppOwner.id,
+ *     status: "synced",
+ *     syncedAt: Millis.orThrow(1000),
+ *     error: null,
+ *     relays: [{ transport, route, status: "synced" }],
+ *   },
+ * ]);
+ * ```
+ */
+export declare const syncStateToOwnerSyncStates: (state: SyncState) => ReadonlyArray<OwnerSyncState>;
 export type EvoluInput = {
     readonly type: "Mutate";
     readonly changes: NonEmptyReadonlyArray<MutationChange>;
@@ -58,6 +534,9 @@ export type EvoluInput = {
     readonly actions: ReadonlyArray<{
         readonly owner: SyncOwner;
         readonly action: "add" | "remove";
+    } | {
+        readonly ownerId: OwnerId;
+        readonly action: "sync";
     }>;
 } | {
     readonly type: "Query";
@@ -76,32 +555,50 @@ export type EvoluOutput = {
     readonly file: Uint8Array<ArrayBuffer>;
 };
 export type DbWorkerInput = (Typed<"Request"> & {
-    readonly callbackId: Id;
-    readonly request: DbWorkerRequest;
-}) | Typed<"Dispose">;
-export type DbWorkerRequest = {
+    readonly attemptId: Id;
+} & ({
+    readonly request: DbWorkerWriteRequest;
+    readonly clock: Timestamp;
+    readonly now: Millis;
+} | {
+    readonly request: DbWorkerReadRequest;
+})) | Typed<"Dispose">;
+export type DbWorkerRequest = DbWorkerWriteRequest | DbWorkerReadRequest;
+export type DbWorkerWriteRequest = {
     readonly type: "ForEvolu";
     readonly id: EvoluInstanceId;
-    readonly message: {
-        readonly [Message in EvoluInput as Message["type"]]: Message;
-    }["Mutate" | "Query" | "Export"];
+    readonly message: ExtractTyped<EvoluInput, "Mutate">;
 } | {
     readonly type: "ForSharedWorker";
     readonly message: {
-        readonly type: "CreateSyncMessages";
-        readonly owners: NonEmptyReadonlyArray<Owner>;
-    } | {
         readonly type: "ApplySyncMessage";
         readonly owner: Owner;
         readonly inputMessage: Uint8Array;
     };
 };
+export type DbWorkerReadRequest = {
+    readonly type: "ForEvolu";
+    readonly id: EvoluInstanceId;
+    readonly message: ExtractTyped<EvoluInput, "Query" | "Export">;
+} | {
+    readonly type: "ForSharedWorker";
+    readonly message: {
+        readonly type: "CreateSyncMessages";
+        readonly owners: NonEmptyReadonlyArray<Owner>;
+    };
+};
 export type DbWorkerOutput = {
     readonly type: "LeaderAcquired";
     readonly name: Name;
+    readonly clock: Timestamp;
+} | {
+    /** Startup was refused; the worker is releasing its resources. */
+    readonly type: "LeaderRefused";
+    readonly name: Name;
+    readonly error: UnsupportedDbVersionError;
 } | {
     readonly type: "OnQueuedResponse";
-    readonly callbackId: Id;
+    readonly attemptId: Id;
     readonly response: DbWorkerQueuedResponse;
 };
 export type DbWorkerQueuedResponse = {
@@ -109,6 +606,7 @@ export type DbWorkerQueuedResponse = {
     readonly id: EvoluInstanceId;
     readonly message: {
         readonly type: "Mutate";
+        readonly clock: Timestamp;
         readonly messagesByOwnerId: ReadonlyMap<OwnerId, NonEmptyReadonlyArray<CrdtMessage>>;
         readonly rowsByQuery: RowsByQueryMap;
     } | {
@@ -123,16 +621,33 @@ export type DbWorkerQueuedResponse = {
     readonly message: {
         readonly type: "CreateSyncMessages";
         readonly protocolMessagesByOwnerId: ReadonlyMap<OwnerId, ProtocolMessage>;
+        /** Owners whose message creation threw; the DbWorker logged it. */
+        readonly failedOwnerIds: ReadonlySet<OwnerId>;
     } | {
         readonly type: "ApplySyncMessage";
+        readonly clock: Timestamp;
         readonly ownerId: OwnerId;
         readonly didWriteMessages: boolean;
-        readonly result: Result<ApplyProtocolMessageAsClientResult, ProtocolError | AbortError>;
+        readonly result: Result<ApplyProtocolMessageAsClientResult, ProtocolError | StorageWriteMessagesError | AbortError>;
     };
 };
-export type SharedWorkerDeps = WorkerDeps & CreateBroadcastChannelDep & CreateMessageChannelDep & CreateWebSocketDep & LockManagerDep;
+/**
+ * Tells whether the platform can store databases persistently.
+ *
+ * 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.
+ */
+export interface PersistentStorageDep {
+    readonly isPersistentStorageAvailable: () => Promise<boolean>;
+}
+export type SharedWorkerDeps = WorkerDeps & CreateBroadcastChannelDep & CreateMessageChannelDep & CreateWebSocketDep & LockManagerDep & Partial<PersistentStorageDep>;
 export type EvoluInstanceId = Id & Brand<"EvoluInstance">;
-export type SyncState = 123;
-/** Initializes the platform-agnostic Evolu SharedWorker. */
+/**
+ * Initializes the platform-agnostic Evolu SharedWorker.
+ *
+ * The worker holds the build lock until it is disposed, so a platform connects
+ * every `createEvoluDeps` call in a JS runtime to one worker, as React Native
+ * does; see Builds.
+ */
 export declare const initSharedWorker: (self: SharedWorkerSelf<SharedWorkerInput, SharedWorkerOutput>) => Task<AsyncDisposableStack, never, SharedWorkerDeps>;
 //# sourceMappingURL=Shared.d.ts.map