@evolu/common 6.0.1-preview.2 → 6.0.1-preview.20

package/src/Evolu/Protocol.ts

@@ -1,35 +1,57 @@
+/* eslint-disable jsdoc/no-undefined-types */
 /**
  * Evolu Protocol
  *
  * Evolu Protocol is a local-first, end-to-end encrypted binary synchronization
  * protocol optimized for minimal size and maximum speed. It enables data sync
- * between a client and a relay, clients in a peer-to-peer (P2P) setup, or
- * relays with each other.
+ * between a client and a relay. In the future, direct peer-to-peer (P2P) sync
+ * between clients will be possible without a relay.
+ *
+ * Relays don't need to sync with each other—clients using those relays will
+ * sync them eventually. If a relay is offline (e.g., for maintenance), it will
+ * sync automatically later via client sync logic. For relay backup using
+ * SQLite, see https://sqlite.org/rsync.html (uses a similar algorithm to Evolu
+ * RBSR).
  *
  * 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). 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.
+ * transfer, ownership, real-time broadcasting, request-response semantics, and
+ * error handling.
  *
  * ### 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}             |
+ * | - messageType                  | {@link MessageType}       |
+ * | **Request (messageType=0)**    |                           |
+ * | - hasWriteKey                  | 0 = no, 1 = yes           |
+ * | - {@link OwnerWriteKey}        | If hasWriteKey = 1        |
+ * | - subscriptionFlag             | {@link SubscriptionFlags} |
+ * | **Response (messageType=1)**   |                           |
+ * | - {@link ProtocolErrorCode}    |                           |
+ * | **Broadcast (messageType=2)**  |                           |
+ * | - (no additional fields)       |                           |
+ * | **Messages**                   |                           |
+ * | - {@link NonNegativeInt}       | A number of messages.     |
+ * | - {@link EncryptedCrdtMessage} |                           |
+ * | **Ranges**                     |                           |
+ * | - {@link NonNegativeInt}       | Number of ranges.         |
+ * | - {@link Range}                |                           |
+ *
+ * ### WriteKey Validation
  *
- * Every protocol message belongs to an {@link Owner}.
+ * The initiator sends a hasWriteKey flag and optionally a WriteKey. The
+ * WriteKey is required when sending messages as a secure token proving the
+ * initiator can write changes. It's ok to not send a WriteKey if the initiator
+ * is only syncing (read-only) and not sending messages. The non-initiator
+ * validates the WriteKey immediately after parsing the initiator header, before
+ * processing any messages or ranges.
  *
  * ### Synchronization
  *
@@ -43,16 +65,20 @@
  * if further sync is needed or possible, continuing until both sides are
  * synchronized.
  *
+ * The **non-initiator always responds** to provide sync completion feedback,
+ * even with empty messages containing only the header and no error. This allows
+ * the initiator to detect when synchronization is complete.
+ *
  * 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, 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 OwnerWriteKey} is required as a
+ * secure token proving the initiator can write changes. The non-initiator
+ * responds without a {@link OwnerWriteKey}, 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 OwnerWriteKey} depending on who is the initiator.
  *
  * ### Protocol Errors
  *
@@ -66,15 +92,21 @@
  * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
  * - {@link ProtocolInvalidDataError}: The message is malformed or corrupted.
  *
- * All protocol errors except `ProtocolInvalidDataError` include the `ownerId`
+ * 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 {@link ProtocolMessage} is
- * less than or equal to this limit, eliminating the need for applications to
- * fragment and reconstruct messages during transmission.
+ * less than or equal to this limit, enabling stateless transports, simplified
+ * relay implementation, and predictable memory usage. When all messages don't
+ * fit within the limit, the protocol automatically continues synchronization in
+ * subsequent rounds using range-based reconciliation.
+ *
+ * Individual database mutations are limited to `maxMutationSize` (640KB), which
+ * is smaller than the protocol message limit to ensure efficient sync with
+ * {@link maxProtocolMessageRangesSize}.
  *
  * ### Why Binary?
  *
@@ -82,13 +114,12 @@
  *
  * - Encrypted data doesn’t compress well, unlike plain JSON.
  * - Message size must be controlled during creation.
- * - Sequential byte reading is faster than parsing and can avoid conversions.
+ * - Sequential byte reading is faster than parsing and avoids conversions.
  *
  * It uses structure-aware encoding, significantly outperforming generic binary
  * serialization formats with the following optimizations:
  *
  * - **NonNegativeInt:** Up to 33% smaller than MessagePack.
- * - **Base64Url Strings:** Up to 25% size reduction.
  * - **DateIso:** Up to 75% smaller.
  * - **Timestamp Encoding:** Delta encoding for milliseconds and run-length
  *   encoding (RLE) for counters and NodeIds.
@@ -121,63 +152,92 @@
  * @module
  */
 
