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

package/dist/src/Evolu/Protocol.js

@@ -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.
@@ -120,25 +151,48 @@
  *
  * @module
  */
-import { sha256 } from "@noble/hashes/sha2";
-import { pack, unpack, unpackMultiple } from "msgpackr";
+import { Packr } from "msgpackr";
 import { isNonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
-import { BufferError, bytesToHex, bytesToUtf8, concatBytes, createBuffer, hexToBytes, utf8ToBytes, } from "../Buffer.js";
+import { bytesToHex, bytesToUtf8, createBuffer, hexToBytes, utf8ToBytes, } from "../Buffer.js";
 import { padmePaddingLength, } 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 { Base64Url, DateIsoString, idTypeValueLength, JsonValueFromString, maxLength, NonNegativeInt, Number, } from "../Type.js";
-import { writeKeyLength, } from "./Owner.js";
-import { binaryTimestampToTimestamp, Counter, Millis, timestampToBinaryTimestamp, } from "./Timestamp.js";
+import { Base64Url, base64UrlToUint8Array, DateIso, Id, idBytesToId, idBytesTypeValueLength, idToIdBytes, Json, jsonToJsonValue, NonNegativeInt, Number, uint8ArrayToBase64Url, } from "../Type.js";
+import { ownerIdToOwnerIdBytes, ownerWriteKeyLength, } from "./Owner.js";
+import { fingerprintSize, InfiniteUpperBound, RangeType, } from "./Storage.js";
+import { Counter, eqTimestamp, Millis, 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;
 /** Maximum size of the ranges in bytes. */
 export const maxProtocolMessageRangesSize = 30_000;
 /** Evolu Protocol version. */
 export const protocolVersion = 0;
+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}. */
@@ -148,15 +202,6 @@ export const ProtocolErrorCode = {
     /** A code for {@link ProtocolSyncError}. */
     SyncError: 3,
 };
-export const RangeType = {
-    Fingerprint: 1,
-    Skip: 0,
-    Timestamps: 2,
-};
-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.
  *
@@ -166,12 +211,13 @@ export const zeroFingerprint = new Uint8Array(fingerprintSize);
  */
 export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages, maxSize) => {
     const buffer = createProtocolMessageBuffer(owner.id, {
+        messageType: MessageType.Request,
         totalMaxSize: maxSize ?? maxProtocolMessageSize,
         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);
@@ -197,7 +243,7 @@ export const createProtocolMessageFromCrdtMessages = (deps) => (owner, messages,
          * 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,
@@ -208,18 +254,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);
-    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);
+    splitRange(deps)(ownerIdBytes, 0, size, InfiniteUpperBound, buffer);
     return buffer.unwrap();
 };
