@evolu/common 6.0.1-preview.0 → 6.0.1-preview.10

package/src/Evolu/Protocol.ts

@@ -7,31 +7,47 @@
  * relays with each other.
  *
  * Evolu Protocol is designed for SQLite but can be extended to any database. It
- * implements [Range-Based Set Reconciliation](https://arxiv.org/abs/2212.13567)
- * by Aljoscha Meyer.
- *
- * To learn how RBSR works, check
- * [Negentropy](https://logperiodic.com/rbsr.html). Evolu Protocol is similar to
- * Negentropy but uses different encoding and also provides data transfer and
- * ownership.
+ * implements [Range-Based Set
+ * Reconciliation](https://arxiv.org/abs/2212.13567). To learn how RBSR works,
+ * check [Negentropy](https://logperiodic.com/rbsr.html). Evolu Protocol is
+ * similar to Negentropy but uses different encoding and also provides data
+ * transfer and ownership.
  *
  * ### Message Structure
  *
- * | Field                          | Notes                      |
- * | :----------------------------- | :------------------------- |
- * | **Header**                     |                            |
- * | - {@link protocolVersion}      |                            |
- * | - {@link OwnerId}              |                            |
- * | - {@link ProtocolErrorCode}    | In non-initiator response. |
- * | **Messages**                   |                            |
- * | - {@link NonNegativeInt}       | A number of messages.      |
- * | - {@link EncryptedCrdtMessage} |                            |
- * | - {@link WriteKey}             | In initiator request.      |
- * | **Ranges**                     |                            |
- * | - {@link NonNegativeInt}       | Number of ranges.          |
- * | - {@link Range}                |                            |
+ * | Field                          | Notes                     |
+ * | :----------------------------- | :------------------------ |
+ * | **Header**                     |                           |
+ * | - {@link protocolVersion}      |                           |
+ * | - {@link OwnerId}              | {@link Owner}             |
+ * | **Initiator**                  |                           |
+ * | - {@link WriteKeyMode}         |                           |
+ * | - {@link WriteKey}             | If WriteKeyMode >= 1      |
+ * | - {@link WriteKey}             | If WriteKeyMode = 2 (new) |
+ * | **Non-initiator**              |                           |
+ * | - {@link ProtocolErrorCode}    |                           |
+ * | **Messages**                   |                           |
+ * | - {@link NonNegativeInt}       | A number of messages.     |
+ * | - {@link EncryptedCrdtMessage} |                           |
+ * | **Ranges**                     |                           |
+ * | - {@link NonNegativeInt}       | Number of ranges.         |
+ * | - {@link Range}                |                           |
+ *
+ * ### WriteKey Validation
+ *
+ * The initiator sends WriteKeyMode and optionally one or two WriteKeys. One key
+ * for write operations and two for key rotation (current and new). Note that
+ * it's ok to not send any key if initiator is going to be synced with readonly
+ * owner. The non-initiator validates them immediately after parsing the
+ * initiator header, before processing any messages or ranges.
  *
- * Every protocol message belongs to an owner.
+ * ### WriteKey Rotation
+ *
+ * When initiator's {@link WriteKeyMode} is `Rotation`, two WriteKeys are
+ * present:
+ *
+ * 1. Current WriteKey (for validation)
+ * 2. New WriteKey (to be stored)
  *
  * ### Synchronization
  *
@@ -48,21 +64,34 @@
  * Both **Messages** and **Ranges** are optional, allowing each side to send,
  * sync, or only subscribe data as needed.
  *
- * When the initiator sends data, the {@link WriteKey} is **required** in
- * **Messages** as a secure token proving the initiator can write changes. The
- * non-initiator responds without a {@link WriteKey}, since the initiator’s
- * request already signals it wants data. If the non-initiator detects an issue
- * (e.g., an invalid {@link WriteKey} causing a {@link ProtocolWriteKeyError}, or
- * a write failure causing a {@link ProtocolWriteError}), it sends an error code
- * via the `Error` field in the header back to the initiator. In relay-to-relay
- * or P2P sync, both sides may require the {@link WriteKey} depending on who is
- * the initiator.
+ * When the initiator sends data, the {@link WriteKey} is required in Messages as
+ * a secure token proving the initiator can write changes. The non-initiator
+ * responds without a {@link WriteKey}, since the initiator’s request already
+ * signals it wants data. If the non-initiator detects an issue, it sends an
+ * error code via the `Error` field in the header back to the initiator. In
+ * relay-to-relay or P2P sync, both sides may require the {@link WriteKey}
+ * depending on who is the initiator.
+ *
+ * ### Protocol Errors
+ *
+ * The protocol uses error codes in the header to signal issues:
+ *
+ * - {@link ProtocolWriteKeyError}: The provided WriteKey is invalid or missing.
+ * - {@link ProtocolWriteError}: A write operation failed (e.g., due to storage
+ *   limits or billing).
+ * - {@link ProtocolSyncError}: A generic or unexpected synchronization failure
+ *   occurred.
+ * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
+ * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
+ *
+ * All protocol errors except `ProtocolInvalidDataError` include the `ownerId`
+ * to allow clients to associate errors with the correct owner.
  *
  * ### Message Size Limit
  *
  * The protocol enforces a strict maximum size for all messages, defined by
- * {@link maxProtocolMessageSize}. This ensures every `ProtocolMessage` is less
- * than or equal to this limit, eliminating the need for applications to
+ * {@link maxProtocolMessageSize}. This ensures every {@link ProtocolMessage} is
+ * less than or equal to this limit, eliminating the need for applications to
  * fragment and reconstruct messages during transmission.
  *
  * ### Why Binary?
@@ -88,11 +117,24 @@
  *
  * ### Versioning
  *
- * The initiator sends a versioned `ProtocolMessage`. If the non-initiator uses
- * a different version, it responds with a message containing only its protocol
- * version—**without an `ownerId`**. This allows the initiator to check protocol
- * compatibility, for example, by sending version-only messages to multiple
- * relays before starting synchronization.
+ * Evolu Protocol uses explicit versioning to ensure compatibility between
+ * clients and relays (or peers). Each protocol message begins with a version
+ * number and an `ownerId` in its header.
+ *
+ * **How version negotiation works:**
+ *
+ * - The initiator (usually a client) sends a `ProtocolMessage` that includes its
+ *   protocol version and the `ownerId`.
+ * - The non-initiator (usually a relay or peer) checks the version.
+ *
+ *   - If the versions match, synchronization proceeds as normal.
+ *   - If the versions do not match, the non-initiator responds with a message
+ *       containing **its own protocol version and the same `ownerId`**.
+ * - The initiator can then detect the version mismatch for that specific owner
+ *   and handle it appropriately (e.g., prompt for an update or halt sync).
+ *
+ * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
+ * over time and provide clear feedback about version mismatches.
  *
  * @module
  */
@@ -103,10 +145,8 @@ import { isNonEmptyReadonlyArray, NonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
 import {
   Buffer,
-  BufferError,
   bytesToHex,
   bytesToUtf8,
-  concatBytes,
   createBuffer,
   hexToBytes,
   utf8ToBytes,
@@ -120,7 +160,7 @@ import {
 } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
-import { objectToEntries, ReadonlyRecord } from "../Object.js";
+import { objectToEntries } from "../Object.js";
 import { err, ok, Result } from "../Result.js";
 import { SqliteValue } from "../Sqlite.js";
 import {
@@ -133,10 +173,13 @@ import {
   NanoId,
   NonNegativeInt,
   Number,
+  object,
   PositiveInt,
+  record,
 } from "../Type.js";
 import { Brand, Predicate } from "../Types.js";
 import {
+  Owner,
   OwnerId,
   OwnerWithWriteAccess,
   WriteKey,
@@ -177,6 +220,14 @@ export const ProtocolErrorCode = {
 type ProtocolErrorCode =
   (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
 
+export const WriteKeyMode = {
+  None: 0,
+  Single: 1,
+  Rotation: 2,
+} as const;
+
+type WriteKeyMode = (typeof WriteKeyMode)[keyof typeof WriteKeyMode];
+
 /**
  * Evolu Protocol Storage
  *
@@ -221,17 +272,15 @@ export interface Storage {
     callback: (timestamp: BinaryTimestamp, index: NonNegativeInt) => boolean,
   ) => void;
 
-  /**
-   * Authorizes the initiator's {@link WriteKey} for the given
-   * {@link BinaryOwnerId}.
-   *
-   * For a client that does not expect foreign writes, return `false`.
-   */
+  /** Validates the {@link WriteKey} for the given {@link Owner}. */
   readonly validateWriteKey: (
     ownerId: BinaryOwnerId,
     writeKey: WriteKey,
   ) => boolean;
 
+  /** Sets the {@link WriteKey} for the given {@link Owner}. */
+  readonly setWriteKey: (ownerId: BinaryOwnerId, writeKey: WriteKey) => boolean;
+
   /** Write encrypted {@link CrdtMessage}s to storage. */
   readonly writeMessages: (
     ownerId: BinaryOwnerId,
@@ -243,6 +292,9 @@ export interface Storage {
     ownerId: BinaryOwnerId,
     timestamp: BinaryTimestamp,
   ) => EncryptedDbChange | null;
+
+  /** Delete all data for the given {@link Owner}. */
+  readonly deleteOwner: (ownerId: BinaryOwnerId) => boolean;
 }
 
 export interface StorageDep {
@@ -267,15 +319,23 @@ export interface CrdtMessage {
   readonly change: DbChange;
 }
 
+/**
+ * Base64Url string with maximum length of 256 characters. Encoding strings as
+ * Base64UrlString saves up to 25% in size compared to regular strings.
+ */
+export const Base64Url256 = maxLength(256)(Base64Url);
+export type Base64Url256 = typeof Base64Url256.Type;
+
 /**
  * A DbChange is a change to a table row. Together with a unique
  * {@link Timestamp}, it forms a {@link CrdtMessage}.
  */
-export interface DbChange {
-  readonly table: Base64Url256;
-  readonly id: Id;
-  readonly values: ReadonlyRecord<Base64Url256, SqliteValue>;
-}
+export const DbChange = object({
+  table: Base64Url256,
+  id: Id,
+  values: record(Base64Url256, SqliteValue),
+});
+export type DbChange = typeof DbChange.Type;
 
 export const RangeType = {
   Fingerprint: 1,
@@ -340,11 +400,16 @@ export type ProtocolError =
   | ProtocolWriteError
   | ProtocolSyncError;
 
+/** Base interface for all protocol errors. */
+export interface ProtocolErrorBase {
+  readonly ownerId: OwnerId;
+}
+
 /**
  * Represents a version mismatch in the Evolu Protocol. Occurs when the
  * initiator and non-initiator are using incompatible protocol versions.
  */
-export interface ProtocolUnsupportedVersionError {
+export interface ProtocolUnsupportedVersionError extends ProtocolErrorBase {
   readonly type: "ProtocolUnsupportedVersionError";
   readonly unsupportedVersion: NonNegativeInt;
   /** Indicates which side is obsolete and should update. */
@@ -359,7 +424,7 @@ export interface ProtocolInvalidDataError {
 }
 
 /** Error when a {@link WriteKey} is invalid, missing, or fails validation. */
-export interface ProtocolWriteKeyError {
+export interface ProtocolWriteKeyError extends ProtocolErrorBase {
   readonly type: "ProtocolWriteKeyError";
 }
 
@@ -367,7 +432,7 @@ export interface ProtocolWriteKeyError {
  * Error when a write fails due to storage limits or billing requirements.
  * Indicates the need to expand capacity or resolve payment issues.
  */
-export interface ProtocolWriteError {
+export interface ProtocolWriteError extends ProtocolErrorBase {
   readonly type: "ProtocolWriteError";
 }
 
@@ -375,7 +440,7 @@ export interface ProtocolWriteError {
  * Error indicating a synchronization failure during the protocol exchange. Used
  * for unexpected or generic sync errors not covered by other error types.
  */
-export interface ProtocolSyncError {
+export interface ProtocolSyncError extends ProtocolErrorBase {
   readonly type: "ProtocolSyncError";
 }
 
@@ -394,6 +459,7 @@ export const createProtocolMessageFromCrdtMessages =
     maxSize?: PositiveInt,
   ): ProtocolMessage => {
     const buffer = createProtocolMessageBuffer(owner.id, {
+      type: "initiator",
       totalMaxSize: maxSize ?? maxProtocolMessageSize,
       writeKey: owner.writeKey,
     });
@@ -449,7 +515,7 @@ export const createProtocolMessageFromCrdtMessages =
 export const createProtocolMessageForSync =
   (deps: StorageDep) =>
   (ownerId: OwnerId): ProtocolMessage | null => {
-    const buffer = createProtocolMessageBuffer(ownerId);
+    const buffer = createProtocolMessageBuffer(ownerId, { type: "initiator" });
     const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
     const size = deps.storage.getSize(binaryOwnerId);
@@ -467,6 +533,19 @@ export const createProtocolMessageForSync =
     return buffer.unwrap();
   };
 
+/** Creates a ProtocolMessage for {@link WriteKey} rotation. */
+export const createProtocolMessageForWriteKeyRotation = (
+  ownerId: OwnerId,
+  currentWriteKey: WriteKey,
+  newWriteKey: WriteKey,
+): ProtocolMessage => {
+  const buffer = createProtocolMessageBuffer(ownerId, {
+    type: "initiator",
+    writeKey: [currentWriteKey, newWriteKey],
+  });
+  return buffer.unwrap();
+};
+
 /**
  * Mutable builder for constructing {@link ProtocolMessage} respecting size
  * limits.
@@ -494,16 +573,22 @@ export interface ProtocolMessageBuffer {
 export const createProtocolMessageBuffer = (
   ownerId: OwnerId,
   options: {
-    readonly errorCode?: ProtocolErrorCode;
-    readonly writeKey?: WriteKey;
     readonly totalMaxSize?: PositiveInt | undefined;
     readonly rangesMaxSize?: PositiveInt | undefined;
     readonly version?: NonNegativeInt;
-  } = {},
+  } & (
+    | {
+        readonly type: "initiator";
+        /** Single key or [current, new] for rotation. */
+        readonly writeKey?: WriteKey | readonly [WriteKey, WriteKey];
+      }
+    | {
+        readonly type: "non-initiator";
+        readonly errorCode: ProtocolErrorCode;
+      }
+  ),
 ): ProtocolMessageBuffer => {
   const {
-    errorCode,
-    writeKey,
     totalMaxSize = maxProtocolMessageSize,
     rangesMaxSize = maxProtocolMessageRangesSize,
     version = protocolVersion,
@@ -524,7 +609,21 @@ export const createProtocolMessageBuffer = (
 
   encodeNonNegativeInt(buffers.header, version);
   buffers.header.extend(ownerIdToBinaryOwnerId(ownerId));
-  if (errorCode != null) buffers.header.extend([errorCode]);
+
+  if (options.type === "initiator") {
+    if (!options.writeKey) {
+      buffers.header.extend([WriteKeyMode.None]);
+    } else if (!Array.isArray(options.writeKey)) {
+      buffers.header.extend([WriteKeyMode.Single]);
+      buffers.header.extend(options.writeKey as WriteKey);
+    } else {
+      buffers.header.extend([WriteKeyMode.Rotation]);
+      buffers.header.extend(options.writeKey[0] as WriteKey); // current
+      buffers.header.extend(options.writeKey[1] as WriteKey); // new
+    }
+  } else {
+    buffers.header.extend([options.errorCode]);
+  }
 
   let isLastRangeInfinite = false;
 
@@ -536,10 +635,7 @@ export const createProtocolMessageBuffer = (
   const getHeaderAndMessagesSize = () =>
     buffers.header.getLength() +
     buffers.messages.timestamps.getLength() +
-    buffers.messages.dbChanges.getLength() +
-    (buffers.messages.timestamps.getCount() > 0 && writeKey
-      ? writeKeyLength
-      : 0);
+    buffers.messages.dbChanges.getLength();
 
   const getRangesSize = () =>
     buffers.ranges.timestamps.getCount() > 0
@@ -654,8 +750,6 @@ export const createProtocolMessageBuffer = (
 
       buffers.messages.timestamps.append(buffers.header);
       buffers.header.extend(buffers.messages.dbChanges.unwrap());
-      if (buffers.messages.timestamps.getCount() > 0 && writeKey)
-        buffers.header.extend(writeKey);
 
       if (buffers.ranges.timestamps.getCount() > 0) {
         buffers.ranges.timestamps.append(buffers.header);
@@ -794,33 +888,34 @@ export const applyProtocolMessageAsClient =
     tryDecodeProtocolData<ProtocolMessage | null, ProtocolError>(
       inputMessage,
       (input) => {
-        const requestedVersion = decodeNonNegativeInt(input);
+        const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
 
         if (requestedVersion !== version) {
           return err<ProtocolUnsupportedVersionError>({
             type: "ProtocolUnsupportedVersionError",
             unsupportedVersion: requestedVersion,
             isInitiator: version < requestedVersion,
+            ownerId,
           });
         }
 
-        const ownerId = decodeOwnerId(input);
-        const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-
         const errorCode = input.shift() as ProtocolErrorCode;
         if (errorCode !== ProtocolErrorCode.NoError) {
           switch (errorCode) {
             case ProtocolErrorCode.WriteKeyError:
               return err<ProtocolWriteKeyError>({
                 type: "ProtocolWriteKeyError",
+                ownerId,
               });
             case ProtocolErrorCode.WriteError:
               return err<ProtocolWriteError>({
                 type: "ProtocolWriteError",
+                ownerId,
               });
             case ProtocolErrorCode.SyncError:
               return err<ProtocolSyncError>({
                 type: "ProtocolSyncError",
+                ownerId,
               });
             default:
               throw new ProtocolDecodeError(
@@ -830,6 +925,7 @@ export const applyProtocolMessageAsClient =
         }
 
         const messages = decodeMessages(input);
+        const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
         if (
           isNonEmptyReadonlyArray(messages) &&
@@ -843,6 +939,7 @@ export const applyProtocolMessageAsClient =
         if (writeKey == null) return ok(null);
 
         const output = createProtocolMessageBuffer(ownerId, {
+          type: "initiator",
           writeKey,
           totalMaxSize,
           rangesMaxSize,
@@ -877,58 +974,102 @@ export const applyProtocolMessageAsRelay =
     version = protocolVersion,
   ): Result<ProtocolMessage | null, ProtocolInvalidDataError> =>
     tryDecodeProtocolData(inputMessage, (input) => {
-      const requestedVersion = decodeNonNegativeInt(input);
+      const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
+      const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
       if (requestedVersion !== version) {
-        // Non-initiator responds with its version.
+        // Non-initiator responds with its version and ownerId.
         const output = createBuffer();
         encodeNonNegativeInt(output, version);
+        output.extend(binaryOwnerId);
         return ok(output.unwrap() as ProtocolMessage);
       }
 
-      const ownerId = decodeOwnerId(input);
-      const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-
       subscribe?.(ownerId);
 
-      const messages = decodeMessages(input);
+      const writeKeyMode = input.shift() as WriteKeyMode;
+      let writeKey: WriteKey | undefined;
+      let newWriteKey: WriteKey | undefined;
+
+      if (writeKeyMode !== WriteKeyMode.None) {
+        writeKey = input.shiftN(writeKeyLength) as WriteKey;
+        switch (writeKeyMode) {
+          case WriteKeyMode.Single:
+            break;
+          case WriteKeyMode.Rotation:
+            newWriteKey = input.shiftN(writeKeyLength) as WriteKey;
+            break;
+          default:
+            throw new ProtocolDecodeError(
+              `Invalid WriteKeyMode: ${writeKeyMode}`,
+            );
+        }
+      }
 
-      if (isNonEmptyReadonlyArray(messages)) {
-        const messagesEnd = inputMessage.length - input.getLength();
-        const writeKey = input.shiftN(writeKeyLength) as WriteKey;
+      if (writeKey) {
+        const isValid = deps.storage.validateWriteKey(binaryOwnerId, writeKey);
+        if (!isValid) {
+          return ok(
+            createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
+              errorCode: ProtocolErrorCode.WriteKeyError,
+            }).unwrap(),
+          );
+        }
 
-        const writeKeyIsValid = deps.storage.validateWriteKey(
-          binaryOwnerId,
-          writeKey,
-        );
+        if (newWriteKey) {
+          const rotationSuccess = deps.storage.setWriteKey(
+            binaryOwnerId,
+            newWriteKey,
+          );
+          if (!rotationSuccess) {
+            return ok(
+              createProtocolMessageBuffer(ownerId, {
+                type: "non-initiator",
+                errorCode: ProtocolErrorCode.WriteError,
+              }).unwrap(),
+            );
+          }
+        }
+      }
 
-        if (!writeKeyIsValid)
+      const messages = decodeMessages(input);
+
+      if (isNonEmptyReadonlyArray(messages)) {
+        if (!writeKey)
           return ok(
             createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
               errorCode: ProtocolErrorCode.WriteKeyError,
             }).unwrap(),
           );
 
-        if (broadcast) {
-          // Instead of encoding a new protocol message, we reuse the inputMessage.
-          const broadcastMessage = concatBytes(
-            inputMessage.slice(0, 17),
-            new Uint8Array([ProtocolErrorCode.NoError]),
-            inputMessage.slice(17, messagesEnd),
-          ) as ProtocolMessage;
-
-          broadcast(ownerId, broadcastMessage);
+        // Only broadcast if there's no ranges.
+        if (broadcast && input.getLength() === 0) {
+          const broadcastBuffer = createProtocolMessageBuffer(ownerId, {
+            type: "non-initiator",
+            errorCode: ProtocolErrorCode.NoError,
+            totalMaxSize,
+            rangesMaxSize,
+            version,
+          });
+          for (const message of messages) {
+            broadcastBuffer.addMessage(message);
+          }
+          broadcast(ownerId, broadcastBuffer.unwrap());
         }
 
         if (!deps.storage.writeMessages(binaryOwnerId, messages))
           return ok(
             createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
               errorCode: ProtocolErrorCode.WriteError,
             }).unwrap(),
           );
       }
 
       const output = createProtocolMessageBuffer(ownerId, {
+        type: "non-initiator",
         errorCode: ProtocolErrorCode.NoError,
         totalMaxSize,
         rangesMaxSize,
@@ -949,17 +1090,24 @@ const tryDecodeProtocolData = <T, E>(
   try {
     return callback(createBuffer(data));
   } catch (error: unknown) {
-    if (error instanceof ProtocolDecodeError || error instanceof BufferError)
-      return err<ProtocolInvalidDataError>({
-        type: "ProtocolInvalidDataError",
-        data,
-        error,
-      });
-
-    throw error;
+    return err<ProtocolInvalidDataError>({
+      type: "ProtocolInvalidDataError",
+      data,
+      error,
+    });
   }
 };
 
+const decodeVersionAndOwner = (input: Buffer): [NonNegativeInt, OwnerId] => {
+  // This structure must never change across protocol versions. The version
+  // and owner ID must always be the first two fields in every protocol message
+  // to enable version negotiation and owner identification before any other
+  // processing occurs.
+  const version = decodeNonNegativeInt(input);
+  const ownerId = decodeOwnerId(input);
+  return [version, ownerId];
+};
+
 /**
  * Error thrown for internal protocol validation failures, such as invalid data
  * or type errors.
@@ -1012,6 +1160,7 @@ const sync =
         return ok(null);
       }
       const message = createProtocolMessageBuffer(binaryOwnerId, {
+        type: "non-initiator",
         errorCode: ProtocolErrorCode.SyncError,
       });
       return ok(message.unwrap());
@@ -1394,13 +1543,6 @@ export const ownerIdToBinaryOwnerId = (ownerId: OwnerId): BinaryOwnerId =>
 export const binaryOwnerIdToOwnerId = (binaryOwnerId: BinaryOwnerId): OwnerId =>
   decodeOwnerId(createBuffer(binaryOwnerId));
 
-/**
- * Base64Url string with maximum length of 256 characters. Encoding strings as
- * Base64UrlString saves up to 25% in size compared to regular strings.
- */
-export const Base64Url256 = maxLength(256)(Base64Url);
-export type Base64Url256 = typeof Base64Url256.Type;
-
 /**
  * Union type for all variants of Base64Url strings with limited length. All
  * these types use Base64Url alphabet and are < 256 characters.
@@ -1855,3 +1997,27 @@ export const decodeSqliteValue = (buffer: Buffer): SqliteValue => {
       throw new ProtocolDecodeError("invalid ProtocolValueType");
   }
 };
+
+/**
+ * Decodes a ProtocolMessage into a readable JSON object for debugging.
+ *
+ * Note: This is a stub for future implementation. It should use:
+ *
+ * - DecodeVersionAndOwner
+ * - DecodeError or decodeWriteKeys (depending on context)
+ * - DecodeMessages
+ * - DecodeRanges
+ *
+ * If you want to help, please contribute to this function.
+ */
+export const decodeProtocolMessageToJson = (
+  _protocolMessage: ProtocolMessage,
+  _isInitiator: boolean,
+): unknown => {
+  // TODO: Implement using
+  // - decodeVersionAndOwner
+  // -- decodeError or decodeWriteKeys (should be refactored out),
+  // -- decodeMessages, and decodeRanges.
+  // This is a stub for PRs and community contributions.
+  throw new Error("decodeProtocolMessageToJson is not implemented yet.");
+};