@evolu/common 8.10.0 → 8.12.0

package/dist/src/local-first/Db.js

@@ -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
  */
 var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
@@ -56,25 +89,28 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { appendToArray, firstInArray, } from "../Array.js";
-import { assertNonEmptyReadonlyArray, assertNonNullable, assertNotUndefined, } from "../Assert.js";
-import { EncryptionKey, } from "../Crypto.js";
+import { assert, assertNonEmptyReadonlyArray, assertNonNullable, assertNotUndefined, } from "../Assert.js";
+import { EncryptionKey } from "../Crypto.js";
 import { constFalse, constVoid } from "../Function.js";
 import { acquireLeaderLock } from "../LockManager.js";
 import { createMutableRecord, getOwnProp, objectToEntries } from "../Object.js";
-import { ok } from "../Result.js";
+import { err, getOk, ok } from "../Result.js";
 import { booleanToSqliteBoolean, createSqlite, sql, SqliteBoolean, sqliteBooleanToBoolean, sqliteQueryStringToSqliteQuery, SqliteValue, } from "../Sqlite.js";
 import { callback } from "../Task.js";
-import { Millis, millisToDateIso } from "../Time.js";
-import { assertType, Id, IdBytes, idBytesToId, idToIdBytes, onePositiveInt, } from "../Type.js";
+import { millisToDateIso, saturateMillis, } from "../Time.js";
+import { assertType, Id, IdBytes, idBytesToId, idToIdBytes, NonNaNNumber, onePositiveInt, PositiveInt, } from "../Type.js";
 import { ownerIdBytesToOwnerId, ownerIdToOwnerIdBytes } from "./Owner.js";
-import { applyProtocolMessageAsClient, createProtocolMessageForSync, decryptAndDecodeDbChange, encodeAndEncryptDbChange, protocolVersion, SubscriptionFlags, } from "./Protocol.js";
-import { ensureSqliteSchema, getEvoluSqliteSchema, systemColumns, } from "./Schema.js";
+import { applyProtocolMessageAsClient, createProtocolMessageForSync, decryptAndDecodeDbChange, encodeAndEncryptDbChange, SubscriptionFlags, } from "./Protocol.js";
+import { ensureSqliteSchema, isLocalOnlyTable, QuarantineOrigin, QuarantineReason, systemColumns, } from "./Schema.js";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.js";
 import { createBaseSqliteStorage, createBaseSqliteStorageTables, DbChange, getTimestampInsertStrategy, readOwnerUsageOrDefault, updateOwnerUsage, } from "./Storage.js";