-export const createProtocolMessageBuffer = (ownerId, options = {}) => {
-    const { errorCode, writeKey, totalMaxSize = maxProtocolMessageSize, rangesMaxSize = maxProtocolMessageRangesSize, version = protocolVersion, } = options;
+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 buffers = {
         header: createBuffer(),
         messages: {
@@ -233,18 +286,28 @@ export const createProtocolMessageBuffer = (ownerId, options = {}) => {
         },
     };
     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;
     const isWithinSizeLimits = () => getSize() <= totalMaxSize;
     const getSize = () => (getHeaderAndMessagesSize() + getRangesSize());
     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
         ? buffers.ranges.timestamps.getLength() +
             buffers.ranges.types.getLength() +
@@ -298,6 +361,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;
             /**
@@ -306,7 +370,7 @@ 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();
             }
@@ -330,8 +394,6 @@ export const createProtocolMessageBuffer = (ownerId, options = {}) => {
             }
             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);
                 buffers.header.extend(buffers.ranges.types.unwrap());
@@ -409,118 +471,220 @@ 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) {
+export const applyProtocolMessageAsClient = (deps) => async (inputMessage, options = {}) => {
+    // try-catch instead of Result for performance and stacktraces
+    try {
+        const input = createBuffer(inputMessage);
+        const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
+        const version = options.version ?? protocolVersion;
+        if (requestedVersion !== version) {
+            return err({
+                type: "ProtocolUnsupportedVersionError",
+                unsupportedVersion: 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.SyncError:
+                        return err({
+                            type: "ProtocolSyncError",
+                            ownerId,
+                        });
+                    default:
+                        throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
+                }
+            }
+        }
+        const messages = decodeMessages(input);
+        const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+        if (isNonEmptyReadonlyArray(messages) &&
+            !(await deps.storage.writeMessages(ownerIdBytes, messages))) {
+            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,
+            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({
-            type: "ProtocolUnsupportedVersionError",
-            unsupportedVersion: requestedVersion,
-            isInitiator: version < requestedVersion,
-            ownerId,
+            type: "ProtocolInvalidDataError",
+            data: inputMessage,
+            error,
         });
     }
-    const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-    const errorCode = input.shift();
-    if (errorCode !== ProtocolErrorCode.NoError) {
-        switch (errorCode) {
-            case ProtocolErrorCode.WriteKeyError:
-                return err({
-                    type: "ProtocolWriteKeyError",
-                    ownerId,
+};
+export const applyProtocolMessageAsRelay = (deps) => async (inputMessage, options = {}, 
+/** For testing purposes only; should not be used in production. */
+version = protocolVersion) => {
+    // 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(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 SubscriptionFlags.Unsubscribe:
+                options.unsubscribe?.(ownerId);
+                break;
+            case SubscriptionFlags.None:
+                break;
+        }
+        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(),
                 });
