@evolu/common 8.9.0 → 8.11.0

package/src/local-first/Db.ts

@@ -1,6 +1,39 @@
 /**
  * Platform-agnostic Evolu DbWorker.
  *
+ * ### Database version
+ *
+ * Every database records `dbVersion` in `evolu_version`. The version describes
+ * Evolu's internal persisted format: the layout of its system tables and the
+ * meaning of the data stored in them. It is independent of the application
+ * schema, which evolves append-only through {@link ensureSqliteSchema}, and of
+ * the network protocol version, which is checked per message. Many Evolu
+ * releases can share one database version.
+ *
+ * Bump `dbVersion` for any change that older code would misread, not only for
+ * changed SQL. A new quarantine reason, for example, changes what startup may
+ * replay even when its columns are additive. Each bump ships with a migration
+ * from the previous version; fresh databases are created at the latest layout
+ * directly.
+ *
+ * Startup holds the database leader lock, then checks the stored version record
+ * before it reads the clock, ensures the application schema, or replays
+ * quarantine. Databases written before the version record existed hold one
+ * `protocolVersion` row instead; that known legacy layout is converted to
+ * version 1. A newer stored version refuses startup with
+ * {@link UnsupportedDbVersionError}. The refusal returns from the startup
+ * transaction before anything is written and is posted to the SharedWorker; the
+ * worker then exits and releases its resources. The single version row is
+ * created in the same transaction as the other system tables.
+ *
+ * Code released before the version record existed never reads it. It recognizes
+ * an initialized database by the `evolu_version` table alone, so it opens a
+ * newer database and replays all quarantine regardless of reason, applying
+ * drift quarantine at once without advancing the clock. Renaming the table
+ * would make such code fail at startup instead. That was declined: the replay
+ * needs drift quarantine and an earlier release on the same device at once, and
+ * failing would break a rollback to an earlier release outright.
+ *
  * @module
  */
 
@@ -11,21 +44,18 @@ import {
   type NonEmptyReadonlyArray,
 } from "../Array.ts";
 import {
+  assert,
   assertNonEmptyReadonlyArray,
   assertNonNullable,
   assertNotUndefined,
 } from "../Assert.ts";
 import type { ConsoleLevel } from "../Console.ts";
-import {
-  EncryptionKey,
-  type DecryptWithXChaCha20Poly1305Error,
-  type RandomBytesDep,
-} from "../Crypto.ts";
+import { EncryptionKey, type RandomBytesDep } from "../Crypto.ts";
 import { constFalse, constVoid } from "../Function.ts";
 import type { LockManagerDep } from "../LockManager.ts";
 import { acquireLeaderLock } from "../LockManager.ts";
 import { createMutableRecord, getOwnProp, objectToEntries } from "../Object.ts";