-import { createInitialTimestamp, defaultTimestampMaxDrift, receiveTimestamp, sendTimestamp, TimestampBytes, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
+import { createInitialTimestamp, defaultTimestampMaxDrift, isTimestampBeyondMaxDrift, maxCounter, maxNodeId, receiveTimestamp, sendTimestamp, TimestampBytes, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
+/** The database version this code creates and supports; see the module doc. */
+const dbVersion = PositiveInt.orThrow(2);
 /**
- * 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) => async (run) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
@@ -107,46 +143,89 @@ export const startDbWorker = (self) => async (run) => {
             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);
+        const startup = sqlite.transaction(() => {
+            // 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(sql `
+          select "name" from pragma_table_info('evolu_version');
+        `);
+            const versionColumns = new Set(versionColumnRows.map((row) => row.name));
+            let initialClock;
+            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(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);
         });
-        const storage = createClientStorage({ ...dbDeps, clock })({
-            onError: (error) => {
-                consoleEntryOrErrorBroadcastChannel.postMessage({
-                    type: "Error",
-                    error,
-                });
-            },
-        });
+        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(({ resolve }) => {
             port.onMessage = (input) => {
                 if (input.type === "Dispose") {
                     resolve(ok());
                     return;
                 }
-                const { callbackId, request } = input;
+                const { attemptId } = input;
                 const postQueuedResponse = (response) => {
                     port.postMessage({
                         type: "OnQueuedResponse",
-                        callbackId,
+                        attemptId,
                         response,
                     }, response.type === "ForEvolu" && response.message.type === "Export"
                         ? [response.message.file.buffer]
                         : undefined);
                 };
-                if (request.type === "ForSharedWorker") {
-                    if (request.message.type === "ApplySyncMessage") {
+                if ("clock" in input) {
+                    const { clock: inputClock, now } = input;
+                    let committedClock = inputClock;
+                    const context = {
+                        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,
                             }));
@@ -154,6 +233,7 @@ export const startDbWorker = (self) => async (run) => {
                                 type: "ForSharedWorker",
                                 message: {
                                     type: "ApplySyncMessage",
+                                    clock: context.clock.get(),
                                     ownerId: owner.id,
                                     didWriteMessages: storage.didWriteMessages(),
                                     result,
@@ -161,21 +241,41 @@ export const startDbWorker = (self) => async (run) => {
                             });
                             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();
+                    const failedOwnerIds = new Set();
+                    // 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({
                         type: "ForSharedWorker",
                         message: {
                             type: "CreateSyncMessages",
                             protocolMessagesByOwnerId,
+                            failedOwnerIds,
                         },
                     });
                     return;
@@ -200,21 +300,7 @@ export const startDbWorker = (self) => async (run) => {
                             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 () => {
                 port.onMessage = null;
@@ -232,42 +318,105 @@ export const startDbWorker = (self) => async (run) => {
             await result_1;
     }
 };
-const createClock = (deps) => (dbIsInitialized) => {
-    let currentTimestamp;
-    if (dbIsInitialized) {
-        const { rows } = deps.sqlite.exec(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) => (timestamp) => {
+    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 }) => (versionColumns) => {
+    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);
+    const { rows } = sqlite.exec(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 }) => {
+    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);
     }
-    return {
-        get: () => currentTimestamp,
-        save: (timestamp) => {
-            currentTimestamp = timestamp;
-            deps.sqlite.exec(sql.prepared `
-          update evolu_config
-          set "clock" = ${timestampToTimestampBytes(timestamp)};
-        `);
-        },
-    };
 };
 const initializeDb = ({ sqlite }) => (initialClock) => {
     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 `
         create table evolu_config (
@@ -314,7 +463,7 @@ const initializeDb = ({ sqlite }) => (initialClock) => {
         );
       `,
         /**
-         * 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),
@@ -326,6 +475,16 @@ const initializeDb = ({ sqlite }) => (initialClock) => {
          * 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.
@@ -338,6 +497,9 @@ const initializeDb = ({ sqlite }) => (initialClock) => {
           "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;
@@ -346,17 +508,27 @@ const initializeDb = ({ sqlite }) => (initialClock) => {
         sqlite.exec(query);
     }
     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) => {
-    const rows = deps.sqlite.exec(sql `
+    const { rows } = deps.sqlite.exec(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), row.table, row.id, idBytesToId(row.id), row.column, row.value, row.timestamp);
-        deps.sqlite.exec(sql `
+        deps.sqlite.exec(sql.prepared `
       delete from evolu_message_quarantine
       where
         "ownerId" = ${row.ownerId}
@@ -367,7 +539,65 @@ const tryApplyQuarantinedMessages = (deps) => {
     `);
     }
 };
+/**
+ * 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) => (clock) => {
+    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(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) => (table, column, _value) => {
+    // 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 &&
         (systemColumnsWithoutOwnerId.has(column) || schemaColumns.has(column)));
@@ -410,21 +640,21 @@ const applyColumnChange = (deps) => (ownerIdBytes, ownerId, table, idBytes, id,
       on conflict do nothing;
     `);
 };
-const createClientStorage = (deps) => ({ onError, }) => {
+const createClientStorage = (deps) => {
     let encryptionKey = null;
     let didWriteMessages = false;
+    let writeContext;
     const getEncryptionKey = () => {
         assertNonNullable(encryptionKey, "ClientStorage encryption key must be set");
         return encryptionKey;
     };
     return {
         ...deps.baseSqliteStorage,
-        // 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) => {
+        // 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;
         },
         didWriteMessages: () => didWriteMessages,
@@ -441,39 +671,49 @@ const createClientStorage = (deps) => ({ onError, }) => {
             const currentEncryptionKey = getEncryptionKey();
             for (const message of encryptedMessages) {
                 const change = decryptAndDecodeDbChange(message, currentEncryptionKey);
-                if (!change.ok) {
-                    onError(change.error);
-                    return ok();
-                }
+                if (!change.ok)
+                    return err(change.error);
                 messages.push({ timestamp: message.timestamp, change: change.value });
             }
-            let clockTimestamp = deps.clock.get();
+            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 = receiveTimestamp(deps)(clockTimestamp, message.timestamp);
+                const nextTimestamp = receive(clockTimestamp, message.timestamp, now);
                 if (!nextTimestamp.ok) {
-                    onError(nextTimestamp.error);
-                    return ok();
+                    if (nextTimestamp.error.cause === "remote")
+                        continue;
+                    clockTimestamp = nextTimestamp.error.timestamp;
                 }
-                clockTimestamp = nextTimestamp.value;
+                else
+                    clockTimestamp = nextTimestamp.value;
             }
             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(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};
-        `);
+        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);
@@ -510,20 +750,20 @@ const createClientStorage = (deps) => ({ onError, }) => {
         },
     };
 };
-const handleMutation = (deps) => (message) => deps.sqlite.transaction(() => {
+const handleMutation = (deps) => (message, now) => getOk(deps.sqlite.transaction(() => {
     const messagesByOwnerId = new Map();
     let clockTimestamp = deps.clock.get();
-    let clockChanged = false;
     for (const change of message.changes) {
-        if (change.table.startsWith("_")) {
-            applyLocalOnlyChange(deps)(change);
+        if (isLocalOnlyTable(change.table)) {
+            applyLocalOnlyChange(deps)(change, now);
             continue;
         }
-        const nextTimestamp = sendTimestamp(deps)(clockTimestamp);
-        if (!nextTimestamp.ok)
-            return nextTimestamp;
-        clockTimestamp = nextTimestamp.value;
-        clockChanged = true;
+        // 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 = {
             timestamp: clockTimestamp,
@@ -536,17 +776,18 @@ const handleMutation = (deps) => (message) => deps.sqlite.transaction(() => {
             messagesByOwnerId.set(ownerId, [message]);
     }
     for (const [ownerId, messages] of messagesByOwnerId) {
-        applyMessages(deps)(ownerId, messages);
+        applyMessages(deps)(ownerId, messages, QuarantineOrigin.LocalMutation, now);
     }
-    if (clockChanged)
-        deps.clock.save(clockTimestamp);
+    if (messagesByOwnerId.size > 0)
+        saveClock(deps)(clockTimestamp);
     return ok({
         type: "Mutate",
+        clock: clockTimestamp,
         messagesByOwnerId,
         rowsByQuery: loadQueries(deps)(message.subscribedQueries),
     });
-});
-const applyLocalOnlyChange = (deps) => (change) => {
+}));
+const applyLocalOnlyChange = (deps) => (change, now) => {
     if (change.isDelete) {
         deps.sqlite.exec(sql `
         delete from ${sql.identifier(change.table)}
@@ -555,7 +796,7 @@ const applyLocalOnlyChange = (deps) => (change) => {
     }
     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);
             deps.sqlite.exec(sql.prepared `
@@ -568,23 +809,52 @@ const applyLocalOnlyChange = (deps) => (change) => {
         }
     }
 };
-const applyMessages = (deps) => (ownerId, messages) => {
+/**
+ * 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) => (ownerId, messages, origin, now) => {
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+    let wroteNewMessages = false;
     const usage = readOwnerUsageOrDefault(deps)(ownerIdBytes, timestampToTimestampBytes(firstInArray(messages).timestamp));
     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, change.table, idBytes, change.id, column, value, timestampBytes);
             }
             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},
@@ -592,23 +862,28 @@ const applyMessages = (deps) => (ownerId, messages) => {
                 ${change.table},
                 ${idBytes},
                 ${column},
-                ${value}
+                ${value},
+                ${hasDrift
+                    ? QuarantineReason.TimestampDrift
+                    : QuarantineReason.Schema},
+                ${origin},
+                ${now}
               )
             on conflict do nothing;
           `);
             }
         }
-        let strategy;
-        [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(timestampBytes, 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);
+    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);
+    }
+    return wroteNewMessages;
 };
 const dbChangeToColumns = (change, now) => {
     let values = objectToEntries(change.values);