-            case ProtocolErrorCode.WriteError:
-                return err({
-                    type: "ProtocolWriteError",
-                    ownerId,
+            }
+        }
+        const messages = decodeMessages(input);
+        if (isNonEmptyReadonlyArray(messages)) {
+            if (!writeKey) {
+                return ok({
+                    type: "response",
+                    message: createProtocolMessageBuffer(ownerId, {
+                        messageType: MessageType.Response,
+                        errorCode: ProtocolErrorCode.WriteKeyError,
+                    }).unwrap(),
                 });
-            case ProtocolErrorCode.SyncError:
-                return err({
-                    type: "ProtocolSyncError",
-                    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,
                 });
-            default:
-                throw new ProtocolDecodeError(`Invalid ProtocolErrorCode: ${errorCode}`);
+                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 messages = decodeMessages(input);
-    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, {
-        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 = decodeNonNegativeInt(input);
-    const ownerId = decodeOwnerId(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());
-    }
-    subscribe?.(ownerId);
-    const messages = decodeMessages(input);
-    if (isNonEmptyReadonlyArray(messages)) {
-        const messagesEnd = inputMessage.length - input.getLength();
-        const writeKey = input.shiftN(writeKeyLength);
-        const writeKeyIsValid = deps.storage.validateWriteKey(binaryOwnerId, writeKey);
-        if (!writeKeyIsValid)
-            return ok(createProtocolMessageBuffer(ownerId, {
-                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));
-            broadcast(ownerId, broadcastMessage);
+        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() });
         }
-        if (!deps.storage.writeMessages(binaryOwnerId, messages))
-            return ok(createProtocolMessageBuffer(ownerId, {
-                errorCode: ProtocolErrorCode.WriteError,
-            }).unwrap());
-    }
-    const output = createProtocolMessageBuffer(ownerId, {
-        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 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) => {
+    // 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);
     return [version, ownerId];
 };
 /**
@@ -544,27 +708,11 @@ 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, {
-            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 skip = false;
@@ -596,7 +744,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.
@@ -610,30 +758,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;
@@ -642,19 +790,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 = {
@@ -673,8 +821,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();
@@ -687,9 +835,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) {
@@ -706,7 +854,7 @@ 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);
@@ -718,7 +866,7 @@ const splitRange = (deps) => (ownerId, lower, upper, upperBound, buffer) => {
             timestamps: createTimestampsBuffer(),
         };
         deps.storage.iterate(ownerId, 0, itemCount, (timestamp) => {
-            range.timestamps.add(binaryTimestampToTimestamp(timestamp));
+            range.timestamps.add(timestampBytesToTimestamp(timestamp));
             return true;
         });
         buffer.addRange(range);
@@ -761,7 +909,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) {
@@ -778,7 +926,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,
@@ -799,7 +947,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;
     }
@@ -808,7 +956,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);
@@ -835,84 +983,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));
-/**
- * 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);
-/**
- * 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;
@@ -926,24 +1011,30 @@ 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 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 change = message.change;
     const buffer = createBuffer();
-    encodeBase64Url256(buffer, change.table);
-    buffer.extend(idToBinaryId(change.id));
+    // 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);
+    encodeString(buffer, change.table);
+    buffer.extend(idToIdBytes(change.id));
     const entries = objectToEntries(change.values).map(([column, value]) => {
         return [column, value];
     });
     encodeLength(buffer, entries);
     for (const [column, value] of entries) {
-        encodeBase64Url256(buffer, column);
+        encodeString(buffer, column);
         encodeSqliteValue(buffer, value);
     }
     const paddingLength = padmePaddingLength(buffer.getLength());
@@ -957,30 +1048,55 @@ 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-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);
+        // Decode version (for future compatibility, no validation needed for now)
+        decodeNonNegativeInt(buffer);
+        // Decode and verify the embedded timestamp
+        const embeddedTimestampBytes = buffer.shiftN(timestampBytesLength);
+        const embeddedTimestamp = timestampBytesToTimestamp(embeddedTimestampBytes);
+        // Verify timestamp integrity
+        if (!eqTimestamp(embeddedTimestamp, message.timestamp)) {
+            return err({
+                type: "ProtocolTimestampMismatchError",
+                expected: message.timestamp,
+                embedded: embeddedTimestamp,
+            });
+        }
+        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 = { table, id, values };
+        return ok(dbChange);
     }
-    const dbChange = { table, id, values };
-    return ok(dbChange);
-});
+    catch (error) {
+        return err({
+            type: "ProtocolInvalidDataError",
+            data: message.change,
+            error,
+        });
+    }
+};
 /**
  * Encodes a non-negative integer into a variable-length integer format. It's
  * more efficient than encoding via {@link encodeNumber}.
@@ -1047,14 +1163,6 @@ export const decodeNodeId = (buffer) => {
     const bytes = buffer.shiftN(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 = {
@@ -1063,18 +1171,20 @@ export const ProtocolValueType = {
     String: 20,
     Number: 21,
     Null: 22,
-    Binary: 23,
+    Bytes: 23,
     // We can add more types for other DBs or anything else later.
     // Optimized types
-    Id: 30,
-    Base64Url256: 31,
-    NonNegativeInt: 32,
-    Json: 33,
+    NonNegativeInt: 30,
+    // String optimizations
+    EmptyString: 31, // 1 byte vs 2 bytes (50% reduction)
+    Base64Url: 32,
+    Id: 33,
+    Json: 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: 35,
+    DateIsoWithNegativeTime: 36, // 9 bytes
     // TODO: Operations (from 40)
     // Increment, Decrement, Patch, whatever.
 };
@@ -1085,9 +1195,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);
@@ -1098,25 +1212,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;
@@ -1136,7 +1256,7 @@ export const encodeSqliteValue = (buffer, value) => {
             return;
         }
     }
-    encodeNonNegativeInt(buffer, ProtocolValueType.Binary);
+    encodeNonNegativeInt(buffer, ProtocolValueType.Bytes);
     encodeLength(buffer, value);
     buffer.extend(value);
 };
@@ -1152,33 +1272,57 @@ 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");
     }
 };
+/**
+ * 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, _isInitiator) => {
+    // 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.");
+};