-import { ok, type Result } from "../Result.ts";
+import { err, getOk, ok, type Result } from "../Result.ts";
 import type {
   CreateSqliteDriverDep,
   SqliteDep,
@@ -42,7 +72,12 @@ import {
   SqliteValue,
 } from "../Sqlite.ts";
 import { callback, type Run, type Task } from "../Task.ts";
-import { Millis, millisToDateIso, type TimeDep } from "../Time.ts";
+import {
+  millisToDateIso,
+  saturateMillis,
+  type Millis,
+  type TimeDep,
+} from "../Time.ts";
 import {
   assertType,
   type FiniteNumber,
@@ -50,9 +85,12 @@ import {
   IdBytes,
   idBytesToId,
   idToIdBytes,
+  NonNaNNumber,
   onePositiveInt,
+  PositiveInt,
   type ExtractTyped,
   type Name,
+  type Typed,
 } from "../Type.ts";
 import type {
   CreateBroadcastChannelDep,
@@ -68,17 +106,16 @@ import {
   createProtocolMessageForSync,
   decryptAndDecodeDbChange,
   encodeAndEncryptDbChange,
-  protocolVersion,
   SubscriptionFlags,
-  type ProtocolInvalidDataError,
   type ProtocolMessage,
-  type ProtocolTimestampMismatchError,
 } from "./Protocol.ts";
 import type { Query, RowsByQueryMap } from "./Query.ts";
 import type { MutationChange, SqliteSchemaDep } from "./Schema.ts";
 import {
   ensureSqliteSchema,
-  getEvoluSqliteSchema,
+  isLocalOnlyTable,
+  QuarantineOrigin,
+  QuarantineReason,
   systemColumns,
 } from "./Schema.ts";
 import type {
@@ -86,7 +123,7 @@ import type {
   DbWorkerInput,
   DbWorkerOutput,
   DbWorkerQueuedResponse,
-  DbWorkerRequest,
+  EvoluInput,
 } from "./Shared.ts";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
 import {
@@ -101,15 +138,13 @@ import {
   type CrdtMessage,
   type Storage,
 } from "./Storage.ts";
-import type {
-  Timestamp,
-  TimestampCounterOverflowError,
-  TimestampDriftError,
-  TimestampTimeOutOfRangeError,
-} from "./Timestamp.ts";
+import type { Timestamp } from "./Timestamp.ts";
 import {
   createInitialTimestamp,
   defaultTimestampMaxDrift,
+  isTimestampBeyondMaxDrift,
+  maxCounter,
+  maxNodeId,
   receiveTimestamp,
   sendTimestamp,
   TimestampBytes,
@@ -141,9 +176,29 @@ export type DbWorkerDeps = WorkerDeps &
   LockManagerDep &
   CreateSqliteDriverDep;
 
+/** The database version this code creates and supports; see the module doc. */
+const dbVersion = PositiveInt.orThrow(2);
+
+/**
+ * The stored database version is newer than this code supports. Newer code
+ * created or migrated the database, which is left unchanged. This happens when
+ * older code opens a database a newer build migrated, for example an older
+ * build loaded from a cache, or when the app was downgraded after a newer
+ * version migrated the local data. On the web, a refused tab reloads once for
+ * each stored version, so it loads the build the server now serves, and the
+ * error is reported when that build refuses too. Then close all tabs of the
+ * app, which lets a service worker replace a cached older build, or update the
+ * app to a version that supports `storedVersion`.
+ */
+export interface UnsupportedDbVersionError extends Typed<"UnsupportedDbVersionError"> {
+  readonly storedVersion: PositiveInt;
+  readonly supportedVersion: PositiveInt;
+}
+
 /**
- * Starts the platform-agnostic Evolu DbWorker and owns its resources until the
- * worker receives a dispose message or its {@link Run} is aborted.
+ * Starts the platform-agnostic Evolu DbWorker and owns its resources until
+ * startup is refused, the worker receives a dispose message, or its {@link Run}
+ * is aborted.
  */
 export const startDbWorker =
   (self: WorkerSelf<DbWorkerInit>): Task<void, never, DbWorkerDeps> =>
@@ -199,27 +254,60 @@ export const startDbWorker =
       baseSqliteStorage,
       timestampConfig: { maxDrift: defaultTimestampMaxDrift },
     };
-    const currentSchema = getEvoluSqliteSchema(dbDeps)();
-    const dbIsInitialized = "evolu_version" in currentSchema.tables;
-    const clock = createClock(dbDeps)(dbIsInitialized);
-
-    sqlite.transaction(() => {
-      if (!dbIsInitialized) initializeDb(dbDeps)(clock.get());
-      ensureSqliteSchema(dbDeps)(initMessage.sqliteSchema, currentSchema);
-      tryApplyQuarantinedMessages(dbDeps);
-    });
-
-    const storage = createClientStorage({ ...dbDeps, clock })({
-      onError: (error) => {
-        consoleEntryOrErrorBroadcastChannel.postMessage({
-          type: "Error",
-          error,
-        });
+    const startup = sqlite.transaction(
+      (): Result<Timestamp, UnsupportedDbVersionError> => {
+        // Only the version record is read before the version check, because a
+        // newer database can hold schema objects this code cannot read.
+        const { rows: versionColumnRows } = sqlite.exec<{ name: string }>(sql`
+          select "name" from pragma_table_info('evolu_version');
+        `);
+        const versionColumns = new Set(
+          versionColumnRows.map((row) => row.name),
+        );
+        let initialClock: Timestamp;
+        if (versionColumns.size === 0) {
+          initialClock = createInitialTimestamp(dbDeps);
+          initializeDb(dbDeps)(initialClock);
+        } else {
+          const version = ensureDbVersion(dbDeps)(versionColumns);
+          if (!version.ok) return version;
+          const { rows } = sqlite.exec<{ clock: TimestampBytes }>(sql`
+            select "clock" from evolu_config limit 1;
+          `);
+          assertNonEmptyReadonlyArray(rows);
+          initialClock = timestampBytesToTimestamp(firstInArray(rows).clock);
+        }
+        ensureSqliteSchema(dbDeps)(initMessage.sqliteSchema);
+        const released = releaseDriftQuarantine(dbDeps)(initialClock);
+        if (released) {
+          initialClock = released;
+          saveClock(dbDeps)(released);
+        }
+        tryApplyQuarantinedMessages(dbDeps);
+        return ok(initialClock);
       },
-    });
+    );
+    if (!startup.ok) {
+      // Nothing was written. Returning lets the disposer close SQLite and
+      // release the database lock, which the SharedWorker's tenant disposal
+      // waits on. The tab leader lock is unaffected.
+      port.postMessage({
+        type: "LeaderRefused",
+        name: initMessage.name,
+        error: startup.error,
+      });
+      return ok();
+    }
+    const initialClock = startup.value;
+
+    const storage = createClientStorage(dbDeps);
     const dbWorkerRun = disposer.use(run.create({ storage }));
 
-    port.postMessage({ type: "LeaderAcquired", name: initMessage.name });
+    port.postMessage({
+      type: "LeaderAcquired",
+      name: initMessage.name,
+      clock: initialClock,
+    });
 
     await run.ok(
       callback<void>(({ resolve }) => {
@@ -229,14 +317,14 @@ export const startDbWorker =
             return;
           }
 
-          const { callbackId, request } = input;
+          const { attemptId } = input;
           const postQueuedResponse = (
             response: DbWorkerQueuedResponse,
           ): void => {
             port.postMessage(
               {
                 type: "OnQueuedResponse",
-                callbackId,
+                attemptId,
                 response,
               },
               response.type === "ForEvolu" && response.message.type === "Export"
@@ -245,48 +333,77 @@ export const startDbWorker =
             );
           };
 
-          if (request.type === "ForSharedWorker") {
-            if (request.message.type === "ApplySyncMessage") {
+          if ("clock" in input) {
+            const { clock: inputClock, now } = input;
+            let committedClock = inputClock;
+            const context: WriteContext = {
+              now,
+              clock: {
+                get: () => committedClock,
+                set: (timestamp) => {
+                  committedClock = timestamp;
+                },
+              },
+            };
+            const request = input.request;
+            if (request.type === "ForSharedWorker") {
               const { owner, inputMessage } = request.message;
-
               void dbWorkerRun(async (run) => {
-                storage.setRequestContext(owner.encryptionKey);
-
+                storage.setRequestContext(owner.encryptionKey, context);
                 const result = await run.abortable(
                   applyProtocolMessageAsClient(inputMessage, {
                     writeKey: owner.writeKey,
                   }),
                 );
-
                 postQueuedResponse({
                   type: "ForSharedWorker",
                   message: {
                     type: "ApplySyncMessage",
+                    clock: context.clock.get(),
                     ownerId: owner.id,
                     didWriteMessages: storage.didWriteMessages(),
                     result,
                   },
                 });
-
                 return ok();
               });
-              return;
+            } else {
+              postQueuedResponse({
+                type: "ForEvolu",
+                id: request.id,
+                message: handleMutation({
+                  ...dbDeps,
+                  clock: context.clock,
+                })(request.message, now),
+              });
             }
+            return;
+          }
 
+          const request = input.request;
+          if (request.type === "ForSharedWorker") {
             const protocolMessagesByOwnerId = new Map<
               OwnerId,
               ProtocolMessage
             >();
+            const failedOwnerIds = new Set<OwnerId>();
 
+            // An unanswered attempt would block the tenant queue, so a failed
+            // owner is logged and reported instead of thrown.
             for (const owner of request.message.owners) {
               storage.setRequestContext(owner.encryptionKey);
-              protocolMessagesByOwnerId.set(
-                owner.id,
-                createProtocolMessageForSync({
-                  storage,
-                  console: deps.console,
-                })(owner.id, SubscriptionFlags.Subscribe),
-              );
+              try {
+                protocolMessagesByOwnerId.set(
+                  owner.id,
+                  createProtocolMessageForSync({ storage })(
+                    owner.id,
+                    SubscriptionFlags.Subscribe,
+                  ),
+                );
+              } catch (error) {
+                deps.console.error(error);
+                failedOwnerIds.add(owner.id);
+              }
             }
 
             postQueuedResponse({
@@ -294,6 +411,7 @@ export const startDbWorker =
               message: {
                 type: "CreateSyncMessages",
                 protocolMessagesByOwnerId,
+                failedOwnerIds,
               },
             });
             return;
@@ -320,23 +438,7 @@ export const startDbWorker =
                 file: sqlite.export(),
               },
             });
-            return;
           }
-
-          const result = handleMutation({ ...dbDeps, clock })(request.message);
-          if (!result.ok) {
-            consoleEntryOrErrorBroadcastChannel.postMessage({
-              type: "Error",
-              error: result.error,
-            });
-            return;
-          }
-
-          postQueuedResponse({
-            type: "ForEvolu",
-            id: request.id,
-            message: result.value,
-          });
         };
 
         return () => {
@@ -348,64 +450,135 @@ export const startDbWorker =
     return ok();
   };
 
-/**
- * Hybrid Logical Clock. Keeps the current timestamp in memory to avoid frequent
- * SQLite reads.
- */
+/** Clock state owned by one write request; published only after commit. */
 interface Clock {
   readonly get: () => Timestamp;
-  readonly save: (timestamp: Timestamp) => void;
+  readonly set: (timestamp: Timestamp) => void;
 }
 
 interface ClockDep {
   readonly clock: Clock;
 }
 
-const createClock =
-  (deps: RandomBytesDep & SqliteDep) =>
-  (dbIsInitialized: boolean): Clock => {
-    let currentTimestamp: Timestamp;
+interface WriteContext extends ClockDep {
+  readonly now: Millis;
+}
 
-    if (dbIsInitialized) {
-      const { rows } = deps.sqlite.exec<{ clock: TimestampBytes }>(sql`
-        select clock
-        from evolu_config
-        limit 1;
+/**
+ * Persists `timestamp` only when it is greater than the stored clock.
+ *
+ * Requests report their computed clock, which can be older than the stored
+ * clock when replayed after startup release. The SQL guard keeps the stored
+ * clock from moving backwards; the SharedWorker adopts response clocks only
+ * when newer than its session clock.
+ *
+ * Timestamp bytes sort like their timestamps and SQLite compares blobs byte by
+ * byte, so persistence takes one statement even when the clock does not
+ * advance.
+ *
+ * Local-only mutations and sync requests that do not invoke `writeMessages`
+ * skip this. Successfully processed batches in `writeMessages` call this even
+ * when every message is duplicated or quarantined. Duplicate receipts within
+ * the drift limit can advance the clock without storing new messages.
+ */
+const saveClock =
+  (deps: SqliteDep) =>
+  (timestamp: Timestamp): void => {
+    const bytes = timestampToTimestampBytes(timestamp);
+    deps.sqlite.exec(sql.prepared`
+      update evolu_config
+      set "clock" = ${bytes}
+      where "clock" < ${bytes};
+    `);
+  };
+
+/**
+ * Checks the stored database version inside the startup transaction, before any
+ * other read. The legacy layout, one `protocolVersion` row that was always 1,
+ * is converted to database version 1 first. An older database is migrated one
+ * version at a time, and the record is updated in the same transaction, so a
+ * failed migration leaves both data and version unchanged.
+ */
+const ensureDbVersion =
+  ({ sqlite }: SqliteDep) =>
+  (
+    versionColumns: ReadonlySet<string>,
+  ): Result<void, UnsupportedDbVersionError> => {
+    if (!versionColumns.has("dbVersion")) {
+      sqlite.exec(sql`
+        alter table evolu_version
+        rename column "protocolVersion" to "dbVersion";
       `);
-      assertNonEmptyReadonlyArray(rows);
-      currentTimestamp = timestampBytesToTimestamp(firstInArray(rows).clock);
-    } else {
-      currentTimestamp = createInitialTimestamp(deps);
     }
 
-    return {
-      get: () => currentTimestamp,
-
-      save: (timestamp) => {
-        currentTimestamp = timestamp;
-
-        deps.sqlite.exec(sql.prepared`
-          update evolu_config
-          set "clock" = ${timestampToTimestampBytes(timestamp)};
-        `);
-      },
-    };
+    const { rows } = sqlite.exec<{ dbVersion: PositiveInt }>(sql`
+      select "dbVersion" from evolu_version;
+    `);
+    const storedVersion = rows[0].dbVersion;
+    if (storedVersion > dbVersion) {
+      return err({
+        type: "UnsupportedDbVersionError",
+        storedVersion,
+        supportedVersion: dbVersion,
+      });
+    }
+    if (storedVersion < dbVersion) {
+      if (storedVersion < 2) migrateToVersion2({ sqlite });
+      sqlite.exec(sql`update evolu_version set "dbVersion" = ${dbVersion};`);
+    }
+    return ok();
   };
 
+/**
+ * Version 2 records why a message is quarantined, whether this database stamped
+ * or received it, and when, and adds the index that startup release reads. Rows
+ * from version 1 get the defaults: schema quarantine of a received message with
+ * an unknown quarantine time. See {@link QuarantineReason}.
+ */
+const migrateToVersion2 = ({ sqlite }: SqliteDep): void => {
+  for (const query of [
+    sql`
+      alter table evolu_message_quarantine
+      add column "reason" integer not null default ${sql.raw(
+        String(QuarantineReason.Schema),
+      )};
+    `,
+    sql`
+      alter table evolu_message_quarantine
+      add column "origin" integer not null default ${sql.raw(
+        String(QuarantineOrigin.ReceivedMessage),
+      )};
+    `,
+    sql`
+      alter table evolu_message_quarantine
+      add column "quarantinedAt" integer;
+    `,
+    sql`
+      create index evolu_message_quarantine_reason_timestamp on evolu_message_quarantine (
+        "reason",
+        "timestamp"
+      );
+    `,
+  ]) {
+    sqlite.exec(query);
+  }
+};
+
 const initializeDb =
   ({ sqlite }: SqliteDep) =>
   (initialClock: Timestamp): void => {
     for (const query of [
+      // The database version record; see the module documentation.
       sql`
         create table evolu_version (
-          "protocolVersion" integer not null
+          "dbVersion" integer not null
         )
         strict;
       `,
 
       sql`
-        insert into evolu_version ("protocolVersion")
-        values (${protocolVersion});
+        insert into evolu_version ("dbVersion")
+        values (${dbVersion});
       `,
 
       sql`
@@ -458,7 +631,7 @@ const initializeDb =
       `,
 
       /**
-       * Stores messages with unknown schema in a quarantine table.
+       * Stores unapplied messages with their quarantine reason.
        *
        * When a device receives sync messages containing tables or columns that
        * don't exist in its current schema (e.g., from a newer app version),
@@ -470,6 +643,16 @@ const initializeDb =
        * 3. Partial messages work - known columns go to app tables, unknown to
        *    quarantine
        *
+       * Clock-drift quarantine preserves every column of the affected message.
+       * It is released at startup once system time comes within the drift limit
+       * of the message's timestamp; see the Timestamp module.
+       *
+       * Each row records why it was not applied (`reason`), whether this
+       * database stamped the message for a local mutation or received it
+       * (`origin`), and the captured system time of the request that
+       * quarantined it (`quarantinedAt`). Quarantine is not reported as an
+       * error; applications watch this table through queries.
+       *
        * The `union all` query in `readDbChange` combines `evolu_history` and
        * this table, ensuring all data (known and unknown) is included when
        * syncing to other devices.
@@ -482,6 +665,13 @@ const initializeDb =
           "id" blob not null,
           "column" text not null,
           "value" any,
+          "reason" integer not null default ${sql.raw(
+            String(QuarantineReason.Schema),
+          )},
+          "origin" integer not null default ${sql.raw(
+            String(QuarantineOrigin.ReceivedMessage),
+          )},
+          "quarantinedAt" integer,
           primary key ("ownerId", "timestamp", "table", "id", "column")
         )
         strict;
@@ -491,26 +681,36 @@ const initializeDb =
     }
 
     createBaseSqliteStorageTables({ sqlite });
+
+    // Startup release reads drift quarantine by reason and timestamp. Created
+    // last, as the migration creates it, so Evolu's own indexes are listed in one
+    // order in fresh and migrated databases.
+    sqlite.exec(sql`
+      create index evolu_message_quarantine_reason_timestamp on evolu_message_quarantine (
+        "reason",
+        "timestamp"
+      );
+    `);
   };
 
 const tryApplyQuarantinedMessages = (
   deps: SqliteDep & SqliteSchemaDep,
 ): void => {
-  const rows = deps.sqlite.exec<{
-    readonly ownerId: OwnerIdBytes;
-    readonly timestamp: TimestampBytes;
-    readonly table: string;
-    readonly id: IdBytes;
-    readonly column: string;
-    readonly value: SqliteValue;
+  const { rows } = deps.sqlite.exec<{
+    ownerId: OwnerIdBytes;
+    timestamp: TimestampBytes;
+    table: string;
+    id: IdBytes;
+    column: string;
+    value: SqliteValue;
   }>(sql`
     select "ownerId", "timestamp", "table", "id", "column", "value"
-    from evolu_message_quarantine;
+    from evolu_message_quarantine
+    where "reason" = ${QuarantineReason.Schema};
   `);
 
-  for (const row of rows.rows) {
+  for (const row of rows) {
     if (!validateColumnValue(deps)(row.table, row.column, row.value)) continue;
-
     applyColumnChange(deps)(
       row.ownerId,
       ownerIdBytesToOwnerId(row.ownerId),
@@ -522,7 +722,7 @@ const tryApplyQuarantinedMessages = (
       row.timestamp,
     );
 
-    deps.sqlite.exec(sql`
+    deps.sqlite.exec(sql.prepared`
       delete from evolu_message_quarantine
       where
         "ownerId" = ${row.ownerId}
@@ -534,9 +734,73 @@ const tryApplyQuarantinedMessages = (
   }
 };
 
+/**
+ * Moves drift quarantine within the drift limit to schema quarantine for
+ * application. Advances `clock` once per distinct timestamp in timestamp order,
+ * using one captured system time, so later local changes sort after released
+ * messages. Only timestamps within the drift limit are loaded. Returns the
+ * advanced clock, or `null` when nothing was released. Runs inside the startup
+ * transaction, before saving the clock and applying schema quarantine, so the
+ * SharedWorker learns the clock only after release commits.
+ */
+const releaseDriftQuarantine =
+  (deps: SqliteDep & TimeDep & TimestampConfigDep) =>
+  (clock: Timestamp): Timestamp | null => {
+    const now = deps.time.now();
+    // Milliseconds are integers; floor the allowance before adding it so a
+    // fractional allowance cannot round up near the timestamp range ceiling.
+    const maxReleaseMillis = now + Math.floor(deps.timestampConfig.maxDrift);
+    assertType(NonNaNNumber, maxReleaseMillis);
+    const bound = timestampToTimestampBytes({
+      millis: saturateMillis(maxReleaseMillis),
+      counter: maxCounter,
+      nodeId: maxNodeId,
+    });
+    const { rows } = deps.sqlite.exec<{ timestamp: TimestampBytes }>(sql`
+      select distinct "timestamp"
+      from evolu_message_quarantine
+      where
+        "reason" = ${QuarantineReason.TimestampDrift}
+        and "timestamp" <= ${bound}
+      order by "timestamp";
+    `);
+    if (rows.length === 0) return null;
+
+    const receive = receiveTimestamp(deps);
+    let nextClock = clock;
+    for (const { timestamp } of rows) {
+      const remote = timestampBytesToTimestamp(timestamp);
+      const next = receive(nextClock, remote, now);
+      if (next.ok) {
+        nextClock = next.value;
+      } else {
+        assert(
+          next.error.cause === "local",
+          "The query bound excludes remote drift at the captured time.",
+        );
+        nextClock = next.error.timestamp;
+      }
+    }
+
+    // Drift checks passed; mark these rows for the next schema pass.
+    deps.sqlite.exec(sql`
+      update evolu_message_quarantine
+      set "reason" = ${QuarantineReason.Schema}
+      where
+        "reason" = ${QuarantineReason.TimestampDrift}
+        and "timestamp" <= ${bound};
+    `);
+
+    return nextClock;
+  };
+
 const validateColumnValue =
   (deps: SqliteSchemaDep) =>
   (table: string, column: string, _value: SqliteValue): boolean => {
+    // Local-only tables never sync, so a received change to one comes from
+    // non-standard code. It stays in quarantine, stored for sync but never
+    // applied.
+    if (isLocalOnlyTable(table)) return false;
     const schemaColumns = getOwnProp(deps.sqliteSchema.tables, table);
     return (
       schemaColumns != null &&
@@ -604,237 +868,231 @@ const applyColumnChange =
  * implementation, and switch owner encryption keys between requests.
  */
 interface ClientStorage extends Storage, BaseSqliteStorage {
-  readonly setRequestContext: (encryptionKey: EncryptionKey) => void;
+  readonly setRequestContext: (
+    encryptionKey: EncryptionKey,
+    writeContext?: WriteContext,
+  ) => void;
   readonly didWriteMessages: () => boolean;
 }
 
-const createClientStorage =
-  (
-    deps: BaseSqliteStorageDep &
-      ClockDep &
-      SqliteSchemaDep &
-      RandomBytesDep &
-      SqliteDep &
-      TimeDep &
-      TimestampConfigDep,
-  ) =>
-  ({
-    onError,
-  }: {
-    onError: (
-      error:
-        | ProtocolInvalidDataError
-        | ProtocolTimestampMismatchError
-        | DecryptWithXChaCha20Poly1305Error
-        | TimestampCounterOverflowError
-        | TimestampDriftError
-        | TimestampTimeOutOfRangeError,
-    ) => void;
-  }): ClientStorage => {
-    let encryptionKey: EncryptionKey | null = null;
-    let didWriteMessages = false;
-
-    const getEncryptionKey = (): EncryptionKey => {
-      assertNonNullable(
-        encryptionKey,
-        "ClientStorage encryption key must be set",
-      );
-      return encryptionKey;
-    };
-
-    return {
-      ...deps.baseSqliteStorage,
+const createClientStorage = (
+  deps: BaseSqliteStorageDep &
+    RandomBytesDep &
+    SqliteDep &
+    SqliteSchemaDep &
+    TimestampConfigDep,
+): ClientStorage => {
+  let encryptionKey: EncryptionKey | null = null;
+  let didWriteMessages = false;
+  let writeContext: WriteContext | undefined;
+
+  const getEncryptionKey = (): EncryptionKey => {
+    assertNonNullable(
+      encryptionKey,
+      "ClientStorage encryption key must be set",
+    );
+    return encryptionKey;
+  };
 
-      // DEV: ClientStorage was designed when Storage and Sync lived in the
-      // same file.
-      // This is safe because the worker handles one message at a time. We will
-      // refactor it later, we will probably have to change Protocol API.
-      setRequestContext: (nextEncryptionKey) => {
-        encryptionKey = nextEncryptionKey;
-        didWriteMessages = false;
-      },
+  return {
+    ...deps.baseSqliteStorage,
 
-      didWriteMessages: () => didWriteMessages,
+    // SharedWorker waits for the response before dispatching another request,
+    // so asynchronous sync processing cannot overlap this request context.
+    setRequestContext: (nextEncryptionKey, nextWriteContext) => {
+      encryptionKey = nextEncryptionKey;
+      writeContext = nextWriteContext;
+      didWriteMessages = false;
+    },
 
-      // Not implemented yet.
-      validateWriteKey: constFalse,
-      setWriteKey: constVoid,
+    didWriteMessages: () => didWriteMessages,
 
-      writeMessages: (ownerIdBytes, encryptedMessages) => () => {
-        // TODO: Add quota checking for collaborative scenarios.
-        // When receiving messages from other owners via relay broadcast,
-        // check if this owner is within quota before accepting the data.
-        // This prevents an owner from exceeding storage limits when receiving
-        // data shared by other collaborators.
+    // Not implemented yet.
+    validateWriteKey: constFalse,
+    setWriteKey: constVoid,
 
-        const messages: Array<CrdtMessage> = [];
-        const currentEncryptionKey = getEncryptionKey();
+    writeMessages: (ownerIdBytes, encryptedMessages) => () => {
+      // TODO: Add quota checking for collaborative scenarios.
+      // When receiving messages from other owners via relay broadcast,
+      // check if this owner is within quota before accepting the data.
+      // This prevents an owner from exceeding storage limits when receiving
+      // data shared by other collaborators.
 
-        for (const message of encryptedMessages) {
-          const change = decryptAndDecodeDbChange(
-            message,
-            currentEncryptionKey,
-          );
-          if (!change.ok) {
-            onError(change.error);
-            return ok();
-          }
-          messages.push({ timestamp: message.timestamp, change: change.value });
-        }
+      const messages: Array<CrdtMessage> = [];
+      const currentEncryptionKey = getEncryptionKey();
 
-        let clockTimestamp = deps.clock.get();
+      for (const message of encryptedMessages) {
+        const change = decryptAndDecodeDbChange(message, currentEncryptionKey);
+        if (!change.ok) return err(change.error);
+        messages.push({ timestamp: message.timestamp, change: change.value });
+      }
 
-        for (const message of messages) {
-          const nextTimestamp = receiveTimestamp(deps)(
-            clockTimestamp,
-            message.timestamp,
-          );
-          if (!nextTimestamp.ok) {
-            onError(nextTimestamp.error);
-            return ok();
-          }
-          clockTimestamp = nextTimestamp.value;
-        }
+      assertNonNullable(writeContext);
+      const { clock, now } = writeContext;
+      let clockTimestamp = clock.get();
+      const receive = receiveTimestamp(deps);
+
+      // The clock is computed over every message, duplicates included, so a
+      // retry with the same inputs reports the same clock. Writes for
+      // timestamps already in the owner's set are skipped by applyMessages.
+      for (const message of messages) {
+        const nextTimestamp = receive(clockTimestamp, message.timestamp, now);
+        if (!nextTimestamp.ok) {
+          if (nextTimestamp.error.cause === "remote") continue;
+          clockTimestamp = nextTimestamp.error.timestamp;
+        } else clockTimestamp = nextTimestamp.value;
+      }
 
-        assertNonEmptyReadonlyArray(messages);
+      assertNonEmptyReadonlyArray(messages);
 
-        return deps.sqlite.transaction(() => {
-          applyMessages(deps)(ownerIdBytesToOwnerId(ownerIdBytes), messages);
-          deps.clock.save(clockTimestamp);
-          didWriteMessages = true;
-          return ok();
-        });
-      },
+      let wroteNewMessages = false;
+      deps.sqlite.transaction(() => {
+        wroteNewMessages = applyMessages(deps)(
+          ownerIdBytesToOwnerId(ownerIdBytes),
+          messages,
+          QuarantineOrigin.ReceivedMessage,
+          now,
+        );
+        saveClock(deps)(clockTimestamp);
+      });
+      clock.set(clockTimestamp);
+      // A batch of duplicates changes no table, so queries need no refresh.
+      if (wroteNewMessages) didWriteMessages = true;
+      return ok();
+    },
 
-      readDbChange: (ownerId, timestamp) => {
-        const result = deps.sqlite.exec<{
-          readonly table: string;
-          readonly id: IdBytes;
-          readonly column: string;
-          readonly value: SqliteValue;
-        }>(sql`
-          select "table", "id", "column", "value"
-          from evolu_history
-          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp}
-          union all
-          select "table", "id", "column", "value"
-          from evolu_message_quarantine
-          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
-        `);
+    readDbChange: (ownerId, timestamp) => {
+      const result = deps.sqlite.exec<{
+        readonly table: string;
+        readonly id: IdBytes;
+        readonly column: string;
+        readonly value: SqliteValue;
+      }>(sql`
+        select "table", "id", "column", "value"
+        from evolu_history
+        where "ownerId" = ${ownerId} and "timestamp" = ${timestamp}
+        union all
+        select "table", "id", "column", "value"
+        from evolu_message_quarantine
+        where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
+      `);
 
-        const { rows } = result;
-        assertNonEmptyReadonlyArray(rows, "Every timestamp must have rows");
-        const firstRow = firstInArray(rows);
-
-        const values = createMutableRecord<string, SqliteValue>();
-        let isInsert: DbChange["isInsert"] = false;
-        let isDelete: DbChange["isDelete"] = null;
-
-        for (const r of rows) {
-          switch (r.column) {
-            case "createdAt":
-              isInsert = true;
-              break;
-            case "updatedAt":
-              isInsert = false;
-              break;
-            case "isDeleted":
-              assertType(SqliteBoolean, r.value);
-              isDelete = sqliteBooleanToBoolean(r.value);
-              break;
-            default:
-              values[r.column] = r.value;
-          }
+      const { rows } = result;
+      assertNonEmptyReadonlyArray(rows, "Every timestamp must have rows");
+      const firstRow = firstInArray(rows);
+
+      const values = createMutableRecord<string, SqliteValue>();
+      let isInsert: DbChange["isInsert"] = false;
+      let isDelete: DbChange["isDelete"] = null;
+
+      for (const r of rows) {
+        switch (r.column) {
+          case "createdAt":
+            isInsert = true;
+            break;
+          case "updatedAt":
+            isInsert = false;
+            break;
+          case "isDeleted":
+            assertType(SqliteBoolean, r.value);
+            isDelete = sqliteBooleanToBoolean(r.value);
+            break;
+          default:
+            values[r.column] = r.value;
         }
+      }
 
-        const message: CrdtMessage = {
-          timestamp: timestampBytesToTimestamp(timestamp),
-          change: DbChange.orThrow({
-            table: firstRow.table,
-            id: idBytesToId(firstRow.id),
-            values,
-            isInsert,
-            isDelete,
-          }),
-        };
-
-        return encodeAndEncryptDbChange(deps)(message, getEncryptionKey());
-      },
-    };
+      const message: CrdtMessage = {
+        timestamp: timestampBytesToTimestamp(timestamp),
+        change: DbChange.orThrow({
+          table: firstRow.table,
+          id: idBytesToId(firstRow.id),
+          values,
+          isInsert,
+          isDelete,
+        }),
+      };
+
+      return encodeAndEncryptDbChange(deps)(message, getEncryptionKey());
+    },
   };
+};
 
 const handleMutation =
   (
     deps: BaseSqliteStorageDep &
       ClockDep &
-      SqliteSchemaDep &
-      RandomBytesDep &
       SqliteDep &
-      TimeDep &
+      SqliteSchemaDep &
       TimestampConfigDep,
   ) =>
   (
-    message: ExtractTyped<
-      ExtractTyped<DbWorkerRequest, "ForEvolu">["message"],
-      "Mutate"
-    >,
-  ): Result<
-    {
-      readonly type: "Mutate";
-      readonly messagesByOwnerId: ReadonlyMap<
-        OwnerId,
-        NonEmptyReadonlyArray<CrdtMessage>
-      >;
-      readonly rowsByQuery: RowsByQueryMap;
-    },
-    | TimestampDriftError
-    | TimestampCounterOverflowError
-    | TimestampTimeOutOfRangeError
-  > =>
-    deps.sqlite.transaction(() => {
-      const messagesByOwnerId = new Map<OwnerId, NonEmptyArray<CrdtMessage>>();
-      let clockTimestamp = deps.clock.get();
-      let clockChanged = false;
-
-      for (const change of message.changes) {
-        if (change.table.startsWith("_")) {
-          applyLocalOnlyChange(deps)(change);
-          continue;
-        }
-
-        const nextTimestamp = sendTimestamp(deps)(clockTimestamp);
-        if (!nextTimestamp.ok) return nextTimestamp;
+    message: ExtractTyped<EvoluInput, "Mutate">,
+    now: Millis,
+  ): {
+    readonly type: "Mutate";
+    readonly clock: Timestamp;
+    readonly messagesByOwnerId: ReadonlyMap<
+      OwnerId,
+      NonEmptyReadonlyArray<CrdtMessage>
+    >;
+    readonly rowsByQuery: RowsByQueryMap;
+  } =>
+    getOk(
+      deps.sqlite.transaction(() => {
+        const messagesByOwnerId = new Map<
+          OwnerId,
+          NonEmptyArray<CrdtMessage>
+        >();
+        let clockTimestamp = deps.clock.get();
 
-        clockTimestamp = nextTimestamp.value;
-        clockChanged = true;
+        for (const change of message.changes) {
+          if (isLocalOnlyTable(change.table)) {
+            applyLocalOnlyChange(deps)(change, now);
+            continue;
+          }
 
-        const { ownerId, ...dbChange } = change;
-        const message: CrdtMessage = {
-          timestamp: clockTimestamp,
-          change: dbChange,
-        };
+          // A drifted change still receives the next timestamp; applyMessages
+          // stores it in quarantine instead of its table.
+          const nextTimestamp = sendTimestamp(deps)(clockTimestamp, now);
+          clockTimestamp = nextTimestamp.ok
+            ? nextTimestamp.value
+            : nextTimestamp.error.timestamp;
+
+          const { ownerId, ...dbChange } = change;
+          const message: CrdtMessage = {
+            timestamp: clockTimestamp,
+            change: dbChange,
+          };
 
-        const messages = messagesByOwnerId.get(ownerId);
-        if (messages) messages.push(message);
-        else messagesByOwnerId.set(ownerId, [message]);
-      }
+          const messages = messagesByOwnerId.get(ownerId);
+          if (messages) messages.push(message);
+          else messagesByOwnerId.set(ownerId, [message]);
+        }
 
-      for (const [ownerId, messages] of messagesByOwnerId) {
-        applyMessages(deps)(ownerId, messages);
-      }
+        for (const [ownerId, messages] of messagesByOwnerId) {
+          applyMessages(deps)(
+            ownerId,
+            messages,
+            QuarantineOrigin.LocalMutation,
+            now,
+          );
+        }
 
-      if (clockChanged) deps.clock.save(clockTimestamp);
+        if (messagesByOwnerId.size > 0) saveClock(deps)(clockTimestamp);
 
-      return ok({
-        type: "Mutate",
-        messagesByOwnerId,
-        rowsByQuery: loadQueries(deps)(message.subscribedQueries),
-      });
-    });
+        return ok({
+          type: "Mutate",
+          clock: clockTimestamp,
+          messagesByOwnerId,
+          rowsByQuery: loadQueries(deps)(message.subscribedQueries),
+        });
+      }),
+    );
 
 const applyLocalOnlyChange =
-  (deps: SqliteDep & TimeDep) =>
-  (change: MutationChange): void => {
+  (deps: SqliteDep) =>
+  (change: MutationChange, now: Millis): void => {
     if (change.isDelete) {
       deps.sqlite.exec(sql`
         delete from ${sql.identifier(change.table)}
@@ -842,7 +1100,7 @@ const applyLocalOnlyChange =
       `);
     } else {
       const ownerId = change.ownerId;
-      const columns = dbChangeToColumns(change, deps.time.now());
+      const columns = dbChangeToColumns(change, now);
 
       for (const [column, value] of columns) {
         assertNotUndefined(value);
@@ -857,10 +1115,28 @@ const applyLocalOnlyChange =
     }
   };
 
+/**
+ * Stores messages for an owner and applies them to their tables. Drifted
+ * messages and columns the schema does not define go to quarantine instead.
+ * Uses the request's captured time to classify drift, matching timestamp
+ * generation. Returns whether any message was new; the rest were stored
+ * before.
+ */
 const applyMessages =
-  (deps: BaseSqliteStorageDep & ClockDep & SqliteSchemaDep & SqliteDep) =>
-  (ownerId: OwnerId, messages: NonEmptyReadonlyArray<CrdtMessage>): void => {
+  (
+    deps: BaseSqliteStorageDep &
+      SqliteDep &
+      SqliteSchemaDep &
+      TimestampConfigDep,
+  ) =>
+  (
+    ownerId: OwnerId,
+    messages: NonEmptyReadonlyArray<CrdtMessage>,
+    origin: QuarantineOrigin,
+    now: Millis,
+  ): boolean => {
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+    let wroteNewMessages = false;
 
     const usage = readOwnerUsageOrDefault(deps)(
       ownerIdBytes,
@@ -870,13 +1146,36 @@ const applyMessages =
     let { firstTimestamp, lastTimestamp } = usage;
 
     for (const { timestamp, change } of messages) {
+      const timestampBytes = timestampToTimestampBytes(timestamp);
+
+      let strategy;
+      [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(
+        timestampBytes,
+        firstTimestamp,
+        lastTimestamp,
+      );
+
+      // A timestamp already in the set was applied or quarantined before.
+      // Skipping it preserves that decision and makes duplicate delivery and
+      // retries idempotent without a separate lookup.
+      const isNew = deps.baseSqliteStorage.insertTimestamp(
+        ownerIdBytes,
+        timestampBytes,
+        strategy,
+      );
+      if (!isNew) continue;
+      wroteNewMessages = true;
+
+      const hasDrift = isTimestampBeyondMaxDrift(deps)(timestamp.millis, now);
       const columns = dbChangeToColumns(change, timestamp.millis);
       const idBytes = idToIdBytes(change.id);
-      const timestampBytes = timestampToTimestampBytes(timestamp);
 
       for (const [column, value] of columns) {
         assertNotUndefined(value);
-        if (validateColumnValue(deps)(change.table, column, value)) {
+        if (
+          !hasDrift &&
+          validateColumnValue(deps)(change.table, column, value)
+        ) {
           applyColumnChange(deps)(
             ownerIdBytes,
             ownerId,
@@ -890,7 +1189,17 @@ const applyMessages =
         } else {
           deps.sqlite.exec(sql.prepared`
             insert into evolu_message_quarantine
-              ("ownerId", "timestamp", "table", "id", "column", "value")
+              (
+                "ownerId",
+                "timestamp",
+                "table",
+                "id",
+                "column",
+                "value",
+                "reason",
+                "origin",
+                "quarantinedAt"
+              )
             values
               (
                 ${ownerIdBytes},
@@ -898,38 +1207,34 @@ const applyMessages =
                 ${change.table},
                 ${idBytes},
                 ${column},
-                ${value}
+                ${value},
+                ${hasDrift
+                  ? QuarantineReason.TimestampDrift
+                  : QuarantineReason.Schema},
+                ${origin},
+                ${now}
               )
             on conflict do nothing;
           `);
         }
       }
+    }
 
-      let strategy;
-      [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(
-        timestampBytes,
+    if (wroteNewMessages) {
+      /**
+       * TODO: Implement proper storedBytes tracking for client using received
+       * and sent encrypted message sizes.
+       */
+      updateOwnerUsage(deps)(
+        ownerIdBytes,
+        // Placeholder until proper tracking implemented
+        onePositiveInt,
         firstTimestamp,
         lastTimestamp,
       );
-
-      deps.baseSqliteStorage.insertTimestamp(
-        ownerIdBytes,
-        timestampBytes,
-        strategy,
-      );
     }
 
-    /**
-     * TODO: Implement proper storedBytes tracking for client using received and
-     * sent encrypted message sizes.
-     */
-    updateOwnerUsage(deps)(
-      ownerIdBytes,
-      // Placeholder until proper tracking implemented
-      onePositiveInt,
-      firstTimestamp,
-      lastTimestamp,
-    );
+    return wroteNewMessages;
   };
 
 const dbChangeToColumns = (change: DbChange, now: Millis) => {