@evolu/common 6.0.1-preview.8 → 7.0.0

package/dist/src/Evolu/Protocol.js

@@ -3,29 +3,39 @@
  *
  * 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
+ * ### Message structure
  *
  * | 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**              |                           |
+ * | - 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} |                           |
@@ -33,21 +43,14 @@
  * | - {@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.
- *
- * ### WriteKey Rotation
+ * ### WriteKey validation
  *
- * When initiator's {@link WriteKeyMode} is `Rotation`, two WriteKeys are
- * present:
- *
- * 1. Current WriteKey (for validation)
- * 2. New WriteKey (to be stored)
+ * 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
  *
@@ -61,38 +64,48 @@
  * 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
+ * ### 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
+ * - {@link ProtocolWriteError}: A serious relay-side write failure occurred.
+ * - {@link ProtocolQuotaError}: Storage or billing quota exceeded.
+ * - {@link ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
- * - {@link ProtocolUnsupportedVersionError}: Protocol version mismatch.
+ * - {@link ProtocolVersionError}: 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
+ * ### 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.
+ * {@link ProtocolMessageMaxSize}. This ensures every {@link ProtocolMessage} is
+ * 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.
+ *
+ * Database mutations are limited to 640KB, which is smaller than the protocol
+ * message limit to ensure efficient sync with
+ * {@link defaultProtocolMessageRangesMaxSize}.
  *
  * ### Why Binary?
  *
@@ -100,13 +113,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.
@@ -136,81 +148,143 @@
  * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
  * over time and provide clear feedback about version mismatches.
  *
+ * ### Credible exit
+ *
+ * The protocol specification is intentionally non-configurable to ensure
+ * universal compatibility. This design allows applications (users) to switch
+ * between any compliant relay without negotiation or compatibility checks
+ * beyond version matching. Relays are generic infrastructure that any
+ * application can use interchangeably making exit from any single provider
+ * technically feasible and economically viable.
+ *
  * @module
  */
-import { sha256 } from "@noble/hashes/sha2";
-import { pack, unpack, unpackMultiple } from "msgpackr";
+/**
+ * TODO:
+ *
+ * - The client-relay naming convention in functions like
+ *   `applyProtocolMessageAsClient` and `applyProtocolMessageAsRelay` is not
+ *   ideal. In the future, clients will be able to sync directly with each other
+ *   (P2P), making the current naming misleading. Consider using
+ *   initiator/non-initiator terminology instead, and consolidate into a single
+ *   `applyProtocolMessage` function with conditional arguments to reduce code
+ *   duplication.
+ * - Replace try-catch with Result + new Error (to preserve stacktraces). Measure
+ *   Result overhead, it should be super small.
+ * - Allow clients to broadcast messages that are not persisted by relays. This
+ *   would enable real-time ephemeral data (like cursor positions, typing
+ *   indicators) to be forwarded by relays without storage overhead.
+ */
+import { Packr } from "msgpackr";
 import { isNonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
-import { BufferError, bytesToHex, bytesToUtf8, createBuffer, hexToBytes, utf8ToBytes, } from "../Buffer.js";
-import { padmePaddingLength, } from "../Crypto.js";
+import { bytesToHex, bytesToUtf8, createBuffer, hexToBytes, utf8ToBytes, } from "../Buffer.js";
+import { createPadmePadding, } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
 import { objectToEntries } from "../Object.js";
 import { err, ok } from "../Result.js";
-import { SqliteValue } from "../Sqlite.js";
-import { Base64Url, DateIsoString, Id, idTypeValueLength, JsonValueFromString, maxLength, NonNegativeInt, Number, object, record, } from "../Type.js";
-import { writeKeyLength, } from "./Owner.js";
-import { binaryTimestampToTimestamp, Counter, Millis, timestampToBinaryTimestamp, } from "./Timestamp.js";
-/** Maximum size of the entire protocol message in bytes. */
-export const maxProtocolMessageSize = 1_000_000;
-/** Maximum size of the ranges in bytes. */
-export const maxProtocolMessageRangesSize = 30_000;
+import { Base64Url, base64UrlToUint8Array, between, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Int, Json, jsonToJsonValue, NonNegativeInt, Number, PositiveInt, uint8ArrayToBase64Url, } from "../Type.js";
+import { ownerIdToOwnerIdBytes, ownerWriteKeyLength, } from "./Owner.js";
+import { DbChange, fingerprintSize, InfiniteUpperBound, RangeType, } from "./Storage.js";
+import { Counter, eqTimestamp, Millis, timestampBytesLength, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
+/**
+ * Evolu uses MessagePack for numbers and JSONs.
+ *
+ * - `variableMapSize: true` - More compact maps, ~5-10% slower encoding
+ * - `useRecords: false` - Standard MessagePack without extensions
+ */
+const packr = new Packr({ variableMapSize: true, useRecords: false });
+const minProtocolMessageMaxSize = 1_000_000;
+const maxProtocolMessageMaxSize = 100_000_000;
+/**
+ * Protocol message maximum size.
+ *
+ * Defines the upper limit for how large a single protocol message can be.
+ * Implementations must enforce a maximum size between 1MB and 100MB to ensure
+ * compatibility across all Evolu implementations (the maximum size of mutation
+ * change is hardcoded and enforced hence the maximum size can't be smaller).
+ *
+ * Larger maximum sizes can be configured by relays to reduce roundtrips. For
+ * example, a dedicated relay with ample resources could configure a 100MB
+ * maximum to minimize roundtrips for large syncs.
+ *
+ * Only relays can safely configure larger sizes, as clients will handle them.
+ * Increasing this value on the client side would break compatibility with
+ * relays that enforce smaller limits.
+ */
+export const ProtocolMessageMaxSize = between(minProtocolMessageMaxSize, maxProtocolMessageMaxSize)(Int);
+/**
+ * Default {@link ProtocolMessageMaxSize} (1MB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageMaxSize = minProtocolMessageMaxSize;
+/**
+ * Protocol message ranges maximum size.
+ *
+ * Defines the upper limit for how large the ranges section of a protocol
+ * message can be. Implementations must enforce a maximum size between 3KB and
+ * 100KB to ensure compatibility.
+ *
+ * The upper bound is set to ensure ranges fit within the default 1MB
+ * {@link defaultProtocolMessageMaxSize}, maintaining compatibility between all
+ * clients and relays.
+ */
+export const ProtocolMessageRangesMaxSize = between(3_000, 100_000)(Int);
+/**
+ * Default {@link ProtocolMessageRangesMaxSize} (30KB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export const defaultProtocolMessageRangesMaxSize = 30_000;
 /** Evolu Protocol version. */
-export const protocolVersion = 0;
+export const protocolVersion = NonNegativeInt.orThrow(1);
+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,
+};
+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,
+};
 export const ProtocolErrorCode = {
     NoError: 0,
     /** A code for {@link ProtocolWriteKeyError}. */
     WriteKeyError: 1,
     /** A code for {@link ProtocolWriteError}. */
     WriteError: 2,
+    /** A code for {@link ProtocolQuotaError}. */
+    QuotaError: 3,
     /** A code for {@link ProtocolSyncError}. */
-    SyncError: 3,
-};
-export const WriteKeyMode = {
-    None: 0,
-    Single: 1,
-    Rotation: 2,
-};
-/**
- * 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);
-/**
- * A DbChange is a change to a table row. Together with a unique
- * {@link Timestamp}, it forms a {@link CrdtMessage}.
- */
-export const DbChange = object({
-    table: Base64Url256,
-    id: Id,
-    values: record(Base64Url256, SqliteValue),
-});
-export const RangeType = {
-    Fingerprint: 1,
-    Skip: 0,
-    Timestamps: 2,
+    SyncError: 4,
 };
-export const InfiniteUpperBound = Symbol("InfiniteUpperBound");
-export const fingerprintSize = 12;
-/** A fingerprint of an empty range. */
-export const zeroFingerprint = new Uint8Array(fingerprintSize);
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
- * If the message size would exceed {@link maxProtocolMessageSize}, the protocol
- * ensures all messages will be sent in the next round(s) even over
+ * If the message size would exceed {@link defaultProtocolMessageMaxSize}, the
+ * protocol ensures all messages will be sent in the next round(s) even over
  * unidirectional and stateless transports.
  */
 export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages, maxSize) => {
     const buffer = createProtocolMessageBuffer(owner.id, {
-        type: "initiator",
-        totalMaxSize: maxSize ?? maxProtocolMessageSize,
+        messageType: MessageType.Request,
+        totalMaxSize: maxSize ?? defaultProtocolMessageMaxSize,
         writeKey: owner.writeKey,
     });
     let notAllMessagesSent = false;
     for (const message of messages) {
-        const change = encodeAndEncryptDbChange(deps)(message.change, owner.encryptionKey);
+        const change = encodeAndEncryptDbChange(deps)(message, owner.encryptionKey);
         const encryptedCrdtMessage = { timestamp: message.timestamp, change };
         if (buffer.canAddMessage(encryptedCrdtMessage)) {
             buffer.addMessage(encryptedCrdtMessage);
@@ -229,14 +303,14 @@ export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages,
          *
          * The ideal approach would be to send three ranges (skip, fingerprint,
          * skip) where the fingerprint of unsent messages would act as narrow sync
-         * probe. I think we can send {@link zeroFingerprint} which can be
-         * interpreted as an indication that the other side should reply with
+         * probe. I think we can send `zeroFingerprint` which can be interpreted
+         * as an indication that the other side should reply with
          * {@link TimestampsRange}, so no need to restart syncing.
          *
          * For now, using a random fingerprint avoids extra complexity and is good
          * enough for this case.
          */
-        const randomFingerprint = deps.createRandomBytes(fingerprintSize);
+        const randomFingerprint = deps.randomBytes.create(fingerprintSize);
         // There is always a space for Fingerprint with InfiniteUpperBound.
         buffer.addRange({
             type: RangeType.Fingerprint,
@@ -247,26 +321,25 @@ export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages,
     return buffer.unwrap();
 };
 /** Creates a {@link ProtocolMessage} for sync. */
-export const createProtocolMessageForSync = (deps) => (ownerId) => {
-    const buffer = createProtocolMessageBuffer(ownerId, { type: "initiator" });
-    const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-    const size = deps.storage.getSize(binaryOwnerId);
+export const createProtocolMessageForSync = (deps) => (ownerId, subscriptionFlag) => {
+    const buffer = createProtocolMessageBuffer(ownerId, {
+        messageType: MessageType.Request,
+        subscriptionFlag: subscriptionFlag ?? SubscriptionFlags.None,
+    });
+    const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+    const size = deps.storage.getSize(ownerIdBytes);
     // Errors are handled by the storage.
     if (size == null)
         return null;
-    splitRange(deps)(binaryOwnerId, 0, size, InfiniteUpperBound, buffer);
-    return buffer.unwrap();
-};
-/** Creates a ProtocolMessage for {@link WriteKey} rotation. */
-export const createProtocolMessageForWriteKeyRotation = (ownerId, currentWriteKey, newWriteKey) => {
-    const buffer = createProtocolMessageBuffer(ownerId, {
-        type: "initiator",
-        writeKey: [currentWriteKey, newWriteKey],
-    });
+    splitRange(deps)(ownerIdBytes, NonNegativeInt.orThrow(0), size, InfiniteUpperBound, buffer);
     return buffer.unwrap();
 };
+export const createProtocolMessageForUnsubscribe = (ownerId) => createProtocolMessageBuffer(ownerId, {
+    messageType: MessageType.Request,
+    subscriptionFlag: SubscriptionFlags.Unsubscribe,
+}).unwrap();
 export const createProtocolMessageBuffer = (ownerId, options) => {
-    const { totalMaxSize = maxProtocolMessageSize, rangesMaxSize = maxProtocolMessageRangesSize, version = protocolVersion, } = options;
+    const { totalMaxSize = defaultProtocolMessageMaxSize, rangesMaxSize = defaultProtocolMessageRangesMaxSize, version = protocolVersion, } = options;
     const buffers = {
         header: createBuffer(),
         messages: {
@@ -280,27 +353,25 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
         },
     };
     encodeNonNegativeInt(buffers.header, version);
-    buffers.header.extend(ownerIdToBinaryOwnerId(ownerId));
-    if (options.type === "initiator") {
+    buffers.header.extend(ownerIdToOwnerIdBytes(ownerId));
+    buffers.header.extend([options.messageType]);
+    if (options.messageType === MessageType.Request) {
         if (!options.writeKey) {
-            buffers.header.extend([WriteKeyMode.None]);
-        }
-        else if (!Array.isArray(options.writeKey)) {
-            buffers.header.extend([WriteKeyMode.Single]);
-            buffers.header.extend(options.writeKey);
+            buffers.header.extend([0]);
         }
         else {
-            buffers.header.extend([WriteKeyMode.Rotation]);
-            buffers.header.extend(options.writeKey[0]); // current
-            buffers.header.extend(options.writeKey[1]); // new
+            buffers.header.extend([1]);
+            buffers.header.extend(options.writeKey);
         }
+        const subscriptionFlag = options.subscriptionFlag ?? SubscriptionFlags.None;
+        buffers.header.extend([subscriptionFlag]);
     }
-    else {
+    else if (options.messageType === MessageType.Response) {
         buffers.header.extend([options.errorCode]);
     }
     let isLastRangeInfinite = false;
     const isWithinSizeLimits = () => getSize() <= totalMaxSize;
-    const getSize = () => (getHeaderAndMessagesSize() + getRangesSize());
+    const getSize = () => PositiveInt.orThrow(getHeaderAndMessagesSize() + getRangesSize());
     const getHeaderAndMessagesSize = () => buffers.header.getLength() +
         buffers.messages.timestamps.getLength() +
         buffers.messages.dbChanges.getLength();
@@ -357,6 +428,7 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
                     : true));
         },
         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;
             /**
@@ -365,11 +437,11 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
              * use SkipRange.
              */
             if (range.upperBound !== InfiniteUpperBound)
-                buffers.ranges.timestamps.add(binaryTimestampToTimestamp(range.upperBound));
+                buffers.ranges.timestamps.add(timestampBytesToTimestamp(range.upperBound));
             else {
                 buffers.ranges.timestamps.addInfinite();
             }
-            encodeNonNegativeInt(buffers.ranges.types, range.type);
+            encodeNonNegativeInt(buffers.ranges.types, NonNegativeInt.orThrow(range.type));
             switch (range.type) {
                 case RangeType.Skip:
                     break;
@@ -400,7 +472,7 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
     };
 };
 export const createTimestampsBuffer = () => {
-    let count = 0;
+    let count = NonNegativeInt.orThrow(0);
     const countBuffer = createBuffer();
     const syncCount = () => {
         countBuffer.reset();
@@ -445,9 +517,9 @@ export const createTimestampsBuffer = () => {
 };
 const createRunLengthEncoder = (encodeValue) => {
     const buffer = createBuffer();
-    let previousLength = 0;
+    let previousLength = NonNegativeInt.orThrow(0);
     let previousValue = null;
-    let runLength = 0;
+    let runLength = NonNegativeInt.orThrow(0);
     return {
         add: (value) => {
             if (value === previousValue) {
@@ -456,7 +528,7 @@ const createRunLengthEncoder = (encodeValue) => {
             }
             else {
                 previousValue = value;
-                runLength = 1;
+                runLength = NonNegativeInt.orThrow(1);
             }
             previousLength = buffer.getLength();
             encodeValue(buffer, value);
@@ -466,155 +538,222 @@ const createRunLengthEncoder = (encodeValue) => {
         unwrap: () => buffer.unwrap(),
     };
 };
-export const applyProtocolMessageAsClient = (deps) => (inputMessage, { getWriteKey, version = protocolVersion, totalMaxSize, rangesMaxSize, } = {}) => tryDecodeProtocolData(inputMessage, (input) => {
-    const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
-    if (requestedVersion !== version) {
-        return err({
-            type: "ProtocolUnsupportedVersionError",
-            unsupportedVersion: requestedVersion,
-            isInitiator: version < requestedVersion,
-            ownerId,
+export const applyProtocolMessageAsClient = (deps) => async (inputMessage, options = {}) => {
+    try {
+        const input = createBuffer(inputMessage);
+        const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
+        const version = options.version ?? protocolVersion;
+        if (requestedVersion !== version) {
+            return err({
+                type: "ProtocolVersionError",
+                version: requestedVersion,
+                isInitiator: version < requestedVersion,
+                ownerId,
+            });
+        }
+        const messageType = input.shift();
+        assert(messageType === MessageType.Response ||
+            messageType === MessageType.Broadcast, "Invalid MessageType");
+        if (messageType === MessageType.Response) {
+            const errorCode = input.shift();
+            if (errorCode !== ProtocolErrorCode.NoError) {
+                switch (errorCode) {
+                    case ProtocolErrorCode.WriteKeyError:
+                        return err({
+                            type: "ProtocolWriteKeyError",
+                            ownerId,
+                        });
+                    case ProtocolErrorCode.WriteError:
+                        return err({
+                            type: "ProtocolWriteError",
+                            ownerId,
+                        });
+                    case ProtocolErrorCode.QuotaError:
+                        return err({
+                            type: "ProtocolQuotaError",
+                            ownerId,
+                        });
+                    case ProtocolErrorCode.SyncError:
+                        return err({
+                            type: "ProtocolSyncError",
+                            ownerId,
+                        });
+                    default:
+                        throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
+                }
+            }
+        }
+        const messages = decodeMessages(input);
+        const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+        if (isNonEmptyReadonlyArray(messages)) {
+            const writeResult = await deps.storage.writeMessages(ownerIdBytes, messages);
+            // Errors are handled by the Storage. Here we just stop syncing.
+            if (!writeResult.ok)
+                return ok({ type: "no-response" });
+        }
+        // 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" });
+        }
+        if (messageType === MessageType.Broadcast) {
+            return ok({ type: "broadcast" });
+        }
+        const ranges = decodeRanges(input);
+        if (!isNonEmptyReadonlyArray(ranges)) {
+            return ok({ type: "no-response" });
+        }
+        const output = createProtocolMessageBuffer(ownerId, {
+            messageType: MessageType.Request,
+            writeKey,
+            rangesMaxSize: options.rangesMaxSize,
         });
-    }
-    const errorCode = input.shift();
-    if (errorCode !== ProtocolErrorCode.NoError) {
-        switch (errorCode) {
-            case ProtocolErrorCode.WriteKeyError:
-                return err({
-                    type: "ProtocolWriteKeyError",
-                    ownerId,
-                });
-            case ProtocolErrorCode.WriteError:
-                return err({
-                    type: "ProtocolWriteError",
-                    ownerId,
-                });
-            case ProtocolErrorCode.SyncError:
-                return err({
-                    type: "ProtocolSyncError",
-                    ownerId,
-                });
-            default:
-                throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
+        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() });
     }
-    const messages = decodeMessages(input);
-    const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-    if (isNonEmptyReadonlyArray(messages) &&
-        !deps.storage.writeMessages(binaryOwnerId, messages)) {
-        return ok(null);
-    }
-    if (!getWriteKey)
-        return ok(null);
-    const writeKey = getWriteKey(ownerId);
-    if (writeKey == null)
-        return ok(null);
-    const output = createProtocolMessageBuffer(ownerId, {
-        type: "initiator",
-        writeKey,
-        totalMaxSize,
-        rangesMaxSize,
-    });
-    return sync(deps)("initiator", input, output, binaryOwnerId);
-});
-export const applyProtocolMessageAsRelay = (deps) => (inputMessage, { subscribe, broadcast, totalMaxSize, rangesMaxSize, } = {}, 
-/** For testing purposes only; should not be used in production. */
-version = protocolVersion) => tryDecodeProtocolData(inputMessage, (input) => {
-    const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
-    const binaryOwnerId = ownerIdToBinaryOwnerId(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());
+    catch (error) {
+        return err({
+            type: "ProtocolInvalidDataError",
+            data: inputMessage,
+            error,
+        });
     }
-    subscribe?.(ownerId);
-    const writeKeyMode = input.shift();
-    let writeKey;
-    let newWriteKey;
-    if (writeKeyMode !== WriteKeyMode.None) {
-        writeKey = input.shiftN(writeKeyLength);
-        switch (writeKeyMode) {
-            case WriteKeyMode.Single:
+};
+export const applyProtocolMessageAsRelay = (deps) => async (inputMessage, options = {}, 
+/** For tests only. */
+version = protocolVersion) => {
+    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(ownerIdBytes);
+            return ok({
+                type: "response",
+                message: output.unwrap(),
+            });
+        }
+        const messageType = input.shift();
+        assert(messageType === MessageType.Request, "Invalid MessageType");
+        const hasWriteKey = input.shift();
+        let writeKey;
+        if (hasWriteKey === 1) {
+            writeKey = input.shiftN(ownerWriteKeyLength);
+        }
+        const subscriptionFlag = input.shift();
+        switch (subscriptionFlag) {
+            case SubscriptionFlags.Subscribe:
+                options.subscribe?.(ownerId);
                 break;
-            case WriteKeyMode.Rotation:
-                newWriteKey = input.shiftN(writeKeyLength);
+            case SubscriptionFlags.Unsubscribe:
+                options.unsubscribe?.(ownerId);
+                break;
+            case SubscriptionFlags.None:
                 break;
-            default:
-                throw new ProtocolDecodeError(`Invalid WriteKeyMode: ${writeKeyMode}`);
-        }
-    }
-    if (writeKey) {
-        const isValid = deps.storage.validateWriteKey(binaryOwnerId, writeKey);
-        if (!isValid) {
-            return ok(createProtocolMessageBuffer(ownerId, {
-                type: "non-initiator",
-                errorCode: ProtocolErrorCode.WriteKeyError,
-            }).unwrap());
         }
-        if (newWriteKey) {
-            const rotationSuccess = deps.storage.setWriteKey(binaryOwnerId, newWriteKey);
-            if (!rotationSuccess) {
-                return ok(createProtocolMessageBuffer(ownerId, {
-                    type: "non-initiator",
-                    errorCode: ProtocolErrorCode.WriteError,
-                }).unwrap());
+        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(),
+                });
             }
         }
-    }
-    const messages = decodeMessages(input);
-    if (isNonEmptyReadonlyArray(messages)) {
-        if (!writeKey)
-            return ok(createProtocolMessageBuffer(ownerId, {
-                type: "non-initiator",
-                errorCode: ProtocolErrorCode.WriteKeyError,
-            }).unwrap());
-        // 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);
+        const messages = decodeMessages(input);
+        if (isNonEmptyReadonlyArray(messages)) {
+            if (!writeKey) {
+                return ok({
+                    type: "response",
+                    message: createProtocolMessageBuffer(ownerId, {
+                        messageType: MessageType.Response,
+                        errorCode: ProtocolErrorCode.WriteKeyError,
+                    }).unwrap(),
+                });
+            }
+            const writeResult = await deps.storage.writeMessages(ownerIdBytes, messages);
+            if (!writeResult.ok) {
+                const errorCode = writeResult.error.type === "StorageWriteError"
+                    ? ProtocolErrorCode.WriteError
+                    : ProtocolErrorCode.QuotaError;
+                const message = createProtocolMessageBuffer(ownerId, {
+                    messageType: MessageType.Response,
+                    errorCode,
+                }).unwrap();
+                return ok({ type: "response", message });
+            }
+            /**
+             * Broadcast messages to all subscribed owners for real-time
+             * synchronization between clients.
+             *
+             * Messages are only broadcasted after successful write to ensure
+             * devices that can still sync aren't affected by quota errors, and to
+             * prevent using a half-working relay service (broadcasting without
+             * persistence).
+             *
+             * 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 Evolu sync 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());
             }
-            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,
-    });
-    return sync(deps)("non-initiator", input, output, binaryOwnerId);
-});
-/**
- * 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 = (data, callback) => {
-    try {
-        return callback(createBuffer(data));
+        const ranges = decodeRanges(input);
+        const output = createProtocolMessageBuffer(ownerId, {
+            messageType: MessageType.Response,
+            errorCode: ProtocolErrorCode.NoError,
+            totalMaxSize: options.totalMaxSize,
+            rangesMaxSize: options.rangesMaxSize,
+        });
+        // 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() });
+        }
+        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) {
-        if (error instanceof ProtocolDecodeError || error instanceof BufferError)
-            return err({
-                type: "ProtocolInvalidDataError",
-                data,
-                error,
-            });
-        throw error;
+        return err({
+            type: "ProtocolInvalidDataError",
+            data: inputMessage,
+            error,
+        });
     }
 };
 const decodeVersionAndOwner = (input) => {
@@ -623,7 +762,7 @@ const decodeVersionAndOwner = (input) => {
     // to enable version negotiation and owner identification before any other
     // processing occurs.
     const version = decodeNonNegativeInt(input);
-    const ownerId = decodeOwnerId(input);
+    const ownerId = decodeId(input);
     return [version, ownerId];
 };
 /**
@@ -647,30 +786,13 @@ const decodeMessages = (buffer) => {
     }
     return messages;
 };
-const sync = (deps) => (role, input, output, ownerId) => {
-    const ranges = decodeRanges(input);
-    if (!isNonEmptyReadonlyArray(ranges)) {
-        // Nothing to sync.
-        return ok(null);
-    }
-    const binaryOwnerId = binaryOwnerIdToOwnerId(ownerId);
+const sync = (deps) => (ranges, output, ownerIdBytes) => {
     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, {
-            type: "non-initiator",
-            errorCode: ProtocolErrorCode.SyncError,
-        });
-        return ok(message.unwrap());
-    };
-    const storageSize = deps.storage.getSize(ownerId);
+    const storageSize = deps.storage.getSize(ownerIdBytes);
     if (storageSize == null)
-        return syncFail();
+        return err(ProtocolErrorCode.SyncError);
     let prevUpperBound = null;
-    let prevIndex = 0;
+    let prevIndex = NonNegativeInt.orThrow(0);
     let skip = false;
     let nonSkipRangeAdded = false;
     const skipRange = (range) => {
@@ -700,7 +822,7 @@ const sync = (deps) => (role, input, output, ownerId) => {
     };
     // When we don't have a space...
     const addFingerprintForRemainingRange = (begin) => {
-        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.
@@ -714,30 +836,30 @@ const sync = (deps) => (role, input, output, ownerId) => {
     for (const range of ranges) {
         const currentUpperBound = range.upperBound;
         const lower = prevIndex;
-        let upper = deps.storage.findLowerBound(ownerId, prevIndex, storageSize, currentUpperBound);
+        let upper = deps.storage.findLowerBound(ownerIdBytes, prevIndex, storageSize, currentUpperBound);
         if (upper == null)
-            return syncFail();
+            return err(ProtocolErrorCode.SyncError);
         switch (range.type) {
             case RangeType.Skip: {
                 skipRange(range);
                 break;
             }
             case RangeType.Fingerprint: {
-                const ourFingerprint = deps.storage.fingerprint(ownerId, lower, upper);
+                const ourFingerprint = deps.storage.fingerprint(ownerIdBytes, lower, upper);
                 if (ourFingerprint == null)
-                    return syncFail();
+                    return err(ProtocolErrorCode.SyncError);
                 if (eqArrayNumber(range.fingerprint, ourFingerprint)) {
                     skipRange(range);
                 }
                 else {
                     if (output.canSplitRange()) {
                         coalesceSkipsBeforeAdd();
-                        splitRange(deps)(ownerId, lower, upper, currentUpperBound, output);
+                        splitRange(deps)(ownerIdBytes, lower, upper, currentUpperBound, output);
                     }
                     else {
-                        if (!addFingerprintForRemainingRange(upper))
-                            return syncFail();
-                        return ok(output.unwrap());
+                        return addFingerprintForRemainingRange(upper)
+                            ? ok(true)
+                            : err(ProtocolErrorCode.SyncError);
                     }
                 }
                 break;
@@ -746,19 +868,19 @@ const sync = (deps) => (role, input, output, ownerId) => {
                 let endBound = currentUpperBound;
                 const timestampsWeNeed = new Map(range.timestamps.map((t) => [t.join(), true]));
                 const ourTimestamps = createTimestampsBuffer();
-                let storageError = false;
+                let cantReadDbChange = false;
                 let exceeded = false;
-                deps.storage.iterate(ownerId, lower, upper, (timestamp, index) => {
+                deps.storage.iterate(ownerIdBytes, lower, upper, (timestamp, index) => {
                     const timestampString = timestamp.join();
-                    const timestampBinary = binaryTimestampToTimestamp(timestamp);
+                    const timestampBinary = timestampBytesToTimestamp(timestamp);
                     let message = null;
                     if (timestampsWeNeed.has(timestampString)) {
                         timestampsWeNeed.delete(timestampString);
                     }
                     else {
-                        const dbChange = deps.storage.readDbChange(ownerId, timestamp);
+                        const dbChange = deps.storage.readDbChange(ownerIdBytes, timestamp);
                         if (dbChange == null) {
-                            storageError = true;
+                            cantReadDbChange = true;
                             return false;
                         }
                         message = {
@@ -777,8 +899,8 @@ const sync = (deps) => (role, input, output, ownerId) => {
                         output.addMessage(message);
                     return true;
                 });
-                if (storageError) {
-                    return syncFail();
+                if (cantReadDbChange) {
+                    return err(ProtocolErrorCode.SyncError);
                 }
                 const addRange = () => {
                     coalesceSkipsBeforeAdd();
@@ -791,9 +913,9 @@ const sync = (deps) => (role, input, output, ownerId) => {
                 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.
                 if (timestampsWeNeed.size > 0) {
@@ -810,10 +932,10 @@ const sync = (deps) => (role, input, output, ownerId) => {
     }
     // 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) => (ownerId, lower, upper, upperBound, buffer) => {
-    const itemCount = (upper - lower);
+    const itemCount = NonNegativeInt.orThrow(upper - lower);
     const buckets = computeBalancedBuckets(itemCount);
     if (!buckets.ok) {
         const range = {
@@ -821,8 +943,8 @@ const splitRange = (deps) => (ownerId, lower, upper, upperBound, buffer) => {
             upperBound,
             timestamps: createTimestampsBuffer(),
         };
-        deps.storage.iterate(ownerId, 0, itemCount, (timestamp) => {
-            range.timestamps.add(binaryTimestampToTimestamp(timestamp));
+        deps.storage.iterate(ownerId, NonNegativeInt.orThrow(0), itemCount, (timestamp) => {
+            range.timestamps.add(timestampBytesToTimestamp(timestamp));
             return true;
         });
         buffer.addRange(range);
@@ -831,7 +953,10 @@ const splitRange = (deps) => (ownerId, lower, upper, upperBound, buffer) => {
     // Check Storage.ts `fingerprint` and `fingerprintRanges` docs.
     const fingerprintRangesBuckets = lower === 0
         ? buckets.value
-        : [lower, ...buckets.value.map((b) => (b + lower))];
+        : [
+            lower,
+            ...buckets.value.map((b) => NonNegativeInt.orThrow(b + lower)),
+        ];
     const fingerprintRanges = deps.storage.fingerprintRanges(ownerId, fingerprintRangesBuckets, upperBound);
     // Errors are handled by the storage.
     if (fingerprintRanges == null)
@@ -847,7 +972,7 @@ const decodeRanges = (buffer) => {
     const rangesCount = decodeNonNegativeInt(buffer);
     if (rangesCount === 0)
         return [];
-    const timestampsCount = (rangesCount - 1);
+    const timestampsCount = NonNegativeInt.orThrow(rangesCount - 1);
     const timestamps = decodeTimestamps(buffer, timestampsCount);
     const rangeTypes = [];
     for (let i = 0; i < rangesCount; i++) {
@@ -865,7 +990,7 @@ const decodeRanges = (buffer) => {
     const ranges = [];
     for (let i = 0; i < rangesCount; i++) {
         const upperBound = i < timestampsCount
-            ? timestampToBinaryTimestamp(timestamps[i])
+            ? timestampToTimestampBytes(timestamps[i])
             : InfiniteUpperBound;
         const rangeType = rangeTypes[i];
         switch (rangeType) {
@@ -882,7 +1007,7 @@ const decodeRanges = (buffer) => {
                 break;
             }
             case RangeType.Timestamps: {
-                const timestamps = decodeTimestamps(buffer).map(timestampToBinaryTimestamp);
+                const timestamps = decodeTimestamps(buffer).map(timestampToTimestampBytes);
                 ranges.push({
                     type: RangeType.Timestamps,
                     upperBound,
@@ -903,7 +1028,7 @@ const decodeTimestamps = (buffer, length) => {
         const deltaMillis = decodeNonNegativeInt(buffer);
         const millis = Millis.from(previousMillis + deltaMillis);
         if (!millis.ok)
-            throw new Error(millis.error.type);
+            throw new ProtocolDecodeError(millis.error.type);
         millises.push(millis.value);
         previousMillis = millis.value;
     }
@@ -912,7 +1037,7 @@ const decodeTimestamps = (buffer, length) => {
     while (counterIndex < length) {
         const counter = Counter.from(decodeNonNegativeInt(buffer));
         if (!counter.ok)
-            throw new Error(counter.error.type);
+            throw new ProtocolDecodeError(counter.error.type);
         const runLength = decodeNonNegativeInt(buffer);
         for (let i = 0; i < runLength; i++) {
             counters.push(counter.value);
@@ -939,79 +1064,21 @@ const decodeTimestamps = (buffer, length) => {
     }
     return timestamps;
 };
-export const binaryIdLength = 16;
-export const idToBinaryId = (id) => base64Url256ToBytes(id);
-export const binaryIdToId = (binaryId) => decodeId(createBuffer(binaryId));
-export const ownerIdToBinaryOwnerId = (ownerId) => base64Url256ToBytes(ownerId);
-export const binaryOwnerIdToOwnerId = (binaryOwnerId) => decodeOwnerId(createBuffer(binaryOwnerId));
-/**
- * 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) => {
-    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;
-};
-export const decodeBase64Url256 = (buffer, stringLength) => {
-    const bytes = buffer.shiftN(Math.ceil((stringLength * 6) / 8));
-    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) => {
+    const bytes = buffer.shiftN(idBytesTypeValueLength);
+    return idBytesToId(bytes);
 };
-const decodeId = (buffer) => decodeBase64Url256(buffer, idTypeValueLength);
-/** Not all 16 bytes are valid {@link OwnerId}. */
-const decodeOwnerId = (buffer) => decodeId(buffer);
 /**
  * Evolu uses MessagePack to handle all number variants except for
  * NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
  */
 export const encodeNumber = (buffer, number) => {
-    buffer.extend(pack(number));
+    buffer.extend(packr.pack(number));
 };
 export const decodeNumber = (buffer) => {
     let number;
     let end;
-    unpackMultiple(buffer.unwrap(), (n, _, e) => {
+    packr.unpackMultiple(buffer.unwrap(), (n, _, e) => {
         number = n;
         end = e;
         return false;
@@ -1025,29 +1092,73 @@ export const decodeNumber = (buffer) => {
     buffer.shiftN(endResult.value);
     return numberResult.value;
 };
-export const binaryTimestampToFingerprint = (timestamp) => {
-    const hash = sha256(timestamp).slice(0, fingerprintSize);
-    return hash;
+/**
+ * Encodes an array of boolean flags into a single byte.
+ *
+ * Each element in the array corresponds to a bit (0-7). Array can have 0-8
+ * elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * encodeFlags(buffer, [true, false, true]); // Encodes bits 0, 1, 2
+ * ```
+ */
+export const encodeFlags = (buffer, flags) => {
+    let byte = 0;
+    for (let i = 0; i < flags.length && i < 8; i++) {
+        if (flags[i]) {
+            byte |= 1 << i;
+        }
+    }
+    buffer.extend([byte]);
+};
+/**
+ * Decodes a byte into an array of boolean flags.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const flags = decodeFlags(buffer, 3); // Decode 3 flags
+ * ```
+ */
+export const decodeFlags = (buffer, count) => {
+    const byte = buffer.shift();
+    const flags = [];
+    for (let i = 0; i < count && i < 8; i++) {
+        flags.push((byte & (1 << i)) !== 0);
+    }
+    return flags;
 };
 /**
  * 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) => (change, key) => {
+export const encodeAndEncryptDbChange = (deps) => (message, key) => {
     const buffer = createBuffer();
-    encodeBase64Url256(buffer, change.table);
-    buffer.extend(idToBinaryId(change.id));
-    const entries = objectToEntries(change.values).map(([column, value]) => {
-        return [column, value];
-    });
+    encodeNonNegativeInt(buffer, protocolVersion);
+    // Encode the timestamp to prevent tampering (e.g., a malicious relay
+    // assigning this EncryptedDbChange to a different EncryptedCrdtMessage)
+    buffer.extend(timestampToTimestampBytes(message.timestamp));
+    encodeFlags(buffer, [
+        message.change.isInsert,
+        message.change.isDelete != null,
+        message.change.isDelete ?? false,
+    ]);
+    encodeString(buffer, message.change.table);
+    buffer.extend(idToIdBytes(message.change.id));
+    const entries = objectToEntries(message.change.values);
     encodeLength(buffer, entries);
     for (const [column, value] of entries) {
-        encodeBase64Url256(buffer, column);
+        encodeString(buffer, column);
         encodeSqliteValue(buffer, value);
     }
-    const paddingLength = padmePaddingLength(buffer.getLength());
-    // Add zero bytes as PADMÉ padding - these will be ignored during decoding.
-    buffer.extend(new Uint8Array(paddingLength));
+    // Add PADMÉ padding (ignored during decoding)
+    buffer.extend(createPadmePadding(buffer.getLength()));
     const { nonce, ciphertext } = deps.symmetricCrypto.encrypt(buffer.unwrap(), key);
     buffer.reset();
     buffer.extend(nonce);
@@ -1056,30 +1167,57 @@ export const encodeAndEncryptDbChange = (deps) => (change, key) => {
     return buffer.unwrap();
 };
 /**
- * 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) => (change, key) => tryDecodeProtocolData(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;
-    buffer.reset();
-    buffer.extend(plaintextBytes.value);
-    const table = decodeBase64Url256WithLength(buffer);
-    const id = decodeId(buffer);
-    const length = decodeLength(buffer);
-    const values = Object.create(null);
-    for (let i = 0; i < length; i++) {
-        const column = decodeBase64Url256WithLength(buffer);
-        const value = decodeSqliteValue(buffer);
-        values[column] = value;
+export const decryptAndDecodeDbChange = (deps) => (message, key) => {
+    try {
+        const buffer = createBuffer(message.change);
+        const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
+        const ciphertext = buffer.shiftN(decodeLength(buffer));
+        const plaintextBytes = deps.symmetricCrypto.decrypt(ciphertext, key, nonce);
+        if (!plaintextBytes.ok)
+            return plaintextBytes;
+        buffer.reset();
+        buffer.extend(plaintextBytes.value);
+        // Decode version (for future compatibility, not need yet)
+        decodeNonNegativeInt(buffer);
+        const timestamp = timestampBytesToTimestamp(buffer.shiftN(timestampBytesLength));
+        if (!eqTimestamp(timestamp, message.timestamp)) {
+            return err({
+                type: "ProtocolTimestampMismatchError",
+                expected: message.timestamp,
+                timestamp,
+            });
+        }
+        const flags = decodeFlags(buffer, PositiveInt.orThrow(3));
+        const table = decodeString(buffer);
+        const id = decodeId(buffer);
+        const length = decodeLength(buffer);
+        const values = Object.create(null);
+        for (let i = 0; i < length; i++) {
+            const column = decodeString(buffer);
+            const value = decodeSqliteValue(buffer);
+            values[column] = value;
+        }
+        const dbChange = DbChange.orThrow({
+            table,
+            id,
+            values,
+            isInsert: flags[0],
+            isDelete: flags[1] ? flags[2] : null,
+        });
+        return ok(dbChange);
+    }
+    catch (error) {
+        return err({
+            type: "ProtocolInvalidDataError",
+            data: message.change,
+            error,
+        });
     }
-    const dbChange = { table, id, values };
-    return ok(dbChange);
-});
+};
 /**
  * Encodes a non-negative integer into a variable-length integer format. It's
  * more efficient than encoding via {@link encodeNumber}.
@@ -1126,7 +1264,7 @@ export const decodeNonNegativeInt = (buffer) => {
     return int.value;
 };
 export const encodeLength = (buffer, value) => {
-    encodeNonNegativeInt(buffer, value.length);
+    encodeNonNegativeInt(buffer, NonNegativeInt.orThrow(value.length));
 };
 export const decodeLength = decodeNonNegativeInt;
 export const encodeString = (buffer, value) => {
@@ -1143,37 +1281,31 @@ export const encodeNodeId = (buffer, nodeId) => {
     buffer.extend(hexToBytes(nodeId));
 };
 export const decodeNodeId = (buffer) => {
-    const bytes = buffer.shiftN(8);
+    const bytes = buffer.shiftN(NonNegativeInt.orThrow(8));
     return bytesToHex(bytes);
 };
-export const encodeBase64Url256 = (buffer, string) => {
-    encodeLength(buffer, string);
-    buffer.extend(base64Url256ToBytes(string));
-};
-export const decodeBase64Url256WithLength = (buffer) => {
-    const length = decodeLength(buffer);
-    return decodeBase64Url256(buffer, length);
-};
 // Small ints are encoded into ProtocolValueType, saving one byte per int.
 const isSmallInt = (value) => value >= 0 && value < 20;
 export const ProtocolValueType = {
     // 0-19 small ints
     // SQLite types
-    String: 20,
-    Number: 21,
-    Null: 22,
-    Binary: 23,
+    String: NonNegativeInt.orThrow(20),
+    Number: NonNegativeInt.orThrow(21),
+    Null: NonNegativeInt.orThrow(22),
+    Bytes: NonNegativeInt.orThrow(23),
     // We can add more types for other DBs or anything else later.
     // Optimized types
-    Id: 30,
-    Base64Url256: 31,
-    NonNegativeInt: 32,
-    Json: 33,
+    NonNegativeInt: NonNegativeInt.orThrow(30),
+    // String optimizations
+    EmptyString: NonNegativeInt.orThrow(31), // 1 byte vs 2 bytes (50% reduction)
+    Base64Url: NonNegativeInt.orThrow(32),
+    Id: NonNegativeInt.orThrow(33),
+    Json: NonNegativeInt.orThrow(34),
     // new Date().toISOString()   - 24 bytes
     // encoded with fixed length  - 8 bytes
     // encode as NonNegativeInt   - 6 bytes (additional 25% reduction)
-    DateIsoWithNonNegativeTime: 34,
-    DateIsoWithNegativeTime: 35, // 9 bytes
+    DateIsoWithNonNegativeTime: NonNegativeInt.orThrow(35),
+    DateIsoWithNegativeTime: NonNegativeInt.orThrow(36), // 9 bytes
     // TODO: Operations (from 40)
     // Increment, Decrement, Patch, whatever.
 };
@@ -1184,9 +1316,13 @@ export const encodeSqliteValue = (buffer, value) => {
     }
     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, ProtocolValueType.DateIsoWithNonNegativeTime);
                     encodeNonNegativeInt(buffer, time);
@@ -1197,25 +1333,31 @@ export const encodeSqliteValue = (buffer, value) => {
                 }
                 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;
@@ -1235,7 +1377,7 @@ export const encodeSqliteValue = (buffer, value) => {
             return;
         }
     }
-    encodeNonNegativeInt(buffer, ProtocolValueType.Binary);
+    encodeNonNegativeInt(buffer, ProtocolValueType.Bytes);
     encodeLength(buffer, value);
     buffer.extend(value);
 };
@@ -1251,31 +1393,35 @@ export const decodeSqliteValue = (buffer) => {
             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");