@evolu/common 8.12.0 → 8.13.0

package/src/local-first/Evolu.test.ts

@@ -61,6 +61,7 @@ import {
   type SharedWorkerInput,
   type SharedWorkerOutput,
   type SyncState,
+  syncStateToOwnerSyncStatus,
 } from "./Shared.ts";
 import {
   acquireLeaderLock,
@@ -72,6 +73,7 @@ import { err, ok } from "../Result.ts";
 import { SqliteBoolean } from "../Sqlite.ts";
 import { explicitAbortReason, testCreateDeps, testCreateRun } from "../Task.ts";
 import { testCreateId } from "../Test.ts";
+import { Millis } from "../Time.ts";
 import {
   assertType,
   createIdFromString,
@@ -428,6 +430,7 @@ describe("Evolu", () => {
         tables: { todo: new Set(["title"]) },
         indexes: [],
       };
+      const sharedWorkerId = testCreateId()<"SharedWorker">();
       const sharedWorkerPort: {
         value: MessagePort<SharedWorkerOutput, SharedWorkerInput> | null;
       } = { value: null };
@@ -468,6 +471,7 @@ describe("Evolu", () => {
           sqliteSchema,
           encryptionKey: testAppOwner.encryptionKey,
           memoryOnly: true,
+          sharedWorkerId,
           port: dbWorkerChannel.port1.native,
         },
         [dbWorkerChannel.port1.native],
@@ -483,6 +487,7 @@ describe("Evolu", () => {
         sqliteSchema,
         encryptionKey: testAppOwner.encryptionKey,
         memoryOnly: true,
+        sharedWorkerId,
         port: dbWorkerChannel.port1.native,
       });
 
@@ -592,7 +597,7 @@ describe("Evolu", () => {
       );
       const createState = (label: string): SyncState => ({
         transports: [],
-        tenants: [{ name: Name.orThrow(label), refused: false, owners: [] }],
+        tenants: [{ type: "Active", name: Name.orThrow(label), owners: [] }],
       });
 
       // Nothing reaches the tab before its worker names the channel.
@@ -616,6 +621,214 @@ describe("Evolu", () => {
       assertEqual(deps.syncState.get(), createState("changed"));
     });
 
+    it("keeps the unchanged parts of each sync state snapshot", async () => {
+      using setup = await setupCreateEvoluDeps();
+      const { deps, connect } = setup;
+      const workerId = testCreateId()<"SharedWorker">();
+      using channel = testCreateBroadcastChannel<SyncState>(
+        `evolu:sync-state:${workerId}`,
+      );
+      await connect(workerId);
+      let notificationCount = 0;
+      deps.syncState.subscribe(() => {
+        notificationCount++;
+      });
+      const transportId = testCreateId()<"SyncTransport">();
+      // Every snapshot is a new structured clone. The worker wraps a caught
+      // Error inside an error in an UnknownError, whose cause can hold the
+      // bytes of a received change.
+      const createState = (
+        lastSentAt: number,
+        message = "wrong key",
+      ): SyncState => ({
+        transports: [
+          {
+            type: "WebSocket",
+            id: transportId,
+            label: "wss://relay.example",
+            connection: {
+              type: "Open",
+              openedAt: Millis.orThrow(1000),
+              error: null,
+            },
+          },
+        ],
+        tenants: [
+          {
+            type: "Active",
+            name: testName,
+            owners: [
+              {
+                type: "Writable",
+                ownerId: testAppOwner.id,
+                routes: [
+                  {
+                    type: "Settled",
+                    transportId,
+                    skippedError: {
+                      type: "DecryptWithXChaCha20Poly1305Error",
+                      error: {
+                        type: "UnknownError",
+                        error: {
+                          message,
+                          cause: { values: { photo: Uint8Array.of(1, 2, 3) } },
+                        },
+                      },
+                      at: Millis.orThrow(1500),
+                    },
+                    completeAt: null,
+                    lastSentAt: Millis.orThrow(lastSentAt),
+                    lastReceivedAt: Millis.orThrow(1500),
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      });
+      const routeOf = (state: SyncState | null) => {
+        const tenant = state?.tenants[0];
+        assert(tenant?.type === "Active", "The tenant should be active.");
+        const owner = tenant.owners[0];
+        assert(owner?.type === "Writable", "The owner should be writable.");
+        const route = owner.routes[0];
+        assert(route?.type === "Settled", "The route should be settled.");
+        return route;
+      };
+      const statusOf = (state: SyncState | null) =>
+        syncStateToOwnerSyncStatus(state, testName, testAppOwner.id);
+
+      channel.postMessage(createState(1000));
+      await testWaitForWorkerMessage();
+      const first = deps.syncState.get();
+      assertNotNull(first);
+      assertSame(notificationCount, 1);
+
+      // An equal snapshot leaves the store unchanged.
+      channel.postMessage(createState(1000));
+      await testWaitForWorkerMessage();
+      assertSame(deps.syncState.get(), first);
+      assertSame(notificationCount, 1);
+
+      // A changed route gets a new object, and every unchanged part keeps the
+      // previous one, so the owner's status is the same object.
+      channel.postMessage(createState(2000));
+      await testWaitForWorkerMessage();
+      const second = deps.syncState.get();
+      assertNotNull(second);
+      assertNotSame(second, first);
+      assertSame(notificationCount, 2);
+      assertSame(second.transports, first.transports);
+      assertNotSame(routeOf(second), routeOf(first));
+      assertSame(routeOf(second).skippedError, routeOf(first).skippedError);
+      assertSame(statusOf(second), statusOf(first));
+
+      // An error with another message is a new error and a new status.
+      channel.postMessage(createState(2000, "tampered"));
+      await testWaitForWorkerMessage();
+      const third = deps.syncState.get();
+      assertNotSame(routeOf(third).skippedError, routeOf(second).skippedError);
+      assertNotSame(statusOf(third), statusOf(second));
+    });
+
+    it("keeps each part of a sync state snapshot when one before it goes away", async () => {
+      using setup = await setupCreateEvoluDeps();
+      const { deps, connect } = setup;
+      const createId = testCreateId();
+      const workerId = createId<"SharedWorker">();
+      using channel = testCreateBroadcastChannel<SyncState>(
+        `evolu:sync-state:${workerId}`,
+      );
+      await connect(workerId);
+      const removedTransportId = createId<"SyncTransport">();
+      const transportId = createId<"SyncTransport">();
+      const at = Millis.orThrow(1000);
+      // The full snapshot lists a transport, tenant, owner, and route before
+      // each part the other snapshot keeps. Only the kept route has an error.
+      const createState = (isFull: boolean): SyncState => ({
+        transports: [removedTransportId, transportId]
+          .slice(isFull ? 0 : 1)
+          .map((id) => ({
+            type: "WebSocket",
+            id,
+            label: `wss://${id}.example`,
+            connection: { type: "Open", openedAt: at, error: null },
+          })),
+        tenants: [
+          ...(isFull
+            ? [
+                {
+                  type: "Active" as const,
+                  name: Name.orThrow("removed"),
+                  owners: [],
+                },
+              ]
+            : []),
+          {
+            type: "Active",
+            name: testName,
+            owners: [
+              ...(isFull
+                ? [
+                    {
+                      type: "Writable" as const,
+                      ownerId: createId<"OwnerId">(),
+                      routes: [],
+                    },
+                  ]
+                : []),
+              {
+                type: "Writable",
+                ownerId: testAppOwner.id,
+                routes: [
+                  ...(isFull
+                    ? [
+                        {
+                          type: "Complete" as const,
+                          transportId: removedTransportId,
+                          completeAt: at,
+                          lastSentAt: at,
+                          lastReceivedAt: at,
+                        },
+                      ]
+                    : []),
+                  {
+                    type: "Pending",
+                    transportId,
+                    failure: {
+                      type: "ProtocolQuotaError",
+                      ownerId: testAppOwner.id,
+                      at,
+                    },
+                    skippedError: null,
+                    completeAt: null,
+                    lastSentAt: at,
+                    lastReceivedAt: at,
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      });
+      const statusOf = (state: SyncState | null) =>
+        syncStateToOwnerSyncStatus(state, testName, testAppOwner.id);
+
+      channel.postMessage(createState(true));
+      await testWaitForWorkerMessage();
+      const full = deps.syncState.get();
+      assertNotNull(full);
+      assertSame(statusOf(full).type, "Error");
+
+      channel.postMessage(createState(false));
+      await testWaitForWorkerMessage();
+      const kept = deps.syncState.get();
+      assertNotNull(kept);
+      assertEqual(kept, createState(false));
+      assertSame(kept.transports[0], full.transports[1]);
+      assertSame(statusOf(kept), statusOf(full));
+    });
+
     it("listens on its worker's channel before asking for a snapshot", async () => {
       const name = "evolu:sync-state:worker";
       using worker = testCreateSharedWorker<
@@ -727,6 +940,29 @@ describe("Evolu", () => {
       assertEqual(deps.evoluError.get(), error);
     });
 
+    it("only logs a sync error that an older build broadcasts", async () => {
+      const testConsole = testCreateConsole();
+      using setup = await setupCreateEvoluDeps(testConsole);
+      const { deps, consoleEntryOrErrorBroadcastChannel } = setup;
+      const error = {
+        type: "ProtocolQuotaError",
+        ownerId: testAppOwner.id,
+      } as const;
+
+      consoleEntryOrErrorBroadcastChannel.postMessage({
+        type: "Error",
+        // @ts-expect-error A ConsoleEntryOrError Error carries only an UnknownError, but a still-running worker of an older build posts a ProtocolQuotaError.
+        error,
+      });
+
+      await testWaitForWorkerMessage();
+
+      assertSame(deps.evoluError.get(), null);
+      assertEqual(testConsole.getEntriesSnapshot(), [
+        { method: "error", path: [], args: [error] },
+      ]);
+    });
+
     for (const source of ["SharedWorker", "Error", "ConsoleEntry"] as const) {
       it(`preserves the first startup refusal while logging a later ${source} message`, async () => {
         const testConsole = testCreateConsole();
@@ -1634,6 +1870,50 @@ describe("Evolu", () => {
       assertEqual(called, 0);
     });
 
+    it("releases the onComplete callbacks of a failed mutation without running them", async () => {
+      await using setup = await setupRunWithEvoluDeps();
+      const { run, evoluInputs, postEvoluOutput } = setup;
+      const evolu = await run.ok(testCreateEvolu);
+
+      let called = 0;
+      evolu.insert(
+        "todo",
+        { title: NonEmptyTrimmedString100.orThrow("First failed") },
+        {
+          onComplete: () => {
+            called += 1;
+          },
+        },
+      );
+      evolu.insert(
+        "todo",
+        { title: NonEmptyTrimmedString100.orThrow("Second failed") },
+        {
+          onComplete: () => {
+            called += 10;
+          },
+        },
+      );
+
+      await testWaitForWorkerMessage();
+
+      const mutate = evoluInputs[0] as ExtractTyped<EvoluInput, "Mutate">;
+      const { onCompleteIds } = mutate;
+      assertLength(onCompleteIds, 2);
+
+      postEvoluOutput({ type: "OnMutateFailed", onCompleteIds });
+      // Patches naming released callbacks find nothing to run.
+      postEvoluOutput({
+        type: "OnPatchesByQuery",
+        patchesByQuery: new Map(),
+        onCompleteIds,
+      });
+
+      await testWaitForWorkerMessage();
+
+      assertEqual(called, 0);
+    });
+
     it("executes mutate onComplete callback when query patches are received", async () => {
       await using setup = await setupRunWithEvoluDeps();
       const { run, evoluInputs, postEvoluOutput } = setup;

package/src/local-first/Evolu.ts

@@ -31,7 +31,9 @@ import {
 import { createMicrotaskBatch } from "../Microtask.ts";
 import {
   createMutableRecord,
+  isPlainObject,
   objectToEntries,
+  shareStructure,
   type ReadonlyRecord,
 } from "../Object.ts";
 import type { FlushSyncDep, ReloadAppDep } from "../Platform.ts";
@@ -75,7 +77,9 @@ import { createOwnerWebSocketTransport } from "./Owner.ts";
 import {
   encodeDbChange,
   type ProtocolError,
+  type ProtocolInvalidDataError,
   type ProtocolQuotaError,
+  type ProtocolTimestampMismatchError,
   type ProtocolVersionError,
 } from "./Protocol.ts";
 import type {
@@ -102,12 +106,15 @@ import type {
   EvoluInput,
   EvoluOutput,
   OtherBuildRunningError,
+  OwnerSyncStatus,
+  PendingSyncRoute,
   SharedWorkerDep,
   SyncState,
-  syncStateToOwnerSyncStates,
+  syncStateToOwnerSyncStatus,
+  syncStateToRelaySyncStates,
 } from "./Shared.ts";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
-import { DbChange, type StorageQuotaError } from "./Storage.ts";
+import { DbChange } from "./Storage.ts";
 import { createTimestamp, type Timestamp } from "./Timestamp.ts";
 
 /**
@@ -388,8 +395,10 @@ export interface Evolu<
    *
    * 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}.
+   * is unavailable; see {@link Evolu.loadQuery}. It also never runs when the
+   * mutation could not be stored, which {@link EvoluErrorDep.evoluError}
+   * reports. A stored change is not always visible; see
+   * {@link MutationOptions.onComplete}.
    *
    * ### Example
    *
@@ -707,6 +716,9 @@ export interface Evolu<
   /**
    * Exports the SQLite database file.
    *
+   * The exported file is not encrypted, even when the local database is. Any
+   * SQLite tool can read all local data from it, so treat it as plaintext.
+   *
    * Exports are sequential: concurrent calls share one pending export instead
    * of starting parallel exports.
    *
@@ -818,9 +830,12 @@ export interface Evolu<
    *
    * 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.
+   * this after the relay provider confirms additional quota is available. It
+   * also checks again the changes this database skipped from the owner's
+   * relays, and sends such a relay the changes received from other relays,
+   * which otherwise wait for its next sync, such as after a reconnect. 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
@@ -828,8 +843,9 @@ export interface Evolu<
    * 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}.
+   * Returns immediately, without waiting for synchronization to complete. The
+   * owner's routes in sync state show a failure, such as a quota rejection, as
+   * `failure`, and a skipped change as `skippedError`.
    *
    * ### Example
    *
@@ -858,9 +874,11 @@ export interface Evolu<
 export type UnuseOwner = () => void;
 
 /**
- * Represents errors that can occur in {@link Evolu}.
+ * Represents app-level errors that can occur in {@link Evolu}.
  *
- * Apps show them from {@link EvoluErrorDep.evoluError}.
+ * Apps show them from {@link EvoluErrorDep.evoluError}. Problems a relay causes
+ * while syncing an owner are not EvoluErrors; see below. An unexpected failure
+ * while syncing is an {@link UnknownError}.
  *
  * 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
@@ -874,31 +892,46 @@ export type UnuseOwner = () => void;
  * - {@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.
+ *   failure, such as a mutation that could not be stored. Show a generic
+ *   message.
+ *
+ * A problem syncing an owner through a relay belongs to that relay and often
+ * repeats in every round, so sync state shows it on the relay's route, as its
+ * {@link PendingSyncRoute.failure} with its details, and apps show it as the
+ * owner's `Error` {@link OwnerSyncStatus}. When the relay rejected or failed a
+ * request, or sent a frame that could not be decoded, the route shows a
+ * {@link ProtocolError}. A {@link ProtocolQuotaError} needs more relay quota,
+ * then {@link Evolu.requestSync}, and a {@link ProtocolVersionError} needs an app
+ * or relay update.
+ *
+ * A received change that was not created with the owner's encryption key, was
+ * altered afterwards, or cannot be decoded by this app version is skipped,
+ * while everything else still syncs. The relay offers it again in every round,
+ * so the route shows it as its `skippedError`: the
+ * {@link DecryptWithXChaCha20Poly1305Error},
+ * {@link ProtocolTimestampMismatchError}, or {@link ProtocolInvalidDataError} of
+ * the first change skipped in a reply, with its details. The owner's status is
+ * `Error` with it too, unless a relay has a failure. Once this database stores
+ * a valid change with that timestamp, for example from another relay, the relay
+ * no longer offers its copy, and the route completes with its next sync, such
+ * as after a reconnect or {@link Evolu.requestSync}, during which no changes
+ * arrive from other relays. If you don't trust that relay, stop using it for
+ * the owner. For owners that use the default transports, such as
+ * {@link Evolu.appOwner} when {@link EvoluConfig.transports} is not empty,
+ * replace the relay there; an empty list stops syncing the app owner and makes
+ * {@link Evolu.useOwner} require explicit transports. For an owner you passed
+ * explicit transports to {@link Evolu.useOwner}, call its {@link UnuseOwner} and
+ * use it again without that relay. Do this wherever the owner is used, such as
+ * in every tab, because the owner syncs through every transport any of its uses
+ * claims. If every route of the owner shows
+ * {@link DecryptWithXChaCha20Poly1305Error} and your code creates or shares the
+ * owner, check the owner's keys.
  *
  * @group Core
  */
 export type EvoluError =
-  | DecryptWithXChaCha20Poly1305Error
-  | OtherBuildRunningError
-  | ProtocolError
-  | StorageQuotaError
-  | UnknownError
-  | UnsupportedDbVersionError;
+  OtherBuildRunningError | UnknownError | UnsupportedDbVersionError;
 
 /**
  * The largest {@link Mutation}, in bytes.
@@ -975,6 +1008,13 @@ export interface EvoluErrorDep {
    * instead; see {@link UnsupportedDbVersionError}. Show that blocking message
    * outside any query-loading boundary, so pending queries do not hide it.
    *
+   * An {@link UnknownError} leaves Evolu in an unknown state, so the app can
+   * only ask the user to close the tab. A failed shared worker closes itself,
+   * so the app opened again starts a new one. Some errors reach every tab, such
+   * as an unexpected failure of the shared worker. An app that forwards this
+   * store to an error tracker from each tab then reports such an error once per
+   * tab.
+   *
    * ### Example
    *
    * ```ts
@@ -988,14 +1028,13 @@ export interface EvoluErrorDep {
    * // 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.";
+   *     case "UnknownError":
+   *       return "Something went wrong. Please close this tab and open the app again.";
    *   }
    * };
    *
@@ -1031,8 +1070,15 @@ 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.
+   * snapshot. It lists every database the shared worker serves, including other
+   * tabs', so an app finds its own by {@link Evolu.name}. Apps show users an
+   * owner's {@link OwnerSyncStatus}, from {@link syncStateToOwnerSyncStatus} or a
+   * framework binding's `useOwnerSyncStatus`; views of each relay use
+   * {@link syncStateToRelaySyncStates}.
+   *
+   * Each snapshot keeps the previous snapshot's object for every part that did
+   * not change, and a snapshot equal to the previous one leaves the store
+   * unchanged, so parts and derived statuses can be compared with `===`.
    *
    * ### Example
    *
@@ -1041,6 +1087,7 @@ export interface SyncStateDep {
    *   assertEqual,
    *   createId,
    *   createStore,
+   *   Millis,
    *   testCreateDeps,
    * } from "@evolu/common";
    * import type {
@@ -1050,7 +1097,7 @@ export interface SyncStateDep {
    *
    * const openRelayLabels = (deps: SyncStateDep): ReadonlyArray<string> =>
    *   (deps.syncState.get()?.transports ?? [])
-   *     .filter(({ readyState }) => readyState === "open")
+   *     .filter(({ connection }) => connection.type === "Open")
    *     .map(({ label }) => label);
    *
    * using syncState = createStore<SyncState | null>(null);
@@ -1060,12 +1107,14 @@ export interface SyncStateDep {
    * syncState.set({
    *   transports: [
    *     {
+   *       type: "WebSocket",
    *       id: createId<"SyncTransport">(deps),
    *       label: "wss://relay.example",
-   *       readyState: "open",
-   *       openedAt: null,
-   *       closedAt: null,
-   *       error: null,
+   *       connection: {
+   *         type: "Open",
+   *         openedAt: Millis.orThrow(1000),
+   *         error: null,
+   *       },
    *     },
    *   ],
    *   tenants: [],
@@ -1155,11 +1204,15 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
         }
         break;
 
-      case "Error":
-        setEvoluError(message.error);
+      case "Error": {
+        // Every build shares this channel, so another build's worker can post
+        // an error type this build does not post, such as an older build's
+        // sync error. That build's own tabs show it, so this tab only logs it.
+        if (message.error.type === "UnknownError") setEvoluError(message.error);
         // Keep typed errors visible in logs as operational failures.
         console.error(message.error);
         break;
+      }
 
       default:
         exhaustiveCheck(message);
@@ -1173,8 +1226,9 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
         break;
 
       case "Error":
-        // Sent to this tab only: its database refused startup, or its worker
-        // still waits for another build.
+        // Sent to this tab only: its database refused startup, a mutation it
+        // made could not be stored, or its worker still waits for another
+        // build.
         setEvoluError(message.error);
         console.error(message.error);
         break;
@@ -1197,7 +1251,15 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
           message.syncStateChannelName,
         );
         syncStateBroadcastChannel.onMessage = (state) => {
-          syncState.set(state);
+          // Every snapshot arrives as a new structured clone, so its unchanged
+          // parts get the previous snapshot's objects back, and an unchanged
+          // snapshot leaves the store as it is.
+          const previous = syncState.get();
+          syncState.set(
+            previous
+              ? shareStructure(previous, state, syncStateItemToKey)
+              : state,
+          );
         };
         // Asking only after listening misses no snapshot.
         sharedWorker.port.postMessage({ type: "RequestSyncState" });
@@ -1235,6 +1297,14 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
   );
 };
 
+// Transports, tenants, owners, and routes come and go, so each is compared
+// with its previous self by its ID: a transport's id, a tenant's name, an
+// owner's ownerId, or a route's transportId. A wrong key only loses sharing.
+const syncStateItemToKey = (item: unknown): unknown =>
+  isPlainObject(item)
+    ? (item.id ?? item.name ?? item.ownerId ?? item.transportId)
+    : undefined;
+
 /**
  * Creates an {@link Evolu} instance from {@link EvoluSchema} and
  * {@link EvoluConfig}.
@@ -1434,6 +1504,14 @@ export const createEvolu =
             break;
           }
 
+          case "OnMutateFailed": {
+            // The tab reports the failure, and these callbacks never run.
+            for (const onCompleteId of message.onCompleteIds) {
+              onMutateCompleteCallbacks.unregister(onCompleteId);
+            }
+            break;
+          }
+
           default:
             exhaustiveCheck(message);
         }

package/src/local-first/Owner.ts

@@ -28,6 +28,15 @@
  * - {@link OwnerEncryptionKey}: the symmetric key that protects the data.
  * - {@link OwnerWriteKey}: the rotatable token that authorizes writes.
  *
+ * Only holders of the encryption key can create an owner's changes. Each change
+ * is encrypted and authenticated together with its timestamp, so a relay, or
+ * anyone who can write to a relay for the owner, can store bytes for the owner
+ * but cannot forge or move a change. A client stores only the changes it can
+ * decrypt, verify, and decode, and syncs only what it stored. It skips any
+ * other change, which sync state shows on the route of the relay that holds it,
+ * and the relay offers it again on each sync until the client stores a valid
+ * change with that timestamp.
+ *
  * @module
  */