@evolu/common 8.17.0 → 8.19.0

package/src/Bytes.test.ts

@@ -1,10 +1,15 @@
+import * as fc from "fast-check";
 import { describe, it, mock } from "node:test";
+import { setFlagsFromString } from "node:v8";
+import { runInNewContext } from "node:vm";
 import {
+  assert,
   assertEqual,
   assertEqualBytes,
   assertErr,
   assertFalse,
   assertInstanceOf,
+  assertNonNullable,
   assertOk,
   assertSame,
   assertThrowsInstanceOf,
@@ -95,6 +100,23 @@ describe("BufferError", () => {
     assertEqual(error.name, "BufferError");
     assertEqual(error.message, "test error");
   });
+
+  it("constructs without Error.captureStackTrace", () => {
+    const descriptor = globalThis.Object.getOwnPropertyDescriptor(
+      Error,
+      "captureStackTrace",
+    );
+    assertNonNullable(descriptor);
+    Reflect.deleteProperty(Error, "captureStackTrace");
+    try {
+      const error = new BufferError("x");
+      assertInstanceOf(error, BufferError);
+      assertEqual(error.message, "x");
+      assertThrowsInstanceOf(() => decodeJson([0xc1]), BufferError);
+    } finally {
+      globalThis.Object.defineProperty(Error, "captureStackTrace", descriptor);
+    }
+  });
 });
 
 describe("concatByteArrays", () => {
@@ -279,6 +301,16 @@ describe("Buffer", () => {
     assertEqual(buffer.getLength(), 2);
     assertEqualBytes(buffer.unwrap(), [6, 7]);
   });
+
+  it("has readonly members", () => {
+    const buffer = createBuffer();
+    const { shift } = buffer;
+
+    // @ts-expect-error Cannot assign to 'shift' because it is a read-only property.
+    buffer.shift = shift;
+
+    assertSame(buffer.shift, shift);
+  });
 });
 
 describe("number encoding", () => {
@@ -482,6 +514,31 @@ describe("string encoding", () => {
     );
     assertEqual(decodeString(buffer), value);
   });
+
+  // Unlike the JSON codec, the string codec keeps the wire valid UTF-8, because
+  // deployed decoders read WTF-8 as three U+FFFD per lone surrogate.
+  it("replaces a lone surrogate with U+FFFD", () => {
+    const buffer = createBuffer();
+    encodeString(buffer, "a\uD800b");
+
+    assertEqualBytes(buffer.unwrap(), [5, 97, 0xef, 0xbf, 0xbd, 98]);
+    assertSame(decodeString(buffer), "a�b");
+  });
+
+  it("decodes invalid UTF-8 as U+FFFD", () => {
+    assertSame(
+      decodeString(createBuffer([5, 97, 0xed, 0xa0, 0x80, 98])),
+      "a���b",
+    );
+  });
+
+  it("keeps a byte order mark", () => {
+    for (const value of ["\uFEFFabc", "\uFEFF", "a\uFEFFb"]) {
+      const buffer = createBuffer();
+      encodeString(buffer, value);
+      assertSame(decodeString(buffer), value);
+    }
+  });
 });
 
 describe("run-length encoding", () => {
@@ -574,6 +631,140 @@ describe("run-length encoding", () => {
   });
 });
 