-import { sha256 } from "@noble/hashes/sha2";
-import { pack, unpack, unpackMultiple } from "msgpackr";
+import { Packr } from "msgpackr";
 import { isNonEmptyReadonlyArray, NonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
+import { Brand } from "../Brand.js";
 import {
   Buffer,
-  BufferError,
   bytesToHex,
   bytesToUtf8,
-  concatBytes,
   createBuffer,
   hexToBytes,
   utf8ToBytes,
 } from "../Buffer.js";
 import {
-  CreateRandomBytesDep,
   EncryptionKey,
   padmePaddingLength,
+  RandomBytesDep,
   SymmetricCryptoDecryptError,
   SymmetricCryptoDep,
 } 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 {
   Base64Url,
-  DateIsoString,
+  base64UrlToUint8Array,
+  DateIso,
   Id,
-  idTypeValueLength,
-  JsonValueFromString,
-  maxLength,
-  NanoId,
+  IdBytes,
+  idBytesToId,
+  idBytesTypeValueLength,
+  idToIdBytes,
+  Json,
+  jsonToJsonValue,
   NonNegativeInt,
   Number,
   PositiveInt,
+  uint8ArrayToBase64Url,
 } from "../Type.js";
-import { Brand, Predicate } from "../Types.js";
+import { Predicate } from "../Types.js";
 import {
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   Owner,
   OwnerId,
-  OwnerWithWriteAccess,
-  WriteKey,
-  writeKeyLength,
+  OwnerIdBytes,
+  ownerIdToOwnerIdBytes,
+  OwnerWriteKey,
+  ownerWriteKeyLength,
 } from "./Owner.js";
 import {
-  BinaryTimestamp,
-  binaryTimestampToTimestamp,
+  BaseRange,
+  CrdtMessage,
+  DbChange,
+  EncryptedCrdtMessage,
+  EncryptedDbChange,
+  Fingerprint,
+  FingerprintRange,
+  fingerprintSize,
+  InfiniteUpperBound,
+  Range,
+  RangeType,
+  RangeUpperBound,
+  SkipRange,
+  StorageDep,
+  TimestampsRange,
+} from "./Storage.js";
+import {
   Counter,
+  eqTimestamp,
   Millis,
   NodeId,
   Timestamp,
-  timestampToBinaryTimestamp,
+  TimestampBytes,
+  timestampBytesLength,
+  timestampBytesToTimestamp,
+  timestampToTimestampBytes,
 } from "./Timestamp.js";
 
+/**
+ * MessagePack serializer for standard compatibility and compact encoding.
+ *
+ * - `variableMapSize: true` - More compact maps, ~5-10% slower encoding
+ * - `useRecords: false` - Standard MessagePack without extensions
+ */
+const packr = new Packr({ variableMapSize: true, useRecords: false });
+
 /** Maximum size of the entire protocol message in bytes. */
 export const maxProtocolMessageSize = 1_000_000 as PositiveInt;
 
@@ -190,6 +250,29 @@ export type ProtocolMessage = Uint8Array & Brand<"ProtocolMessage">;
 /** Evolu Protocol version. */
 export const protocolVersion = 0 as NonNegativeInt;
 
+export const MessageType = {
+  /** Request message from initiator (client) to non-initiator (relay). */
+  Request: 0,
+  /** Response message from non-initiator (relay) to initiator (client). */
+  Response: 1,
+  /** Broadcast message from non-initiator (relay) to subscribed clients. */
+  Broadcast: 2,
+} as const;
+
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+
+export const SubscriptionFlags = {
+  /** No subscription changes for this owner. */
+  None: 0,
+  /** Subscribe to updates for this owner. */
+  Subscribe: 1,
+  /** Unsubscribe from updates for this owner. */
+  Unsubscribe: 2,
+} as const;
+
+export type SubscriptionFlag =
+  (typeof SubscriptionFlags)[keyof typeof SubscriptionFlags];
+
 export const ProtocolErrorCode = {
   NoError: 0,
   /** A code for {@link ProtocolWriteKeyError}. */
@@ -203,168 +286,13 @@ export const ProtocolErrorCode = {
 type ProtocolErrorCode =
   (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
 
-/**
- * Evolu Protocol Storage
- *
- * The protocol is agnostic to storage implementation details—any storage can be
- * plugged in, as long as it implements this interface. Implementations must
- * handle their own errors; return values only indicates overall success or
- * failure.
- */
-export interface Storage {
-  readonly getSize: (ownerId: BinaryOwnerId) => NonNegativeInt | null;
-
-  readonly fingerprint: (
-    ownerId: BinaryOwnerId,
-    begin: NonNegativeInt,
-    end: NonNegativeInt,
-  ) => Fingerprint | null;
-
-  /**
-   * Computes fingerprints with their upper bounds in one call.
-   *
-   * This function can be replaced with many fingerprint/findLowerBound calls,
-   * but implementations can leverage it for batching and more efficient
-   * fingerprint computation.
-   */
-  readonly fingerprintRanges: (
-    ownerId: BinaryOwnerId,
-    buckets: ReadonlyArray<NonNegativeInt>,
-    upperBound?: RangeUpperBound,
-  ) => ReadonlyArray<FingerprintRange> | null;
-
-  readonly findLowerBound: (
-    ownerId: BinaryOwnerId,
-    begin: NonNegativeInt,
-    end: NonNegativeInt,
-    upperBound: RangeUpperBound,
-  ) => NonNegativeInt | null;
-
-  readonly iterate: (
-    ownerId: BinaryOwnerId,
-    begin: NonNegativeInt,
-    end: NonNegativeInt,
-    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`.
-   */
-  readonly validateWriteKey: (
-    ownerId: BinaryOwnerId,
-    writeKey: WriteKey,
-  ) => boolean;
-
-  /** Write encrypted {@link CrdtMessage}s to storage. */
-  readonly writeMessages: (
-    ownerId: BinaryOwnerId,
-    messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>,
-  ) => boolean;
-
-  /** Read encrypted {@link DbChange}s from storage. */
-  readonly readDbChange: (
-    ownerId: BinaryOwnerId,
-    timestamp: BinaryTimestamp,
-  ) => EncryptedDbChange | null;
-}
-
-export interface StorageDep {
-  readonly storage: Storage;
-}
-
-/** An encrypted {@link CrdtMessage}. */
-export interface EncryptedCrdtMessage {
-  readonly timestamp: Timestamp;
-  readonly change: EncryptedDbChange;
-}
-
-/** Encrypted DbChange */
-export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
-
-/**
- * A CRDT message that combines a unique {@link Timestamp} with a
- * {@link DbChange}.
- */
-export interface CrdtMessage {
-  readonly timestamp: Timestamp;
-  readonly change: DbChange;
-}
-
-/**
- * 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 RangeType = {
-  Fingerprint: 1,
-  Skip: 0,
-  Timestamps: 2,
-} as const;
-
-export type RangeType = (typeof RangeType)[keyof typeof RangeType];
-
-export const InfiniteUpperBound = Symbol("InfiniteUpperBound");
-export type InfiniteUpperBound = typeof InfiniteUpperBound;
-
-/**
- * Union type for Range's upperBound: either a {@link BinaryTimestamp} or
- * {@link InfiniteUpperBound}.
- */
-export type RangeUpperBound = BinaryTimestamp | InfiniteUpperBound;
-
-interface BaseRange {
-  readonly upperBound: RangeUpperBound;
-}
-
-export interface SkipRange extends BaseRange {
-  readonly type: typeof RangeType.Skip;
-}
-
-export interface FingerprintRange extends BaseRange {
-  readonly type: typeof RangeType.Fingerprint;
-  readonly fingerprint: Fingerprint;
-}
-
-/**
- * A cryptographic hash used for efficiently comparing collections of
- * {@link BinaryTimestamp}s.
- *
- * It consists of the first {@link fingerprintSize} bytes of the SHA-256 hash of
- * one or more timestamps.
- */
-export type Fingerprint = Uint8Array & Brand<"Fingerprint">;
-
-export const fingerprintSize = 12 as NonNegativeInt;
-
-/** A fingerprint of an empty range. */
-export const zeroFingerprint = new Uint8Array(fingerprintSize) as Fingerprint;
-
-export interface TimestampsRange extends BaseRange {
-  readonly type: typeof RangeType.Timestamps;
-  readonly timestamps: ReadonlyArray<BinaryTimestamp>;
-}
-
-export interface TimestampsRangeWithTimestampsBuffer extends BaseRange {
-  readonly type: typeof RangeType.Timestamps;
-  readonly timestamps: TimestampsBuffer;
-}
-
-export type Range = SkipRange | FingerprintRange | TimestampsRange;
-
 export type ProtocolError =
   | ProtocolUnsupportedVersionError
   | ProtocolInvalidDataError
   | ProtocolWriteKeyError
   | ProtocolWriteError
-  | ProtocolSyncError;
+  | ProtocolSyncError
+  | ProtocolTimestampMismatchError;
 
 /** Base interface for all protocol errors. */
 export interface ProtocolErrorBase {
@@ -389,7 +317,7 @@ export interface ProtocolInvalidDataError {
   readonly error: unknown;
 }
 
-/** Error when a {@link WriteKey} is invalid, missing, or fails validation. */
+/** Error when a {@link OwnerWriteKey} is invalid, missing, or fails validation. */
 export interface ProtocolWriteKeyError extends ProtocolErrorBase {
   readonly type: "ProtocolWriteKeyError";
 }
@@ -410,6 +338,17 @@ export interface ProtocolSyncError extends ProtocolErrorBase {
   readonly type: "ProtocolSyncError";
 }
 
+/**
+ * Error when embedded timestamp doesn't match expected timestamp in
+ * EncryptedDbChange. Indicates potential tampering or corruption of CRDT
+ * messages.
+ */
+export interface ProtocolTimestampMismatchError {
+  readonly type: "ProtocolTimestampMismatchError";
+  readonly expected: Timestamp;
+  readonly embedded: Timestamp;
+}
+
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
@@ -418,13 +357,14 @@ export interface ProtocolSyncError extends ProtocolErrorBase {
  * unidirectional and stateless transports.
  */
 export const createProtocolMessageFromCrdtMessages =
-  (deps: SymmetricCryptoDep & CreateRandomBytesDep) =>
+  (deps: RandomBytesDep & SymmetricCryptoDep) =>
   (
-    owner: OwnerWithWriteAccess,
+    owner: Owner,
     messages: NonEmptyReadonlyArray<CrdtMessage>,
     maxSize?: PositiveInt,
   ): ProtocolMessage => {
     const buffer = createProtocolMessageBuffer(owner.id, {
+      messageType: MessageType.Request,
       totalMaxSize: maxSize ?? maxProtocolMessageSize,
       writeKey: owner.writeKey,
     });
@@ -433,7 +373,7 @@ export const createProtocolMessageFromCrdtMessages =
 
     for (const message of messages) {
       const change = encodeAndEncryptDbChange(deps)(
-        message.change,
+        message,
         owner.encryptionKey,
       );
       const encryptedCrdtMessage = { timestamp: message.timestamp, change };
@@ -461,7 +401,7 @@ export const createProtocolMessageFromCrdtMessages =
        * For now, using a random fingerprint avoids extra complexity and is good
        * enough for this case.
        */
-      const randomFingerprint = deps.createRandomBytes(
+      const randomFingerprint = deps.randomBytes.create(
         fingerprintSize,
       ) as unknown as Fingerprint;
 
@@ -479,16 +419,22 @@ export const createProtocolMessageFromCrdtMessages =
 /** Creates a {@link ProtocolMessage} for sync. */
 export const createProtocolMessageForSync =
   (deps: StorageDep) =>
-  (ownerId: OwnerId): ProtocolMessage | null => {
-    const buffer = createProtocolMessageBuffer(ownerId);
-    const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
+  (
+    ownerId: OwnerId,
+    subscriptionFlag?: SubscriptionFlag,
+  ): ProtocolMessage | null => {
+    const buffer = createProtocolMessageBuffer(ownerId, {
+      messageType: MessageType.Request,
+      subscriptionFlag: subscriptionFlag ?? SubscriptionFlags.None,
+    });
+    const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
-    const size = deps.storage.getSize(binaryOwnerId);
+    const size = deps.storage.getSize(ownerIdBytes);
     // Errors are handled by the storage.
     if (size == null) return null;
 
     splitRange(deps)(
-      binaryOwnerId,
+      ownerIdBytes,
       0 as NonNegativeInt,
       size,
       InfiniteUpperBound,
@@ -498,6 +444,14 @@ export const createProtocolMessageForSync =
     return buffer.unwrap();
   };
 
+export const createProtocolMessageForUnsubscribe = (
+  ownerId: OwnerId,
+): ProtocolMessage =>
+  createProtocolMessageBuffer(ownerId, {
+    messageType: MessageType.Request,
+    subscriptionFlag: SubscriptionFlags.Unsubscribe,
+  }).unwrap();
+
 /**
  * Mutable builder for constructing {@link ProtocolMessage} respecting size
  * limits.
@@ -525,16 +479,25 @@ 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 messageType: typeof MessageType.Request;
+        readonly writeKey?: OwnerWriteKey;
+        readonly subscriptionFlag?: SubscriptionFlag;
+      }
+    | {
+        readonly messageType: typeof MessageType.Response;
+        readonly errorCode: ProtocolErrorCode;
+      }
+    | {
+        readonly messageType: typeof MessageType.Broadcast;
+      }
+  ),
 ): ProtocolMessageBuffer => {
   const {
-    errorCode,
-    writeKey,
     totalMaxSize = maxProtocolMessageSize,
     rangesMaxSize = maxProtocolMessageRangesSize,
     version = protocolVersion,
@@ -554,8 +517,21 @@ export const createProtocolMessageBuffer = (
   };
 
   encodeNonNegativeInt(buffers.header, version);
-  buffers.header.extend(ownerIdToBinaryOwnerId(ownerId));
-  if (errorCode != null) buffers.header.extend([errorCode]);
+  buffers.header.extend(ownerIdToOwnerIdBytes(ownerId));
+  buffers.header.extend([options.messageType]);
+
+  if (options.messageType === MessageType.Request) {
+    if (!options.writeKey) {
+      buffers.header.extend([0]);
+    } else {
+      buffers.header.extend([1]);
+      buffers.header.extend(options.writeKey);
+    }
+    const subscriptionFlag = options.subscriptionFlag ?? SubscriptionFlags.None;
+    buffers.header.extend([subscriptionFlag]);
+  } else if (options.messageType === MessageType.Response) {
+    buffers.header.extend([options.errorCode]);
+  }
 
   let isLastRangeInfinite = false;
 
@@ -567,10 +543,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
@@ -639,10 +612,15 @@ export const createProtocolMessageBuffer = (
     },
 
     addRange: (range) => {
+      assert(
+        options.messageType !== MessageType.Broadcast,
+        "Cannot add a range into broadcast message",
+      );
       assert(
         !isLastRangeInfinite,
         "Cannot add a range after an InfiniteUpperBound range",
       );
+
       isLastRangeInfinite = range.upperBound === InfiniteUpperBound;
 
       /**
@@ -652,7 +630,7 @@ export const createProtocolMessageBuffer = (
        */
       if (range.upperBound !== InfiniteUpperBound)
         buffers.ranges.timestamps.add(
-          binaryTimestampToTimestamp(range.upperBound),
+          timestampBytesToTimestamp(range.upperBound),
         );
       else {
         buffers.ranges.timestamps.addInfinite();
@@ -685,8 +663,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);
@@ -701,6 +677,11 @@ export const createProtocolMessageBuffer = (
   };
 };
 
+export interface TimestampsRangeWithTimestampsBuffer extends BaseRange {
+  readonly type: typeof RangeType.Timestamps;
+  readonly timestamps: TimestampsBuffer;
+}
+
 export interface TimestampsBuffer {
   readonly add: (timestamp: Timestamp) => void;
   readonly addInfinite: () => void;
@@ -802,7 +783,7 @@ const createRunLengthEncoder = <T>(
 };
 
 export interface ApplyProtocolMessageAsClientOptions {
-  getWriteKey?: (ownerId: OwnerId) => WriteKey | null;
+  getWriteKey?: (ownerId: OwnerId) => OwnerWriteKey | null;
 
   /** For testing purposes only; should not be used in production. */
   version?: NonNegativeInt;
@@ -811,33 +792,53 @@ export interface ApplyProtocolMessageAsClientOptions {
   rangesMaxSize?: PositiveInt;
 }
 
+/**
+ * Result type for {@link applyProtocolMessageAsClient} that distinguishes
+ * between responses to client requests and broadcast messages.
+ */
+export type ApplyProtocolMessageAsClientResult =
+  | { readonly type: "response"; readonly message: ProtocolMessage }
+  | { readonly type: "no-response" }
+  | { readonly type: "broadcast" };
+
 export const applyProtocolMessageAsClient =
   (deps: StorageDep) =>
-  (
+  async (
     inputMessage: Uint8Array,
-    {
-      getWriteKey,
-      version = protocolVersion,
-      totalMaxSize,
-      rangesMaxSize,
-    }: ApplyProtocolMessageAsClientOptions = {},
-  ): Result<ProtocolMessage | null, ProtocolError> =>
-    tryDecodeProtocolData<ProtocolMessage | null, ProtocolError>(
-      inputMessage,
-      (input) => {
-        const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
-
-        if (requestedVersion !== version) {
-          return err<ProtocolUnsupportedVersionError>({
-            type: "ProtocolUnsupportedVersionError",
-            unsupportedVersion: requestedVersion,
-            isInitiator: version < requestedVersion,
-            ownerId,
-          });
-        }
+    options: ApplyProtocolMessageAsClientOptions = {},
+  ): Promise<
+    Result<
+      ApplyProtocolMessageAsClientResult,
+      | ProtocolInvalidDataError
+      | ProtocolSyncError
+      | ProtocolUnsupportedVersionError
+      | ProtocolWriteError
+      | ProtocolWriteKeyError
+    >
+  > => {
+    // try-catch instead of Result for performance and stacktraces
+    try {
+      const input = createBuffer(inputMessage);
+      const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
+      const version = options.version ?? protocolVersion;
 
-        const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
+      if (requestedVersion !== version) {
+        return err<ProtocolUnsupportedVersionError>({
+          type: "ProtocolUnsupportedVersionError",
+          unsupportedVersion: requestedVersion,
+          isInitiator: version < requestedVersion,
+          ownerId,
+        });
+      }
+
+      const messageType = input.shift() as MessageType;
+      assert(
+        messageType === MessageType.Response ||
+          messageType === MessageType.Broadcast,
+        "Invalid MessageType",
+      );
 
+      if (messageType === MessageType.Response) {
         const errorCode = input.shift() as ProtocolErrorCode;
         if (errorCode !== ProtocolErrorCode.NoError) {
           switch (errorCode) {
@@ -862,34 +863,69 @@ export const applyProtocolMessageAsClient =
               );
           }
         }
+      }
 
-        const messages = decodeMessages(input);
+      const messages = decodeMessages(input);
+      const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
-        if (
-          isNonEmptyReadonlyArray(messages) &&
-          !deps.storage.writeMessages(binaryOwnerId, messages)
-        ) {
-          return ok(null);
-        }
+      if (
+        isNonEmptyReadonlyArray(messages) &&
+        !(await deps.storage.writeMessages(ownerIdBytes, messages))
+      ) {
+        return ok({ type: "no-response" });
+      }
 
-        if (!getWriteKey) return ok(null);
-        const writeKey = getWriteKey(ownerId);
-        if (writeKey == null) return ok(null);
+      // Now: No writeKey, no sync.
+      // TODO: Allow to sync SharedReadonlyOwner
+      // Without local changes, writeKey will not be required.
+      // With local changes, writeKey will be required and if not provided,
+      // the sync will stop.
+      const writeKey = options.getWriteKey?.(ownerId);
+      if (writeKey == null) {
+        return ok({ type: "no-response" });
+      }
 
-        const output = createProtocolMessageBuffer(ownerId, {
-          writeKey,
-          totalMaxSize,
-          rangesMaxSize,
-        });
+      if (messageType === MessageType.Broadcast) {
+        return ok({ type: "broadcast" });
+      }
 
-        return sync(deps)("initiator", input, output, binaryOwnerId);
-      },
-    );
+      const ranges = decodeRanges(input);
+
+      if (!isNonEmptyReadonlyArray(ranges)) {
+        return ok({ type: "no-response" });
+      }
+
+      const output = createProtocolMessageBuffer(ownerId, {
+        messageType: MessageType.Request,
+        writeKey,
+        totalMaxSize: options.totalMaxSize,
+        rangesMaxSize: options.rangesMaxSize,
+      });
+
+      const syncResult = sync(deps)(ranges, output, ownerIdBytes);
+
+      // Client sync error (handled via Storage) or no changes.
+      if (!syncResult.ok || !syncResult.value) {
+        return ok({ type: "no-response" });
+      }
+
+      return ok({ type: "response", message: output.unwrap() });
+    } catch (error) {
+      return err<ProtocolInvalidDataError>({
+        type: "ProtocolInvalidDataError",
+        data: inputMessage,
+        error,
+      });
+    }
+  };
 
 export interface ApplyProtocolMessageAsRelayOptions {
   /** To subscribe an owner for broadcasting. */
   subscribe?: (ownerId: OwnerId) => void;
 
+  /** To unsubscribe an owner from broadcasting. */
+  unsubscribe?: (ownerId: OwnerId) => void;
+
   /** To broadcast a protocol message to all subscribers. */
   broadcast?: (ownerId: OwnerId, message: ProtocolMessage) => void;
 
@@ -897,106 +933,174 @@ export interface ApplyProtocolMessageAsRelayOptions {
   rangesMaxSize?: PositiveInt;
 }
 
+/**
+ * Result type for {@link applyProtocolMessageAsRelay}.
+ *
+ * Unlike {@link ApplyProtocolMessageAsClientResult}, relays always respond with
+ * a message to provide sync completion feedback. This ensures the initiator can
+ * reliably detect when synchronization is complete, even when there's nothing
+ * to sync. Clients may choose not to respond in certain cases (like when they
+ * receive broadcast messages or when they lack a write key for syncing).
+ */
+export interface ApplyProtocolMessageAsRelayResult {
+  readonly type: "response";
+  readonly message: ProtocolMessage;
+}
+
 export const applyProtocolMessageAsRelay =
   (deps: StorageDep) =>
-  (
+  async (
     inputMessage: Uint8Array,
-    {
-      subscribe,
-      broadcast,
-      totalMaxSize,
-      rangesMaxSize,
-    }: ApplyProtocolMessageAsRelayOptions = {},
+    options: ApplyProtocolMessageAsRelayOptions = {},
     /** For testing purposes only; should not be used in production. */
     version = protocolVersion,
-  ): Result<ProtocolMessage | null, ProtocolInvalidDataError> =>
-    tryDecodeProtocolData(inputMessage, (input) => {
-      const requestedVersion = decodeNonNegativeInt(input);
-      const ownerId = decodeOwnerId(input);
-      const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
+  ): Promise<
+    Result<ApplyProtocolMessageAsRelayResult, ProtocolInvalidDataError>
+  > => {
+    // try-catch instead of Result for performance and stacktraces
+    try {
+      const input = createBuffer(inputMessage);
+      const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
+      const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
       if (requestedVersion !== version) {
         // Non-initiator responds with its version and ownerId.
         const output = createBuffer();
         encodeNonNegativeInt(output, version);
-        output.extend(binaryOwnerId);
-        return ok(output.unwrap() as ProtocolMessage);
+        output.extend(ownerIdBytes);
+        return ok({
+          type: "response",
+          message: output.unwrap() as ProtocolMessage,
+        });
       }
 
-      subscribe?.(ownerId);
+      const messageType = input.shift() as MessageType;
+      assert(messageType === MessageType.Request, "Invalid MessageType");
 
-      const messages = decodeMessages(input);
+      const hasWriteKey = input.shift();
+      let writeKey: OwnerWriteKey | undefined;
 
-      if (isNonEmptyReadonlyArray(messages)) {
-        const messagesEnd = inputMessage.length - input.getLength();
-        const writeKey = input.shiftN(writeKeyLength) as WriteKey;
+      if (hasWriteKey === 1) {
+        writeKey = input.shiftN(ownerWriteKeyLength) as OwnerWriteKey;
+      }
 
-        const writeKeyIsValid = deps.storage.validateWriteKey(
-          binaryOwnerId,
-          writeKey,
-        );
+      const subscriptionFlag = input.shift() as SubscriptionFlag;
+
+      switch (subscriptionFlag) {
+        case SubscriptionFlags.Subscribe:
+          options.subscribe?.(ownerId);
+          break;
+        case SubscriptionFlags.Unsubscribe:
+          options.unsubscribe?.(ownerId);
+          break;
+        case SubscriptionFlags.None:
+          break;
+      }
 
-        if (!writeKeyIsValid)
-          return ok(
-            createProtocolMessageBuffer(ownerId, {
+      if (writeKey) {
+        const isValid = deps.storage.validateWriteKey(ownerIdBytes, writeKey);
+        if (!isValid) {
+          return ok({
+            type: "response",
+            message: createProtocolMessageBuffer(ownerId, {
+              messageType: MessageType.Response,
               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;
+      const messages = decodeMessages(input);
 
-          broadcast(ownerId, broadcastMessage);
+      if (isNonEmptyReadonlyArray(messages)) {
+        if (!writeKey) {
+          return ok({
+            type: "response",
+            message: createProtocolMessageBuffer(ownerId, {
+              messageType: MessageType.Response,
+              errorCode: ProtocolErrorCode.WriteKeyError,
+            }).unwrap(),
+          });
         }
 
-        if (!deps.storage.writeMessages(binaryOwnerId, messages))
-          return ok(
-            createProtocolMessageBuffer(ownerId, {
+        /**
+         * Broadcast messages to all subscribed devices. This ensures real-time
+         * synchronization between clients.
+         *
+         * When a relay's database is deleted or clients migrate to a new relay
+         * (without data migration), clients will sync their data to the relay,
+         * and the relay will broadcast those messages to other connected
+         * clients. Those clients may receive messages they already have, but
+         * this is safe because `applyMessages` is idempotent. As the relay
+         * becomes more synchronized with clients over time, fewer duplicate
+         * messages will be broadcasted.
+         */
+        if (options.broadcast) {
+          const broadcastBuffer = createProtocolMessageBuffer(ownerId, {
+            messageType: MessageType.Broadcast,
+            totalMaxSize: options.totalMaxSize,
+            rangesMaxSize: options.rangesMaxSize,
+            version,
+          });
+          for (const message of messages) {
+            broadcastBuffer.addMessage(message);
+          }
+          options.broadcast(ownerId, broadcastBuffer.unwrap());
+        }
+
+        if (!(await deps.storage.writeMessages(ownerIdBytes, messages))) {
+          return ok({
+            type: "response",
+            message: createProtocolMessageBuffer(ownerId, {
+              messageType: MessageType.Response,
               errorCode: ProtocolErrorCode.WriteError,
             }).unwrap(),
-          );
+          });
+        }
       }
 
+      const ranges = decodeRanges(input);
+
       const output = createProtocolMessageBuffer(ownerId, {
+        messageType: MessageType.Response,
         errorCode: ProtocolErrorCode.NoError,
-        totalMaxSize,
-        rangesMaxSize,
+        totalMaxSize: options.totalMaxSize,
+        rangesMaxSize: options.rangesMaxSize,
       });
 
-      return sync(deps)("non-initiator", input, output, binaryOwnerId);
-    });
+      // Non-initiators always respond to provide sync completion feedback,
+      // even when there's nothing to sync.
+      if (!isNonEmptyReadonlyArray(ranges)) {
+        return ok({ type: "response", message: output.unwrap() });
+      }
 
-/**
- * Wraps Evolu Protocol decoding functions, which use exceptions instead of
- * {@link Result} to provide stack traces for debugging and reduce allocation
- * overhead in success cases.
- */
-const tryDecodeProtocolData = <T, E>(
-  data: Uint8Array,
-  callback: (buffer: Buffer) => Result<T, E | ProtocolInvalidDataError>,
-) => {
-  try {
-    return callback(createBuffer(data));
-  } catch (error: unknown) {
-    if (error instanceof ProtocolDecodeError || error instanceof BufferError)
+      const syncResult = sync(deps)(ranges, output, ownerIdBytes);
+
+      const message = syncResult.ok
+        ? output.unwrap()
+        : createProtocolMessageBuffer(ownerId, {
+            messageType: MessageType.Response,
+            errorCode: syncResult.error,
+          }).unwrap();
+
+      // Non-initiators always respond to provide sync completion feedback,
+      return ok({ type: "response", message });
+    } catch (error) {
       return err<ProtocolInvalidDataError>({
         type: "ProtocolInvalidDataError",
-        data,
+        data: inputMessage,
         error,
       });
-
-    throw 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);
+  const ownerId = decodeId(input) as OwnerId;
   return [version, ownerId];
 };
 
@@ -1031,34 +1135,14 @@ const decodeMessages = (
 const sync =
   (deps: StorageDep) =>
   (
-    role: "initiator" | "non-initiator",
-    input: Buffer,
+    ranges: NonEmptyReadonlyArray<Range>,
     output: ProtocolMessageBuffer,
-    ownerId: BinaryOwnerId,
-  ): Result<ProtocolMessage | null, never> => {
-    const ranges = decodeRanges(input);
-
-    if (!isNonEmptyReadonlyArray(ranges)) {
-      // Nothing to sync.
-      return ok(null);
-    }
-
-    const binaryOwnerId = binaryOwnerIdToOwnerId(ownerId);
+    ownerIdBytes: OwnerIdBytes,
+  ): Result<boolean, typeof ProtocolErrorCode.SyncError> => {
     const outputInitialSize = output.getSize();
 
-    const syncFail = () => {
-      // Only the relay (non-initiator) reports sync errors, not the client (initiator).
-      if (role === "initiator") {
-        return ok(null);
-      }
-      const message = createProtocolMessageBuffer(binaryOwnerId, {
-        errorCode: ProtocolErrorCode.SyncError,
-      });
-      return ok(message.unwrap());
-    };
-
-    const storageSize = deps.storage.getSize(ownerId);
-    if (storageSize == null) return syncFail();
+    const storageSize = deps.storage.getSize(ownerIdBytes);
+    if (storageSize == null) return err(ProtocolErrorCode.SyncError);
 
     let prevUpperBound: RangeUpperBound | null = null;
     let prevIndex = 0 as NonNegativeInt;
@@ -1098,7 +1182,11 @@ const sync =
     const addFingerprintForRemainingRange = (
       begin: NonNegativeInt,
     ): boolean => {
-      const fingerprint = deps.storage.fingerprint(ownerId, begin, storageSize);
+      const fingerprint = deps.storage.fingerprint(
+        ownerIdBytes,
+        begin,
+        storageSize,
+      );
       if (!fingerprint) return false;
       // There is always a space for a ramaining range.
       output.addRange({
@@ -1114,12 +1202,12 @@ const sync =
 
       const lower = prevIndex;
       let upper = deps.storage.findLowerBound(
-        ownerId,
+        ownerIdBytes,
         prevIndex,
         storageSize,
         currentUpperBound,
       );
-      if (upper == null) return syncFail();
+      if (upper == null) return err(ProtocolErrorCode.SyncError);
 
       switch (range.type) {
         case RangeType.Skip: {
@@ -1129,11 +1217,11 @@ const sync =
 
         case RangeType.Fingerprint: {
           const ourFingerprint = deps.storage.fingerprint(
-            ownerId,
+            ownerIdBytes,
             lower,
             upper,
           );
-          if (ourFingerprint == null) return syncFail();
+          if (ourFingerprint == null) return err(ProtocolErrorCode.SyncError);
 
           if (eqArrayNumber(range.fingerprint, ourFingerprint)) {
             skipRange(range);
@@ -1141,15 +1229,16 @@ const sync =
             if (output.canSplitRange()) {
               coalesceSkipsBeforeAdd();
               splitRange(deps)(
-                ownerId,
+                ownerIdBytes,
                 lower,
                 upper,
                 currentUpperBound,
                 output,
               );
             } else {
-              if (!addFingerprintForRemainingRange(upper)) return syncFail();
-              return ok(output.unwrap());
+              return addFingerprintForRemainingRange(upper)
+                ? ok(true)
+                : err(ProtocolErrorCode.SyncError);
             }
           }
           break;
@@ -1163,45 +1252,53 @@ const sync =
           );
           const ourTimestamps = createTimestampsBuffer();
 
-          let storageError = false as boolean;
+          let cantReadDbChange = false as boolean;
           let exceeded = false as boolean;
 
-          deps.storage.iterate(ownerId, lower, upper, (timestamp, index) => {
-            const timestampString = timestamp.join();
-            const timestampBinary = binaryTimestampToTimestamp(timestamp);
-
-            let message: EncryptedCrdtMessage | null = null;
+          deps.storage.iterate(
+            ownerIdBytes,
+            lower,
+            upper,
+            (timestamp, index) => {
+              const timestampString = timestamp.join();
+              const timestampBinary = timestampBytesToTimestamp(timestamp);
+
+              let message: EncryptedCrdtMessage | null = null;
+
+              if (timestampsWeNeed.has(timestampString)) {
+                timestampsWeNeed.delete(timestampString);
+              } else {
+                const dbChange = deps.storage.readDbChange(
+                  ownerIdBytes,
+                  timestamp,
+                );
+                if (dbChange == null) {
+                  cantReadDbChange = true;
+                  return false;
+                }
+                message = {
+                  timestamp: timestampBinary,
+                  change: dbChange,
+                };
+              }
 
-            if (timestampsWeNeed.has(timestampString)) {
-              timestampsWeNeed.delete(timestampString);
-            } else {
-              const dbChange = deps.storage.readDbChange(ownerId, timestamp);
-              if (dbChange == null) {
-                storageError = true;
+              if (
+                !output.canAddTimestampsRangeAndMessage(ourTimestamps, message)
+              ) {
+                exceeded = true;
+                endBound = timestamp;
+                upper = index;
                 return false;
               }
-              message = {
-                timestamp: timestampBinary,
-                change: dbChange,
-              };
-            }
 
-            if (
-              !output.canAddTimestampsRangeAndMessage(ourTimestamps, message)
-            ) {
-              exceeded = true;
-              endBound = timestamp;
-              upper = index;
-              return false;
-            }
-
-            ourTimestamps.add(timestampBinary);
-            if (message) output.addMessage(message);
-            return true;
-          });
+              ourTimestamps.add(timestampBinary);
+              if (message) output.addMessage(message);
+              return true;
+            },
+          );
 
-          if (storageError) {
-            return syncFail();
+          if (cantReadDbChange) {
+            return err(ProtocolErrorCode.SyncError);
           }
 
           const addRange = () => {
@@ -1216,9 +1313,9 @@ const sync =
           if (exceeded) {
             addRange();
             if (!addFingerprintForRemainingRange(upper)) {
-              return syncFail();
+              return err(ProtocolErrorCode.SyncError);
             }
-            return ok(output.unwrap());
+            return ok(true);
           }
 
           // If we need something, we have to respond with our timestamps.
@@ -1238,13 +1335,14 @@ const sync =
 
     // If all ranges were skipped, there are no changes and sync is complete.
     const hasChange = output.getSize() > outputInitialSize;
-    return ok(hasChange ? output.unwrap() : null);
+
+    return ok(hasChange);
   };
 
 const splitRange =
   (deps: StorageDep) =>
   (
-    ownerId: BinaryOwnerId,
+    ownerId: OwnerIdBytes,
     lower: NonNegativeInt,
     upper: NonNegativeInt,
     upperBound: RangeUpperBound,
@@ -1265,7 +1363,7 @@ const splitRange =
         0 as NonNegativeInt,
         itemCount,
         (timestamp) => {
-          range.timestamps.add(binaryTimestampToTimestamp(timestamp));
+          range.timestamps.add(timestampBytesToTimestamp(timestamp));
           return true;
         },
       );
@@ -1324,7 +1422,7 @@ const decodeRanges = (buffer: Buffer): ReadonlyArray<Range> => {
   for (let i = 0; i < rangesCount; i++) {
     const upperBound =
       i < timestampsCount
-        ? timestampToBinaryTimestamp(timestamps[i])
+        ? timestampToTimestampBytes(timestamps[i])
         : InfiniteUpperBound;
 
     const rangeType = rangeTypes[i];
@@ -1346,7 +1444,7 @@ const decodeRanges = (buffer: Buffer): ReadonlyArray<Range> => {
 
       case RangeType.Timestamps: {
         const timestamps = decodeTimestamps(buffer).map(
-          timestampToBinaryTimestamp,
+          timestampToTimestampBytes,
         );
         ranges.push({
           type: RangeType.Timestamps,
@@ -1374,7 +1472,7 @@ const decodeTimestamps = (
   for (let i = 0; i < length; i++) {
     const deltaMillis = decodeNonNegativeInt(buffer);
     const millis = Millis.from(previousMillis + deltaMillis);
-    if (!millis.ok) throw new Error(millis.error.type);
+    if (!millis.ok) throw new ProtocolDecodeError(millis.error.type);
     millises.push(millis.value);
     previousMillis = millis.value;
   }
@@ -1383,7 +1481,7 @@ const decodeTimestamps = (
   let counterIndex = 0;
   while (counterIndex < length) {
     const counter = Counter.from(decodeNonNegativeInt(buffer));
-    if (!counter.ok) throw new Error(counter.error.type);
+    if (!counter.ok) throw new ProtocolDecodeError(counter.error.type);
     const runLength = decodeNonNegativeInt(buffer);
     for (let i = 0; i < runLength; i++) {
       counters.push(counter.value);
@@ -1414,134 +1512,31 @@ const decodeTimestamps = (
   return timestamps;
 };
 
-/** Binary representation of {@link Id}. */
-export type BinaryId = Uint8Array & Brand<"BinaryId">;
-
-export const binaryIdLength = 16 as NonNegativeInt;
-
-export const idToBinaryId = (id: Id): BinaryId =>
-  base64Url256ToBytes(id) as BinaryId;
-
-export const binaryIdToId = (binaryId: BinaryId): Id =>
-  decodeId(createBuffer(binaryId));
-
-/** Binary representation of {@link OwnerId}. */
-export type BinaryOwnerId = Uint8Array & Brand<"BinaryOwnerId">;
-
-export const ownerIdToBinaryOwnerId = (ownerId: OwnerId): BinaryOwnerId =>
-  base64Url256ToBytes(ownerId) as 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.
- */
-export type Base64Url256Variant = Base64Url256 | Id | NanoId | OwnerId;
-
-/**
- * Alphabet used for Base64Url encoding. This is copied from the `nanoid`
- * library to avoid dependency on a specific version of `nanoid`.
- */
-const urlAlphabet =
-  "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
-
-/**
- * Converts a Base64Url string to a Uint8Array for binary storage. This encoding
- * is more space-efficient than UTF-8 for Base64Url strings.
- */
-export const base64Url256ToBytes = (
-  string: Base64Url256Variant,
-): globalThis.Uint8Array => {
-  const totalBits = string.length * 6; // 6 bits per character
-  const byteLength = Math.ceil(totalBits / 8);
-  const value = new globalThis.Uint8Array(byteLength);
-
-  let bitBuffer = 0;
-  let bitsInBuffer = 0;
-  let byteIndex = 0;
-
-  for (const char of string) {
-    const charValue = urlAlphabet.indexOf(char);
-    bitBuffer = (bitBuffer << 6) | charValue;
-    bitsInBuffer += 6;
-    while (bitsInBuffer >= 8) {
-      bitsInBuffer -= 8;
-      value[byteIndex++] = (bitBuffer >> bitsInBuffer) & 0xff;
-    }
-  }
-
-  if (bitsInBuffer > 0 && byteIndex < byteLength) {
-    value[byteIndex] = (bitBuffer << (8 - bitsInBuffer)) & 0xff;
-  }
-
-  return value;
+const decodeId = (buffer: Buffer): Id => {
+  const bytes = buffer.shiftN(idBytesTypeValueLength);
+  return idBytesToId(bytes as IdBytes);
 };
 
-export const decodeBase64Url256 = (
-  buffer: Buffer,
-  stringLength: number,
-): Base64Url256Variant => {
-  const bytes = buffer.shiftN(
-    Math.ceil((stringLength * 6) / 8) as NonNegativeInt,
-  );
-
-  let bitBuffer = 0;
-  let bitsInBuffer = 0;
-  let string = "";
-
-  for (const byte of bytes) {
-    bitBuffer = (bitBuffer << 8) | byte;
-    bitsInBuffer += 8;
-    while (bitsInBuffer >= 6) {
-      bitsInBuffer -= 6;
-      if (string.length < stringLength) {
-        const charValue = (bitBuffer >> bitsInBuffer) & 0x3f;
-        if (charValue < 0 || charValue >= urlAlphabet.length) {
-          throw new ProtocolDecodeError("invalid charValue");
-        }
-        string += urlAlphabet[charValue];
-      }
-    }
-  }
-
-  const result = Base64Url256.from(string);
-  if (!result.ok) throw new ProtocolDecodeError(result.error.type);
-
-  return result.value;
-};
-
-const decodeId = (buffer: Buffer): Id =>
-  decodeBase64Url256(buffer, idTypeValueLength) as Id;
-
-/** Not all 16 bytes are valid {@link OwnerId}. */
-const decodeOwnerId = (buffer: Buffer): OwnerId => decodeId(buffer) as OwnerId;
-
 /**
  * Evolu uses MessagePack to handle all number variants except for
  * NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
  */
 export const encodeNumber = (buffer: Buffer, number: number): void => {
-  buffer.extend(pack(number));
+  buffer.extend(packr.pack(number));
 };
 
 export const decodeNumber = (buffer: Buffer): number => {
   let number: unknown;
   let end: unknown;
 
-  unpackMultiple(buffer.unwrap(), (n, _, e) => {
-    number = n;
-    end = e;
-    return false;
-  });
+  packr.unpackMultiple(
+    buffer.unwrap(),
+    (n: unknown, _: unknown, e: unknown) => {
+      number = n;
+      end = e;
+      return false;
+    },
+  );
 
   const endResult = NonNegativeInt.fromUnknown(end);
   if (!endResult.ok) throw new ProtocolDecodeError(endResult.error.type);
@@ -1553,28 +1548,33 @@ export const decodeNumber = (buffer: Buffer): number => {
   return numberResult.value;
 };
 
-export const binaryTimestampToFingerprint = (
-  timestamp: BinaryTimestamp,
-): Fingerprint => {
-  const hash = sha256(timestamp).slice(0, fingerprintSize);
-  return hash as Fingerprint;
-};
-
 /**
  * Encodes and encrypts a {@link DbChange} using the provided owner's encryption
  * key. Returns an encrypted binary representation as {@link EncryptedDbChange}.
+ *
+ * The format includes the protocol version for backward compatibility and the
+ * timestamp for tamper-proof verification that the timestamp matches the change
+ * data.
  */
 export const encodeAndEncryptDbChange =
   (deps: SymmetricCryptoDep) =>
-  (change: DbChange, key: EncryptionKey): EncryptedDbChange => {
+  (message: CrdtMessage, key: EncryptionKey): EncryptedDbChange => {
+    const change = message.change;
     const buffer = createBuffer();
 
-    encodeBase64Url256(buffer, change.table);
+    // Encode protocol version first for backward compatibility
+    encodeNonNegativeInt(buffer, protocolVersion);
+
+    // Encode the timestamp (after version) for tamper verification
+    const timestampBytes = timestampToTimestampBytes(message.timestamp);
+    buffer.extend(timestampBytes);
 
-    buffer.extend(idToBinaryId(change.id));
+    encodeString(buffer, change.table);
+
+    buffer.extend(idToIdBytes(change.id));
 
     const entries = objectToEntries(change.values).map(
-      ([column, value]): [Base64Url256, SqliteValue] => {
+      ([column, value]): [string, SqliteValue] => {
         return [column, value];
       },
     );
@@ -1582,7 +1582,7 @@ export const encodeAndEncryptDbChange =
     encodeLength(buffer, entries);
 
     for (const [column, value] of entries) {
-      encodeBase64Url256(buffer, column);
+      encodeString(buffer, column);
       encodeSqliteValue(buffer, value);
     }
 
@@ -1604,50 +1604,80 @@ export const encodeAndEncryptDbChange =
   };
 
 /**
- * Decrypts and decodes an {@link EncryptedDbChange} using the provided owner's
- * encryption key.
+ * Decrypts and decodes an {@link EncryptedCrdtMessage} using the provided
+ * owner's encryption key. Verifies that the embedded timestamp matches the
+ * expected timestamp to ensure message integrity.
  */
 export const decryptAndDecodeDbChange =
   (deps: SymmetricCryptoDep) =>
   (
-    change: EncryptedDbChange,
+    message: EncryptedCrdtMessage,
     key: EncryptionKey,
-  ): Result<DbChange, SymmetricCryptoDecryptError | ProtocolInvalidDataError> =>
-    tryDecodeProtocolData<DbChange, SymmetricCryptoDecryptError>(
-      change,
-      (buffer) => {
-        const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
-
-        const ciphertextLength = decodeLength(buffer);
-        const ciphertext = buffer.shiftN(ciphertextLength);
-
-        const plaintextBytes = deps.symmetricCrypto.decrypt(
-          ciphertext,
-          key,
-          nonce,
-        );
-        if (!plaintextBytes.ok) return plaintextBytes;
+  ): Result<
+    DbChange,
+    | SymmetricCryptoDecryptError
+    | ProtocolInvalidDataError
+    | ProtocolTimestampMismatchError
+  > => {
+    // try-catch instead of Result for performance and stacktraces
+    try {
+      const buffer = createBuffer(message.change);
+      const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
+
+      const ciphertextLength = decodeLength(buffer);
+      const ciphertext = buffer.shiftN(ciphertextLength);
+
+      const plaintextBytes = deps.symmetricCrypto.decrypt(
+        ciphertext,
+        key,
+        nonce,
+      );
+      if (!plaintextBytes.ok) return plaintextBytes;
 
-        buffer.reset();
-        buffer.extend(plaintextBytes.value);
+      buffer.reset();
+      buffer.extend(plaintextBytes.value);
 
-        const table = decodeBase64Url256WithLength(buffer);
-        const id = decodeId(buffer);
+      // Decode version (for future compatibility, no validation needed for now)
+      decodeNonNegativeInt(buffer);
 
-        const length = decodeLength(buffer);
-        const values = Object.create(null) as Record<string, SqliteValue>;
+      // Decode and verify the embedded timestamp
+      const embeddedTimestampBytes = buffer.shiftN(timestampBytesLength);
+      const embeddedTimestamp = timestampBytesToTimestamp(
+        embeddedTimestampBytes as TimestampBytes,
+      );
 
-        for (let i = 0; i < length; i++) {
-          const column = decodeBase64Url256WithLength(buffer);
-          const value = decodeSqliteValue(buffer);
-          values[column] = value;
-        }
+      // Verify timestamp integrity
+      if (!eqTimestamp(embeddedTimestamp, message.timestamp)) {
+        return err<ProtocolTimestampMismatchError>({
+          type: "ProtocolTimestampMismatchError",
+          expected: message.timestamp,
+          embedded: embeddedTimestamp,
+        });
+      }
 
-        const dbChange = { table, id, values };
+      const table = decodeString(buffer);
+      const id = decodeId(buffer);
 
-        return ok(dbChange);
-      },
-    );
+      const length = decodeLength(buffer);
+      const values = Object.create(null) as Record<string, SqliteValue>;
+
+      for (let i = 0; i < length; i++) {
+        const column = decodeString(buffer);
+        const value = decodeSqliteValue(buffer);
+        values[column] = value;
+      }
+
+      const dbChange = { table, id, values };
+
+      return ok(dbChange);
+    } catch (error) {
+      return err<ProtocolInvalidDataError>({
+        type: "ProtocolInvalidDataError",
+        data: message.change,
+        error,
+      });
+    }
+  };
 
 /**
  * Encodes a non-negative integer into a variable-length integer format. It's
@@ -1731,19 +1761,6 @@ export const decodeNodeId = (buffer: Buffer): NodeId => {
   return bytesToHex(bytes) as NodeId;
 };
 
-export const encodeBase64Url256 = (
-  buffer: Buffer,
-  string: Base64Url256Variant,
-): void => {
-  encodeLength(buffer, string);
-  buffer.extend(base64Url256ToBytes(string));
-};
-
-export const decodeBase64Url256WithLength = (buffer: Buffer): Base64Url256 => {
-  const length = decodeLength(buffer);
-  return decodeBase64Url256(buffer, length) as Base64Url256;
-};
-
 // Small ints are encoded into ProtocolValueType, saving one byte per int.
 const isSmallInt: Predicate<number> = (value: number) =>
   value >= 0 && value < 20;
@@ -1755,20 +1772,23 @@ export const ProtocolValueType = {
   String: 20 as NonNegativeInt,
   Number: 21 as NonNegativeInt,
   Null: 22 as NonNegativeInt,
-  Binary: 23 as NonNegativeInt,
+  Bytes: 23 as NonNegativeInt,
   // We can add more types for other DBs or anything else later.
 
   // Optimized types
-  Id: 30 as NonNegativeInt,
-  Base64Url256: 31 as NonNegativeInt,
-  NonNegativeInt: 32 as NonNegativeInt,
-  Json: 33 as NonNegativeInt,
+  NonNegativeInt: 30 as NonNegativeInt,
+
+  // String optimizations
+  EmptyString: 31 as NonNegativeInt, // 1 byte vs 2 bytes (50% reduction)
+  Base64Url: 32 as NonNegativeInt,
+  Id: 33 as NonNegativeInt,
+  Json: 34 as NonNegativeInt,
 
   // new Date().toISOString()   - 24 bytes
   // encoded with fixed length  - 8 bytes
   // encode as NonNegativeInt   - 6 bytes (additional 25% reduction)
-  DateIsoWithNonNegativeTime: 34 as NonNegativeInt,
-  DateIsoWithNegativeTime: 35 as NonNegativeInt, // 9 bytes
+  DateIsoWithNonNegativeTime: 35 as NonNegativeInt,
+  DateIsoWithNegativeTime: 36 as NonNegativeInt, // 9 bytes
 
   // TODO: Operations (from 40)
   // Increment, Decrement, Patch, whatever.
@@ -1782,9 +1802,14 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
 
   switch (typeof value) {
     case "string": {
-      const dateIsoString = DateIsoString.from(value);
-      if (dateIsoString.ok) {
-        const time = new Date(dateIsoString.value).getTime();
+      if (value === "") {
+        encodeNonNegativeInt(buffer, ProtocolValueType.EmptyString);
+        return;
+      }
+
+      const dateIso = DateIso.fromParent(value);
+      if (dateIso.ok) {
+        const time = new Date(dateIso.value).getTime();
         if (NonNegativeInt.is(time)) {
           encodeNonNegativeInt(
             buffer,
@@ -1801,27 +1826,34 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
         return;
       }
 
-      const base64Url256 = Base64Url256.from(value);
-      if (base64Url256.ok) {
-        if (base64Url256.value.length === idTypeValueLength) {
-          encodeNonNegativeInt(buffer, ProtocolValueType.Id);
-          buffer.extend(base64Url256ToBytes(base64Url256.value));
-          return;
-        }
-        encodeNonNegativeInt(buffer, ProtocolValueType.Base64Url256);
-        encodeBase64Url256(buffer, base64Url256.value);
+      const id = Id.fromParent(value);
+      if (id.ok) {
+        encodeNonNegativeInt(buffer, ProtocolValueType.Id);
+        buffer.extend(idToIdBytes(id.value));
         return;
       }
 
-      const jsonValue = JsonValueFromString.fromParent(value);
-      if (jsonValue.ok) {
-        const jsonBytes = pack(jsonValue.value);
+      const json = Json.fromParent(value);
+      // Only encode as Json if it survives JSON.parse/JSON.stringify round-trip.
+      // Some valid JSON strings like "-0E0" get normalized to "0" during parsing,
+      // which would cause data corruption if we don't verify round-trip safety.
+      if (json.ok && JSON.stringify(jsonToJsonValue(json.value)) === value) {
+        const jsonBytes = packr.pack(jsonToJsonValue(json.value));
         encodeNonNegativeInt(buffer, ProtocolValueType.Json);
         encodeLength(buffer, jsonBytes);
         buffer.extend(jsonBytes);
         return;
       }
 
+      const base64Url = Base64Url.fromParent(value);
+      if (base64Url.ok) {
+        encodeNonNegativeInt(buffer, ProtocolValueType.Base64Url);
+        const bytes = base64UrlToUint8Array(base64Url.value);
+        encodeLength(buffer, bytes);
+        buffer.extend(bytes);
+        return;
+      }
+
       encodeNonNegativeInt(buffer, ProtocolValueType.String);
       encodeString(buffer, value);
       return;
@@ -1843,7 +1875,7 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
     }
   }
 
-  encodeNonNegativeInt(buffer, ProtocolValueType.Binary);
+  encodeNonNegativeInt(buffer, ProtocolValueType.Bytes);
   encodeLength(buffer, value);
   buffer.extend(value);
 };
@@ -1858,40 +1890,75 @@ export const decodeSqliteValue = (buffer: Buffer): SqliteValue => {
   switch (type) {
     case ProtocolValueType.String:
       return decodeString(buffer);
+
     case ProtocolValueType.Number:
       return decodeNumber(buffer);
+
     case ProtocolValueType.Null:
       return null;
-    case ProtocolValueType.Binary: {
+
+    case ProtocolValueType.Bytes: {
       const length = decodeLength(buffer);
       return buffer.shiftN(length);
     }
-    case ProtocolValueType.Id: {
+
+    case ProtocolValueType.Id:
       return decodeId(buffer);
-    }
-    case ProtocolValueType.Base64Url256:
-      return decodeBase64Url256WithLength(buffer);
+
     case ProtocolValueType.NonNegativeInt:
       return decodeNonNegativeInt(buffer);
+
     case ProtocolValueType.Json: {
       const length = decodeLength(buffer);
       const bytes = buffer.shiftN(length);
-      return JSON.stringify(unpack(bytes));
+      return JSON.stringify(packr.unpack(bytes));
     }
+
     case ProtocolValueType.DateIsoWithNonNegativeTime:
     case ProtocolValueType.DateIsoWithNegativeTime: {
       const time =
         type === ProtocolValueType.DateIsoWithNonNegativeTime
           ? decodeNonNegativeInt(buffer)
           : decodeNumber(buffer);
-      const dateIsoString = DateIsoString.fromParent(
-        new Date(time).toISOString(),
-      );
-      if (!dateIsoString.ok)
-        throw new ProtocolDecodeError(dateIsoString.error.type);
-      return dateIsoString.value;
+      const dateIso = DateIso.fromParent(new Date(time).toISOString());
+      if (!dateIso.ok) throw new ProtocolDecodeError(dateIso.error.type);
+      return dateIso.value;
+    }
+
+    case ProtocolValueType.EmptyString:
+      return "";
+
+    case ProtocolValueType.Base64Url: {
+      const length = decodeLength(buffer);
+      const bytes = buffer.shiftN(length);
+      return uint8ArrayToBase64Url(bytes);
     }
+
     default:
       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.");
+};