+describe("run-length encoder checkpoint", () => {
+  const setupEncoder = (values: ReadonlyArray<number> = []) => {
+    const encoder =
+      createRunLengthEncoder<NonNegativeInt>(encodeNonNegativeInt);
+    for (const value of values) encoder.add(NonNegativeInt.orThrow(value));
+    return encoder;
+  };
+
+  const decodeEncoder = (
+    encoder: ReturnType<typeof setupEncoder>,
+    length: number,
+  ) => {
+    const buffer = createBuffer(encoder.unwrap());
+    const values = decodeRle(buffer, NonNegativeInt.orThrow(length), () =>
+      decodeNonNegativeInt(buffer),
+    );
+    assertSame(buffer.getLength(), 0);
+    return values;
+  };
+
+  it("restores a run rewritten in place", () => {
+    const encoder = setupEncoder([7, 5]);
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [7, 1, 5, 3]);
+
+    restore();
+    assertEqualBytes(encoder.unwrap(), [7, 1, 5, 1]);
+
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), setupEncoder([7, 5, 5]).unwrap());
+    assertEqual(decodeEncoder(encoder, 3), [7, 5, 5]);
+  });
+
+  it("restores a run length across the 127/128 varint boundary", () => {
+    const run127 = Array.from({ length: 127 }, () => 5);
+    const encoder = setupEncoder(run127);
+    const restoreAt127 = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 128, 1]);
+    const restoreAt128 = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 129, 1]);
+
+    restoreAt128();
+    assertEqualBytes(encoder.unwrap(), [5, 128, 1]);
+
+    restoreAt127();
+    assertEqualBytes(encoder.unwrap(), [5, 127]);
+    assertEqual(encoder.getLength(), 2);
+
+    encoder.add(NonNegativeInt.orThrow(6));
+    assertEqualBytes(encoder.unwrap(), [5, 127, 6, 1]);
+    assertEqual(decodeEncoder(encoder, 128), [...run127, 6]);
+  });
+
+  it("restores the previous value after a different value", () => {
+    const encoder = setupEncoder([5]);
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(7));
+    encoder.add(NonNegativeInt.orThrow(7));
+    assertEqualBytes(encoder.unwrap(), [5, 1, 7, 2]);
+
+    restore();
+    assertEqualBytes(encoder.unwrap(), [5, 1]);
+
+    // Without the previous value, the next 5 would start a new run.
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 2]);
+  });
+
+  it("restores an empty encoder", () => {
+    const encoder = setupEncoder();
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+
+    restore();
+    assertEqual(encoder.getLength(), 0);
+    assertEqualBytes(encoder.unwrap(), []);
+
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 1]);
+  });
+
+  it("encodes only the committed values after restores", () => {
+    fc.assert(
+      fc.property(
+        fc.array(
+          fc.oneof(
+            fc.record({
+              value: fc.constantFrom(0, 5, 300),
+              count: fc.integer({ min: 1, max: 200 }),
+            }),
+            fc.constant("checkpoint" as const),
+            fc.constant("restore" as const),
+          ),
+          { maxLength: 30 },
+        ),
+        (operations) => {
+          const encoder = setupEncoder();
+          const committed: Array<number> = [];
+          const checkpoints: Array<{
+            readonly restore: () => void;
+            readonly length: number;
+          }> = [];
+
+          for (const operation of operations) {
+            if (operation === "checkpoint") {
+              checkpoints.push({
+                restore: encoder.checkpoint(),
+                length: committed.length,
+              });
+            } else if (operation === "restore") {
+              const checkpoint = checkpoints.pop();
+              if (!checkpoint) continue;
+              checkpoint.restore();
+              committed.length = checkpoint.length;
+            } else {
+              for (let i = 0; i < operation.count; i++) {
+                encoder.add(NonNegativeInt.orThrow(operation.value));
+                committed.push(operation.value);
+              }
+            }
+          }
+
+          assertEqualBytes(encoder.unwrap(), setupEncoder(committed).unwrap());
+          assertEqual(decodeEncoder(encoder, committed.length), committed);
+        },
+      ),
+    );
+  });
+});
+
 describe("JSON binary codec", () => {
   it("matches fixed msgpackr 2.0.5 fixtures", () => {
     const fixtures: ReadonlyArray<readonly [unknown, ReadonlyArray<number>]> = [
@@ -1164,6 +1355,27 @@ describe("JSON binary codec", () => {
     }
   });
 
+  it("releases an oversized encoder arena", () => {
+    setFlagsFromString("--expose-gc");
+    const gc = runInNewContext("gc") as () => void;
+    gc();
+    gc();
+    const before = process.memoryUsage().arrayBuffers;
+    const buffer = createBuffer();
+
+    // A string reserves 3 bytes per UTF-16 code unit, so this one grows the
+    // module-scope arena to 6 MB.
+    encodeJsonValue(buffer, JsonValue.orThrow("x".repeat(2_000_000)));
+    gc();
+    gc();
+
+    const retained =
+      process.memoryUsage().arrayBuffers - before - buffer.getCapacity();
+    assert(retained < 1_000_000, "Expected the arena to be released.", {
+      actual: retained,
+    });
+  });
+
   it("converts unexpected decoder errors to BufferError", () => {
     const errorBuffer = {
       ...createBuffer([0xc0]),

package/src/Bytes.ts

@@ -103,16 +103,11 @@ export const concatByteArrays = (
   return result;
 };
 
-/**
- * Custom error for {@link Buffer}-related failures like premature end of data.
- * Provides better stack traces for debugging binary protocol issues.
- */
+/** Custom error for {@link Buffer}-related failures like premature end of data. */
 export class BufferError extends Error {
   constructor(message: string) {
     super(message);
     this.name = this.constructor.name;
-
-    Error.captureStackTrace(this, this.constructor);
   }
 }
 
@@ -173,34 +168,34 @@ export class BufferError extends Error {
  */
 export interface Buffer {
   /** Returns the current capacity of the buffer. */
-  getCapacity: () => NonNegativeInt;
+  readonly getCapacity: () => NonNegativeInt;
 
   /** Returns the current number of bytes stored in the buffer. */
-  getLength: () => NonNegativeInt;
+  readonly getLength: () => NonNegativeInt;
 
   /**
    * Appends binary data to the buffer, resizing if necessary. Throws if
    * `arg.length` is not a non-negative safe integer.
    */
-  extend: (arg: Uint8Array | ArrayLike<number>) => void;
+  readonly extend: (arg: Uint8Array | ArrayLike<number>) => void;
 
   /**
    * Removes and returns the first byte. Throws an `Error` with message "Buffer
    * parse ended prematurely" if the buffer is empty.
    */
-  shift: () => NonNegativeInt;
+  readonly shift: () => NonNegativeInt;
 
   /**
    * Removes and returns the first `n` bytes. Throws an `Error` with message
    * "Buffer parse ended prematurely" if fewer than `n` bytes remain.
    */
-  shiftN: (n: NonNegativeInt) => Uint8Array;
+  readonly shiftN: (n: NonNegativeInt) => Uint8Array;
 
   /**
    * Truncates the buffer to the specified length, discarding data from the end.
    * Throws if the new length is greater than the current length.
    */
-  truncate: (length: NonNegativeInt) => void;
+  readonly truncate: (length: NonNegativeInt) => void;
 
   /**
    * Resets the buffer to its initial empty state, preserving its capacity.
@@ -209,14 +204,14 @@ export interface Buffer {
    * when you want to clear the buffer and write new data, avoiding unnecessary
    * allocations.
    */
-  reset: () => void;
+  readonly reset: () => void;
 
   /**
    * Returns a view of the buffer’s current data. Do not modify this array, as
    * it directly alters the buffer’s internal state, potentially breaking
    * subsequent operations.
    */
-  unwrap: () => Uint8Array;
+  readonly unwrap: () => Uint8Array;
 }
 
 /** Creates a {@link Buffer} for efficient byte operations. */
@@ -438,18 +433,37 @@ export const encodeLength = (
 /** Decodes an array-like value length. */
 export const decodeLength = decodeNonNegativeInt;
 
-/** Encodes a length-prefixed UTF-8 string. */
+/**
+ * Encodes a length-prefixed UTF-8 string.
+ *
+ * A lone surrogate becomes U+FFFD, so the bytes are always valid UTF-8. Unlike
+ * {@link encodeJsonValue}, which keeps lone surrogates, this does not round-trip
+ * every JavaScript string.
+ */
 export const encodeString = (buffer: Buffer, value: string): void => {
   const bytes = utf8ToBytes(value);
   encodeLength(buffer, bytes);
   buffer.extend(bytes);
 };
 
-/** Decodes a length-prefixed UTF-8 string. */
+/**
+ * Decodes a length-prefixed UTF-8 string.
+ *
+ * Invalid UTF-8 decodes as U+FFFD instead of throwing. A leading U+FEFF is
+ * kept. Decoders in `@evolu/common` 8.17 and earlier drop it, so such peers
+ * still store a string that starts with it without the mark.
+ */
 export const decodeString = (buffer: Buffer): string => {
   const length = decodeLength(buffer);
   const bytes = buffer.shiftN(length);
-  return bytesToUtf8(bytes);
+  const string = bytesToUtf8(bytes);
+  // bytesToUtf8 uses the default TextDecoder, which drops a leading U+FEFF
+  // (EF BB BF in UTF-8), so it is restored here. Passing { ignoreBOM: true }
+  // to a TextDecoder would also keep it, but costs more compiler types in the
+  // type benchmark.
+  return bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
+    ? `\uFEFF${string}`
+    : string;
 };
 
 /** Incrementally encodes consecutive equal values using run-length encoding. */
@@ -457,6 +471,15 @@ export interface RunLengthEncoder<T> {
   readonly add: (value: T) => void;
   readonly getLength: () => NonNegativeInt;
   readonly unwrap: () => Uint8Array;
+
+  /**
+   * Returns a function that restores the encoder, in constant time, to the
+   * state it had when this was called, discarding every value added since.
+   *
+   * A restore function can be called repeatedly. It is valid until the encoder
+   * is restored to an earlier checkpoint.
+   */
+  readonly checkpoint: () => () => void;
 }
 
 /** Creates an incremental run-length encoder. */
@@ -485,6 +508,26 @@ export const createRunLengthEncoder = <T>(
     getLength: () => buffer.getLength(),
 
     unwrap: () => buffer.unwrap(),
+
+    checkpoint: () => {
+      const checkpointLength = previousLength;
+      const checkpointValue = previousValue;
+      const checkpointRunLength = runLength;
+
+      return () => {
+        // `add` rewrites the last run in place, so the bytes after its start
+        // may differ from the checkpoint's even at the same length. Bytes
+        // before it never change, so the last run is encoded again.
+        buffer.truncate(checkpointLength);
+        previousLength = checkpointLength;
+        previousValue = checkpointValue;
+        runLength = checkpointRunLength;
+        if (runLength > 0) {
+          encodeValue(buffer, previousValue as T);
+          encodeNonNegativeInt(buffer, runLength);
+        }
+      };
+    },
   };
 };
 
@@ -557,6 +600,9 @@ interface JsonKeyCacheEntry {
 const jsonKeyCacheSize = 4096;
 const maxCachedJsonKeyByteLength = 32;
 const maxJsonNestingDepth = 1_000;
+// A string reserves 3 bytes per UTF-16 code unit, so one large value would
+// otherwise keep several times its size allocated after encoding.
+const maxRetainedJsonEncoderLength = 1024 * 1024;
 let jsonEncoderTarget = new Uint8Array(8192);
 let jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
 let jsonEncoderPosition = 0;
@@ -622,6 +668,10 @@ export const encodeJsonValue = (buffer: Buffer, value: JsonValue): void => {
     jsonEncoderPosition = 0;
     jsonEncoderDepth = 0;
     jsonEncoderIsActive = false;
+    if (jsonEncoderTarget.length > maxRetainedJsonEncoderLength) {
+      jsonEncoderTarget = new Uint8Array(8192);
+      jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
+    }
   }
 };
 

package/src/Error.ts

@@ -172,7 +172,11 @@ export const defectToError = (reported: unknown): Error => {
   // instanceof fails.
   const tag = Object.prototype.toString.call(defect);
   // Chromium reports a DOMException from a worker without its name or message,
-  // so it is described in an Error.
+  // so it is described in an Error. Its fix covered only exceptions thrown in
+  // classic workers (https://issues.chromium.org/issues/41241359); Chrome 154
+  // still drops both for reportError
+  // (https://issues.chromium.org/issues/568850673) and for a module worker's
+  // evaluation.
   if (tag === "[object DOMException]") {
     const { name, message } = defect as Error;
     return new Error(`${name}: ${message}`, { cause: defect });

package/src/Polyfills.ts

@@ -37,8 +37,9 @@ export const installPolyfills = (): void => {
    * This module intentionally owns `DisposableStack` and `AsyncDisposableStack`
    * polyfills instead of depending on `es-shims/DisposableStack` at runtime.
    *
-   * Evolu originally used the upstream package, but WebKit hit a known async
-   * disposal completion bug (`completion["?"]` crash, see issue #9). The local
+   * Evolu originally used the upstream package, but WebKit, which needs the
+   * polyfill, hit its async disposal completion bug (`completion["?"]` crash,
+   * https://github.com/es-shims/DisposableStack/issues/9). The local
    * implementation applies the fix and keeps behavior deterministic across
    * runtimes used by Evolu.
    *

package/src/Sqlite.ts

@@ -188,7 +188,7 @@ export interface SqliteQueryOptions {
    * statements can improve performance for repeated queries by reusing the
    * compiled query.
    *
-   * See: {@link https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-prepare}.
+   * See: {@link https://sqlite.org/c3ref/prepare.html}.
    */
   readonly prepare?: boolean;
 }

package/src/Task.ts

@@ -1798,9 +1798,10 @@ export interface AbortReason extends InferType<typeof AbortReason> {}
  * Helpers that abort their own child Tasks should catch or normalize AbortError
  * before it escapes the helper boundary. The reason carries typed domain data.
  *
- * WebKit fetch rejects with its own abort error instead of `signal.reason`.
- * Native wrappers should treat `signal.reason` as the source of truth and
- * normalize aborts to AbortError.
+ * WebKit fetch rejects with its own abort error instead of `signal.reason`
+ * ([WebKit bug 246069](https://bugs.webkit.org/show_bug.cgi?id=246069)). Native
+ * wrappers should treat `signal.reason` as the source of truth and normalize
+ * aborts to AbortError.
  *
  * @group Core
  */

package/src/index.ts

@@ -51,7 +51,10 @@ export * from "./WebSocket.ts";
 export * from "./Worker.ts";
 
 // Local-first essentials.
-export type { UnsupportedDbVersionError } from "./local-first/Db.ts";
+export type {
+  DatabaseHeldError,
+  UnsupportedDbVersionError,
+} from "./local-first/Db.ts";
 export {
   AppName,
   createEvolu,

package/src/local-first/Db.ts

@@ -23,8 +23,10 @@
  * 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.
+ * worker then exits and releases its resources. A database whose files another
+ * context keeps holding refuses startup the same way, before it is opened, with
+ * {@link DatabaseHeldError}; see {@link WaitForDatabaseRelease}. 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
@@ -57,7 +59,7 @@ import {
   type RandomBytesDep,
 } from "../Crypto.ts";
 import { createUnknownError } from "../Error.ts";
-import { constFalse, constVoid } from "../Function.ts";
+import { constFalse } from "../Function.ts";
 import type { LockManagerDep } from "../LockManager.ts";
 import {
   acquireLeaderLock,
@@ -116,6 +118,7 @@ import {
   decryptAndDecodeDbChange,
   encodeAndEncryptDbChange,
   SubscriptionFlags,
+  type ProtocolChangeTooLargeError,
   type ProtocolInvalidDataError,
   type ProtocolMessage,
   type ProtocolTimestampMismatchError,
@@ -194,7 +197,28 @@ export interface CreateDbWorkerDep {
 export type DbWorkerDeps = WorkerDeps &
   CreateBroadcastChannelDep &
   LockManagerDep &
-  CreateSqliteDriverDep;
+  CreateSqliteDriverDep &
+  Partial<WaitForDatabaseReleaseDep>;
+
+/**
+ * Waits until no other context holds the files of the persistent database
+ * `name`, and fails with {@link DatabaseHeldError} when they stay held.
+ *
+ * {@link startDbWorker} calls it, except for a memory-only database, while it
+ * holds the database's leader lock and before it opens the database. Only a
+ * context that ended without closing the database can then hold its files, and
+ * such a context can only release them, so the files stay free until the
+ * database opens. Platforms whose databases cannot be held this way, such as
+ * Node.js and React Native, omit it.
+ */
+export type WaitForDatabaseRelease = (
+  name: Name,
+) => Task<void, DatabaseHeldError>;
+
+/** Dependency wrapper for {@link WaitForDatabaseRelease}. */
+export interface WaitForDatabaseReleaseDep {
+  readonly waitForDatabaseRelease: WaitForDatabaseRelease;
+}
 
 /** The database version this code creates and supports; see the module doc. */
 const dbVersion = PositiveInt.orThrow(2);
@@ -215,6 +239,18 @@ export interface UnsupportedDbVersionError extends Typed<"UnsupportedDbVersionEr
   readonly supportedVersion: PositiveInt;
 }
 
+/**
+ * Another context kept holding the database's files, so the database did not
+ * open; see {@link WaitForDatabaseRelease}.
+ *
+ * A browser can keep the files of a worker that ended without closing them
+ * until the browser restarts. Ask the user to close the app's other tabs or to
+ * restart the browser, then to reload the app.
+ */
+export interface DatabaseHeldError extends Typed<"DatabaseHeldError"> {
+  readonly name: Name;
+}
+
 /**
  * Starts the platform-agnostic Evolu DbWorker and owns its resources until
  * startup is refused, the worker receives a dispose message, the SharedWorker
@@ -258,6 +294,15 @@ export const startDbWorker =
 
     disposer.use(await run.ok(acquireLeaderLock(initMessage.name)));
 
+    if (!initMessage.memoryOnly && deps.waitForDatabaseRelease) {
+      const released = await run(deps.waitForDatabaseRelease(initMessage.name));
+      if (!released.ok) {
+        // Returning lets the disposer release the database lock.
+        port.postMessage({ type: "LeaderRefused", error: released.error });
+        return ok();
+      }
+    }
+
     const sqlite = disposer.use(
       await run.ok(
         createSqlite(
@@ -374,6 +419,7 @@ export const startDbWorker =
                 const result = await run.abortable(
                   applyProtocolMessageAsClient(inputMessage, {
                     writeKey: owner.writeKey,
+                    onChangeTooLarge: storage.onChangeTooLarge,
                   }),
                 );
                 postQueuedResponse({
@@ -475,7 +521,8 @@ export const startDbWorker =
 
         // Stops once the SharedWorker no longer leads for its ID, which the
         // platform releases when it closes, because Firefox can lose a Dispose
-        // posted right before that.
+        // posted right before that
+        // (https://bugzilla.mozilla.org/show_bug.cgi?id=2077609).
         const sharedWorkerEnded = acquireLeaderLockCallback(deps)(
           initMessage.sharedWorkerId,
           () => resolve(ok()),
@@ -917,14 +964,18 @@ interface ClientStorage extends Storage, BaseSqliteStorage {
   ) => void;
   readonly didWriteMessages: () => boolean;
   /**
-   * The first error of a message that {@link Storage.writeMessages} skipped in
-   * this request, or null.
+   * The first error of a message skipped in this request, or null: one that
+   * {@link Storage.writeMessages} could not store, or a stored change that sync
+   * could not send.
    */
   readonly skippedError: () =>
     | DecryptWithXChaCha20Poly1305Error
     | ProtocolInvalidDataError
     | ProtocolTimestampMismatchError
+    | ProtocolChangeTooLargeError
     | null;
+  /** Records a stored change that sync skipped, unless an error came first. */
+  readonly onChangeTooLarge: (error: ProtocolChangeTooLargeError) => void;
 }
 
 const createClientStorage = (
@@ -961,10 +1012,12 @@ const createClientStorage = (
 
     didWriteMessages: () => didWriteMessages,
     skippedError: () => skippedError,
+    onChangeTooLarge: (error) => {
+      skippedError ??= error;
+    },
 
     // Not implemented yet.
     validateWriteKey: constFalse,
-    setWriteKey: constVoid,
 
     writeMessages: (ownerIdBytes, encryptedMessages) => () => {
       // TODO: Add quota checking for collaborative scenarios.
@@ -1020,15 +1073,21 @@ const createClientStorage = (
       }
 
       let wroteNewMessages = false;
-      deps.sqlite.transaction(() => {
-        wroteNewMessages = applyMessages(deps)(
-          ownerIdBytesToOwnerId(ownerIdBytes),
-          messages,
-          QuarantineOrigin.ReceivedMessage,
-          now,
-        );
-        saveClock(deps)(clockTimestamp);
-      });
+      // SQLite can fail the write, for example on a full disk. The transaction
+      // has rolled back, so the route reports the error instead of a throw
+      // panicking the DbWorker.
+      const written = trySync(() => {
+        deps.sqlite.transaction(() => {
+          wroteNewMessages = applyMessages(deps)(
+            ownerIdBytesToOwnerId(ownerIdBytes),
+            messages,
+            QuarantineOrigin.ReceivedMessage,
+            now,
+          );
+          saveClock(deps)(clockTimestamp);
+        });
+      }, createUnknownError);
+      if (!written.ok) return written;
       clock.set(clockTimestamp);
       // A batch of duplicates changes no table, so queries need no refresh.
       if (wroteNewMessages) didWriteMessages = true;