@evolu/common 7.4.1 → 8.0.0-next.0

package/dist/src/local-first/Protocol.js

@@ -20,7 +20,7 @@
  * transfer, ownership, real-time broadcasting, request-response semantics, and
  * error handling.
  *
- * ### Message structure
+ * ## Message structure
  *
  * | Field                          | Notes                     |
  * | :----------------------------- | :------------------------ |
@@ -43,7 +43,7 @@
  * | - {@link NonNegativeInt}       | Number of ranges.         |
  * | - {@link Range}                |                           |
  *
- * ### WriteKey validation
+ * ## WriteKey validation
  *
  * The initiator sends a hasWriteKey flag and optionally a WriteKey. The
  * WriteKey is required when sending messages as a secure token proving the
@@ -52,7 +52,7 @@
  * validates the WriteKey immediately after parsing the initiator header, before
  * processing any messages or ranges.
  *
- * ### Synchronization
+ * ## Synchronization
  *
  * - **Messages**: Sends {@link EncryptedCrdtMessage}s in either direction.
  * - **Ranges**: Determines messages to sync. Usage varies by transport—e.g., sent
@@ -79,7 +79,7 @@
  * 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:
  *
@@ -94,7 +94,7 @@
  * 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 ProtocolMessageMaxSize}. This ensures every {@link ProtocolMessage} is
@@ -107,7 +107,7 @@
  * message limit to ensure efficient sync with
  * {@link defaultProtocolMessageRangesMaxSize}.
  *
- * ### Why Binary?
+ * ## Why Binary?
  *
  * The protocol avoids JSON because:
  *
@@ -127,7 +127,7 @@
  * To avoid reinventing serialization where it’s unnecessary—like for JSON and
  * certain numbers—the Evolu Protocol relies on MessagePack.
  *
- * ### Versioning
+ * ## Versioning
  *
  * Evolu Protocol uses explicit versioning to ensure compatibility between
  * clients and relays (or peers). Each protocol message begins with a version
@@ -148,7 +148,7 @@
  * Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
  * over time and provide clear feedback about version mismatches.
  *
- * ### Credible exit
+ * ## Credible exit
  *
  * The protocol specification is intentionally non-configurable to ensure
  * universal compatibility. This design allows applications (users) to switch
@@ -176,18 +176,20 @@
  *   indicators) to be forwarded by relays without storage overhead.
  */
 import { Packr } from "msgpackr";
-import { isNonEmptyReadonlyArray } from "../Array.js";
+import { isNonEmptyArray } from "../Array.js";
 import { assert } from "../Assert.js";
 import { bytesToHex, bytesToUtf8, createBuffer, hexToBytes, utf8ToBytes, } from "../Buffer.js";
-import { createPadmePadding, } from "../Crypto.js";
+import { createPadmePadding, decryptWithXChaCha20Poly1305, EncryptionKey, encryptWithXChaCha20Poly1305, Entropy24, XChaCha20Poly1305Ciphertext, xChaCha20Poly1305NonceLength, } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
 import { createRecord, objectToEntries } from "../Object.js";
 import { err, ok } from "../Result.js";
-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 { SqliteValue } from "../Sqlite.js";
+import { Millis } from "../Time.js";
+import { Base64Url, base64UrlToUint8Array, between, DateIso, Id, IdBytes, idBytesToId, idBytesTypeValueLength, idToIdBytes, Int, Json, jsonToJsonValue, NonNegativeInt, Number, onePositiveInt, PositiveInt, uint8ArrayToBase64Url, zeroNonNegativeInt, } from "../Type.js";
+import { OwnerId, OwnerIdBytes, ownerIdToOwnerIdBytes, OwnerWriteKey, ownerWriteKeyLength, } from "./Owner.js";
 import { DbChange, fingerprintSize, InfiniteUpperBound, RangeType, } from "./Storage.js";
-import { Counter, eqTimestamp, Millis, timestampBytesLength, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
+import { Counter, eqTimestamp, NodeId, Timestamp, TimestampBytes, timestampBytesLength, timestampBytesToTimestamp, timestampToTimestampBytes, } from "./Timestamp.js";
 /**
  * Evolu uses MessagePack for numbers and JSONs.
  *
@@ -213,7 +215,7 @@ const maxProtocolMessageMaxSize = 100_000_000;
  * Increasing this value on the client side would break compatibility with
  * relays that enforce smaller limits.
  */
-export const ProtocolMessageMaxSize = between(minProtocolMessageMaxSize, maxProtocolMessageMaxSize)(Int);
+export const ProtocolMessageMaxSize = /*#__PURE__*/ between(minProtocolMessageMaxSize, maxProtocolMessageMaxSize)(Int);
 /**
  * Default {@link ProtocolMessageMaxSize} (1MB).
  *
@@ -232,7 +234,7 @@ export const defaultProtocolMessageMaxSize = minProtocolMessageMaxSize;
  * {@link defaultProtocolMessageMaxSize}, maintaining compatibility between all
  * clients and relays.
  */
-export const ProtocolMessageRangesMaxSize = between(3_000, 100_000)(Int);
+export const ProtocolMessageRangesMaxSize = /*#__PURE__*/ between(3_000, 100_000)(Int);
 /**
  * Default {@link ProtocolMessageRangesMaxSize} (30KB).
  *
@@ -241,7 +243,7 @@ export const ProtocolMessageRangesMaxSize = between(3_000, 100_000)(Int);
  */
 export const defaultProtocolMessageRangesMaxSize = 30_000;
 /** Evolu Protocol version. */
-export const protocolVersion = NonNegativeInt.orThrow(1);
+export const protocolVersion = onePositiveInt;
 export const MessageType = {
     /** Request message from initiator (client) to non-initiator (relay). */
     Request: 0,
@@ -250,6 +252,24 @@ export const MessageType = {
     /** Broadcast message from non-initiator (relay) to subscribed clients. */
     Broadcast: 2,
 };
+/**
+ * Parses the protocol header needed for routing.
+ *
+ * Every protocol message begins with `protocolVersion`, `ownerId`, and
+ * `messageType`.
+ */
+export const parseProtocolHeader = (inputMessage) => {
+    try {
+        return ok(parseProtocolHeaderFromBuffer(createBuffer(inputMessage)));
+    }
+    catch (error) {
+        return err({
+            type: "ProtocolInvalidDataError",
+            data: inputMessage,
+            error,
+        });
+    }
+};
 export const SubscriptionFlags = {
     /** No subscription changes for this owner. */
     None: 0,
@@ -328,10 +348,7 @@ export const createProtocolMessageForSync = (deps) => (ownerId, subscriptionFlag
     });
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
     const size = deps.storage.getSize(ownerIdBytes);
-    // Errors are handled by the storage.
-    if (size == null)
-        return null;
-    splitRange(deps)(ownerIdBytes, NonNegativeInt.orThrow(0), size, InfiniteUpperBound, buffer);
+    splitRange(deps)(ownerIdBytes, zeroNonNegativeInt, size, InfiniteUpperBound, buffer);
     return buffer.unwrap();
 };
 export const createProtocolMessageForUnsubscribe = (ownerId) => createProtocolMessageBuffer(ownerId, {
@@ -413,9 +430,7 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
             buffers.messages.dbChanges.extend(message.change);
             assert(isWithinSizeLimits(), "the message is too big");
         },
-        canSplitRange: () => {
-            return getRangesSize() + safeMargins.splitRange <= rangesMaxSize;
-        },
+        canSplitRange: () => getRangesSize() + safeMargins.splitRange <= rangesMaxSize,
         canAddTimestampsRangeAndMessage: (timestamps, message) => {
             const rangesNewSize = getRangesSize() + timestamps.getLength() + safeMargins.timestampsRange;
             return (rangesNewSize <= rangesMaxSize &&
@@ -472,7 +487,7 @@ export const createProtocolMessageBuffer = (ownerId, options) => {
     };
 };
 export const createTimestampsBuffer = () => {
-    let count = NonNegativeInt.orThrow(0);
+    let count = zeroNonNegativeInt;
     const countBuffer = createBuffer();
     const syncCount = () => {
         countBuffer.reset();
@@ -517,9 +532,9 @@ export const createTimestampsBuffer = () => {
 };
 const createRunLengthEncoder = (encodeValue) => {
     const buffer = createBuffer();
-    let previousLength = NonNegativeInt.orThrow(0);
+    let previousLength = zeroNonNegativeInt;
     let previousValue = null;
-    let runLength = NonNegativeInt.orThrow(0);
+    let runLength = zeroNonNegativeInt;
     return {
         add: (value) => {
             if (value === previousValue) {
@@ -538,7 +553,8 @@ const createRunLengthEncoder = (encodeValue) => {
         unwrap: () => buffer.unwrap(),
     };
 };
-export const applyProtocolMessageAsClient = (deps) => async (inputMessage, options = {}) => {
+export const applyProtocolMessageAsClient = (inputMessage, options = {}) => async (run) => {
+    const { storage } = run.deps;
     try {
         const input = createBuffer(inputMessage);
         const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
@@ -585,39 +601,45 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
         }
         const messages = decodeMessages(input);
         const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
-        if (isNonEmptyReadonlyArray(messages)) {
-            const result = await deps.storage.writeMessages(ownerIdBytes, messages);
-            // Errors are handled by the Storage. Here we just stop syncing.
-            if (!result.ok)
-                return ok({ type: "no-response" });
+        if (isNonEmptyArray(messages)) {
+            try {
+                const result = await run(storage.writeMessages(ownerIdBytes, messages));
+                // Quota errors are handled by Storage; protocol just stops syncing.
+                if (!result.ok)
+                    return ok({ type: "NoResponse" });
+            }
+            catch (error) {
+                run.deps.console.error(error);
+                return ok({ type: "NoResponse" });
+            }
         }
         // 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);
+        const writeKey = options.writeKey;
         if (writeKey == null) {
-            return ok({ type: "no-response" });
+            return ok({ type: "NoResponse" });
         }
         if (messageType === MessageType.Broadcast) {
-            return ok({ type: "broadcast" });
+            return ok({ type: "Broadcast" });
         }
         const ranges = decodeRanges(input);
-        if (!isNonEmptyReadonlyArray(ranges)) {
-            return ok({ type: "no-response" });
+        if (!isNonEmptyArray(ranges)) {
+            return ok({ type: "NoResponse" });
         }
         const output = createProtocolMessageBuffer(ownerId, {
             messageType: MessageType.Request,
             writeKey,
             rangesMaxSize: options.rangesMaxSize,
         });
-        const result = sync(deps)(ranges, output, ownerIdBytes);
+        const result = sync(run.deps)(ranges, output, ownerIdBytes);
         // Client sync error (handled via Storage) or no changes.
         if (!result.ok || !result.value) {
-            return ok({ type: "no-response" });
+            return ok({ type: "NoResponse" });
         }
-        return ok({ type: "response", message: output.unwrap() });
+        return ok({ type: "Response", message: output.unwrap() });
     }
     catch (error) {
         return err({
@@ -627,9 +649,10 @@ export const applyProtocolMessageAsClient = (deps) => async (inputMessage, optio
         });
     }
 };
-export const applyProtocolMessageAsRelay = (deps) => async (inputMessage, options = {}, 
+export const applyProtocolMessageAsRelay = (inputMessage, options = {}, 
 /** For tests only. */
-version = protocolVersion) => {
+version = protocolVersion) => async (run) => {
+    const { storage } = run.deps;
     try {
         const input = createBuffer(inputMessage);
         const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
@@ -640,7 +663,7 @@ version = protocolVersion) => {
             encodeNonNegativeInt(output, version);
             output.extend(ownerIdBytes);
             return ok({
-                type: "response",
+                type: "Response",
                 message: output.unwrap(),
             });
         }
@@ -663,10 +686,10 @@ version = protocolVersion) => {
                 break;
         }
         if (writeKey) {
-            const isValid = deps.storage.validateWriteKey(ownerIdBytes, writeKey);
+            const isValid = storage.validateWriteKey(ownerIdBytes, writeKey);
             if (!isValid) {
                 return ok({
-                    type: "response",
+                    type: "Response",
                     message: createProtocolMessageBuffer(ownerId, {
                         messageType: MessageType.Response,
                         errorCode: ProtocolErrorCode.WriteKeyError,
@@ -675,26 +698,33 @@ version = protocolVersion) => {
             }
         }
         const messages = decodeMessages(input);
-        if (isNonEmptyReadonlyArray(messages)) {
+        if (isNonEmptyArray(messages)) {
             if (!writeKey) {
                 return ok({
-                    type: "response",
+                    type: "Response",
                     message: createProtocolMessageBuffer(ownerId, {
                         messageType: MessageType.Response,
                         errorCode: ProtocolErrorCode.WriteKeyError,
                     }).unwrap(),
                 });
             }
-            const result = await deps.storage.writeMessages(ownerIdBytes, messages);
-            if (!result.ok) {
-                const errorCode = result.error.type === "StorageWriteError"
-                    ? ProtocolErrorCode.WriteError
-                    : ProtocolErrorCode.QuotaError;
+            try {
+                const result = await run(storage.writeMessages(ownerIdBytes, messages));
+                if (!result.ok) {
+                    const message = createProtocolMessageBuffer(ownerId, {
+                        messageType: MessageType.Response,
+                        errorCode: ProtocolErrorCode.QuotaError,
+                    }).unwrap();
+                    return ok({ type: "Response", message });
+                }
+            }
+            catch (error) {
+                run.deps.console.error(error);
                 const message = createProtocolMessageBuffer(ownerId, {
                     messageType: MessageType.Response,
-                    errorCode,
+                    errorCode: ProtocolErrorCode.WriteError,
                 }).unwrap();
-                return ok({ type: "response", message });
+                return ok({ type: "Response", message });
             }
             /**
              * Broadcast messages to all subscribed owners for real-time
@@ -735,10 +765,10 @@ version = protocolVersion) => {
         });
         // 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 (!isNonEmptyArray(ranges)) {
+            return ok({ type: "Response", message: output.unwrap() });
         }
-        const result = sync(deps)(ranges, output, ownerIdBytes);
+        const result = sync(run.deps)(ranges, output, ownerIdBytes);
         const message = result.ok
             ? output.unwrap()
             : createProtocolMessageBuffer(ownerId, {
@@ -746,7 +776,7 @@ version = protocolVersion) => {
                 errorCode: result.error,
             }).unwrap();
         // Non-initiators always respond to provide sync completion feedback,
-        return ok({ type: "response", message });
+        return ok({ type: "Response", message });
     }
     catch (error) {
         return err({
@@ -765,6 +795,33 @@ const decodeVersionAndOwner = (input) => {
     const ownerId = decodeId(input);
     return [version, ownerId];
 };
+const parseProtocolHeaderFromBuffer = (input) => {
+    const [version, ownerId] = decodeVersionAndOwner(input);
+    if (version !== protocolVersion) {
+        throw new ProtocolDecodeError(`Unsupported protocol version: ${version}`);
+    }
+    const messageTypeValue = input.shift();
+    let messageType;
+    switch (messageTypeValue) {
+        case MessageType.Request:
+            messageType = MessageType.Request;
+            break;
+        case MessageType.Response:
+            messageType = MessageType.Response;
+            break;
+        case MessageType.Broadcast:
+            messageType = MessageType.Broadcast;
+            break;
+        default:
+            throw new ProtocolDecodeError("Invalid MessageType");
+    }
+    return {
+        type: "ProtocolHeader",
+        version: 1,
+        ownerId,
+        messageType,
+    };
+};
 /**
  * Error thrown for internal protocol validation failures, such as invalid data
  * or type errors.
@@ -778,21 +835,27 @@ class ProtocolDecodeError extends Error {
 }
 const decodeMessages = (buffer) => {
     const timestamps = decodeTimestamps(buffer);
-    const messages = [];
-    for (const timestamp of timestamps) {
+    const messages = new Array(timestamps.length);
+    for (let i = 0; i < timestamps.length; i++) {
+        const timestamp = timestamps[i];
         const changeLength = decodeLength(buffer);
         const change = buffer.shiftN(changeLength);
-        messages.push({ timestamp, change });
+        messages[i] = { timestamp, change };
     }
     return messages;
 };
 const sync = (deps) => (ranges, output, ownerIdBytes) => {
     const outputInitialSize = output.getSize();
-    const storageSize = deps.storage.getSize(ownerIdBytes);
-    if (storageSize == null)
+    let storageSize;
+    try {
+        storageSize = deps.storage.getSize(ownerIdBytes);
+    }
+    catch (error) {
+        deps.console.error(error);
         return err(ProtocolErrorCode.SyncError);
+    }
     let prevUpperBound = null;
-    let prevIndex = NonNegativeInt.orThrow(0);
+    let prevIndex = zeroNonNegativeInt;
     let skip = false;
     let nonSkipRangeAdded = false;
     const skipRange = (range) => {
@@ -822,9 +885,14 @@ const sync = (deps) => (ranges, output, ownerIdBytes) => {
     };
     // When we don't have a space...
     const addFingerprintForRemainingRange = (begin) => {
-        const fingerprint = deps.storage.fingerprint(ownerIdBytes, begin, storageSize);
-        if (!fingerprint)
+        let fingerprint;
+        try {
+            fingerprint = deps.storage.fingerprint(ownerIdBytes, begin, storageSize);
+        }
+        catch (error) {
+            deps.console.error(error);
             return false;
+        }
         // There is always a space for a ramaining range.
         output.addRange({
             type: RangeType.Fingerprint,
@@ -836,18 +904,28 @@ const sync = (deps) => (ranges, output, ownerIdBytes) => {
     for (const range of ranges) {
         const currentUpperBound = range.upperBound;
         const lower = prevIndex;
-        let upper = deps.storage.findLowerBound(ownerIdBytes, prevIndex, storageSize, currentUpperBound);
-        if (upper == null)
+        let upper;
+        try {
+            upper = deps.storage.findLowerBound(ownerIdBytes, prevIndex, storageSize, currentUpperBound);
+        }
+        catch (error) {
+            deps.console.error(error);
             return err(ProtocolErrorCode.SyncError);
+        }
         switch (range.type) {
             case RangeType.Skip: {
                 skipRange(range);
                 break;
             }
             case RangeType.Fingerprint: {
-                const ourFingerprint = deps.storage.fingerprint(ownerIdBytes, lower, upper);
-                if (ourFingerprint == null)
+                let ourFingerprint;
+                try {
+                    ourFingerprint = deps.storage.fingerprint(ownerIdBytes, lower, upper);
+                }
+                catch (error) {
+                    deps.console.error(error);
                     return err(ProtocolErrorCode.SyncError);
+                }
                 if (eqArrayNumber(range.fingerprint, ourFingerprint)) {
                     skipRange(range);
                 }
@@ -868,38 +946,46 @@ const sync = (deps) => (ranges, output, ownerIdBytes) => {
                 let endBound = currentUpperBound;
                 const timestampsWeNeed = new Map(range.timestamps.map((t) => [t.join(), true]));
                 const ourTimestamps = createTimestampsBuffer();
-                let cantReadDbChange = false;
                 let exceeded = false;
-                deps.storage.iterate(ownerIdBytes, lower, upper, (timestamp, index) => {
-                    const timestampString = timestamp.join();
-                    const timestampBinary = timestampBytesToTimestamp(timestamp);
-                    let message = null;
-                    if (timestampsWeNeed.has(timestampString)) {
-                        timestampsWeNeed.delete(timestampString);
-                    }
-                    else {
-                        const dbChange = deps.storage.readDbChange(ownerIdBytes, timestamp);
-                        if (dbChange == null) {
-                            cantReadDbChange = true;
+                let iterateFailed = false;
+                try {
+                    deps.storage.iterate(ownerIdBytes, lower, upper, (timestamp, index) => {
+                        const timestampString = timestamp.join();
+                        const timestampBinary = timestampBytesToTimestamp(timestamp);
+                        let message = null;
+                        if (timestampsWeNeed.has(timestampString)) {
+                            timestampsWeNeed.delete(timestampString);
+                        }
+                        else {
+                            try {
+                                message = {
+                                    timestamp: timestampBinary,
+                                    change: deps.storage.readDbChange(ownerIdBytes, timestamp),
+                                };
+                            }
+                            catch (error) {
+                                deps.console.error(error);
+                                iterateFailed = true;
+                                return false;
+                            }
+                        }
+                        if (!output.canAddTimestampsRangeAndMessage(ourTimestamps, message)) {
+                            exceeded = true;
+                            endBound = timestamp;
+                            upper = index;
                             return false;
                         }
-                        message = {
-                            timestamp: timestampBinary,
-                            change: dbChange,
-                        };
-                    }
-                    if (!output.canAddTimestampsRangeAndMessage(ourTimestamps, message)) {
-                        exceeded = true;
-                        endBound = timestamp;
-                        upper = index;
-                        return false;
-                    }
-                    ourTimestamps.add(timestampBinary);
-                    if (message)
-                        output.addMessage(message);
-                    return true;
-                });
-                if (cantReadDbChange) {
+                        ourTimestamps.add(timestampBinary);
+                        if (message)
+                            output.addMessage(message);
+                        return true;
+                    });
+                }
+                catch (error) {
+                    deps.console.error(error);
+                    return err(ProtocolErrorCode.SyncError);
+                }
+                if (iterateFailed) {
                     return err(ProtocolErrorCode.SyncError);
                 }
                 const addRange = () => {
@@ -943,7 +1029,7 @@ const splitRange = (deps) => (ownerId, lower, upper, upperBound, buffer) => {
             upperBound,
             timestamps: createTimestampsBuffer(),
         };
-        deps.storage.iterate(ownerId, NonNegativeInt.orThrow(0), itemCount, (timestamp) => {
+        deps.storage.iterate(ownerId, zeroNonNegativeInt, itemCount, (timestamp) => {
             range.timestamps.add(timestampBytesToTimestamp(timestamp));
             return true;
         });
@@ -957,10 +1043,14 @@ const splitRange = (deps) => (ownerId, lower, upper, upperBound, buffer) => {
             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)
+    let fingerprintRanges;
+    try {
+        fingerprintRanges = deps.storage.fingerprintRanges(ownerId, fingerprintRangesBuckets, upperBound);
+    }
+    catch (error) {
+        deps.console.error(error);
         return;
+    }
     const rangesToUse = lower > 0 ? fingerprintRanges.slice(1) : fingerprintRanges;
     for (const range of rangesToUse) {
         buffer.addRange(range);
@@ -974,20 +1064,20 @@ const decodeRanges = (buffer) => {
         return [];
     const timestampsCount = NonNegativeInt.orThrow(rangesCount - 1);
     const timestamps = decodeTimestamps(buffer, timestampsCount);
-    const rangeTypes = [];
+    const rangeTypes = new Array(rangesCount);
     for (let i = 0; i < rangesCount; i++) {
         const rangeType = decodeNonNegativeInt(buffer);
         switch (rangeType) {
             case RangeType.Fingerprint:
             case RangeType.Skip:
             case RangeType.Timestamps:
-                rangeTypes.push(rangeType);
+                rangeTypes[i] = rangeType;
                 break;
             default:
                 throw new ProtocolDecodeError(`Invalid RangeType: ${rangeType}`);
         }
     }
-    const ranges = [];
+    const ranges = new Array(rangesCount);
     for (let i = 0; i < rangesCount; i++) {
         const upperBound = i < timestampsCount
             ? timestampToTimestampBytes(timestamps[i])
@@ -995,75 +1085,81 @@ const decodeRanges = (buffer) => {
         const rangeType = rangeTypes[i];
         switch (rangeType) {
             case RangeType.Skip:
-                ranges.push({ type: RangeType.Skip, upperBound });
+                ranges[i] = { type: RangeType.Skip, upperBound };
                 break;
             case RangeType.Fingerprint: {
                 const fingerprint = buffer.shiftN(fingerprintSize);
-                ranges.push({
+                ranges[i] = {
                     type: RangeType.Fingerprint,
                     upperBound,
                     fingerprint,
-                });
+                };
                 break;
             }
             case RangeType.Timestamps: {
                 const timestamps = decodeTimestamps(buffer).map(timestampToTimestampBytes);
-                ranges.push({
+                ranges[i] = {
                     type: RangeType.Timestamps,
                     upperBound,
                     timestamps,
-                });
+                };
                 break;
             }
         }
     }
     return ranges;
 };
-/** Decodes an array of sorted timestamps with delta-encoded millis. */
 const decodeTimestamps = (buffer, length) => {
     length ??= decodeNonNegativeInt(buffer);
     let previousMillis = 0;
-    const millises = [];
+    const millises = new Array(length);
     for (let i = 0; i < length; i++) {
         const deltaMillis = decodeNonNegativeInt(buffer);
         const millis = Millis.from(previousMillis + deltaMillis);
         if (!millis.ok)
             throw new ProtocolDecodeError(millis.error.type);
-        millises.push(millis.value);
+        millises[i] = millis.value;
         previousMillis = millis.value;
     }
-    const counters = [];
-    let counterIndex = 0;
-    while (counterIndex < length) {
+    const counters = decodeRle(buffer, length, () => {
         const counter = Counter.from(decodeNonNegativeInt(buffer));
         if (!counter.ok)
             throw new ProtocolDecodeError(counter.error.type);
-        const runLength = decodeNonNegativeInt(buffer);
-        for (let i = 0; i < runLength; i++) {
-            counters.push(counter.value);
-            counterIndex++;
-        }
-    }
-    const nodeIds = [];
-    let nodeIdIndex = 0;
-    while (nodeIdIndex < length) {
-        const nodeId = decodeNodeId(buffer);
-        const runLength = decodeNonNegativeInt(buffer);
-        for (let i = 0; i < runLength; i++) {
-            nodeIds.push(nodeId);
-            nodeIdIndex++;
-        }
-    }
-    const timestamps = [];
+        return counter.value;
+    });
+    const nodeIds = decodeRle(buffer, length, () => decodeNodeId(buffer));
+    const timestamps = new Array(length);
     for (let i = 0; i < length; i++) {
-        timestamps.push({
+        timestamps[i] = {
             millis: millises[i],
             counter: counters[i],
             nodeId: nodeIds[i],
-        });
+        };
     }
     return timestamps;
 };
+export const decodeRle = (buffer, length, decodeValue) => {
+    const values = new Array(length);
+    let index = 0;
+    while (index < length) {
+        const value = decodeValue();
+        const runLength = decodeNonNegativeInt(buffer);
+        // Prevent infinite loop on malformed input.
+        if (runLength === 0) {
+            throw new ProtocolDecodeError("Invalid RLE encoding: runLength must be positive");
+        }
+        const remaining = length - index;
+        // Prevent CPU/memory amplification via oversized runLength.
+        if (runLength > remaining) {
+            throw new ProtocolDecodeError(`Invalid RLE encoding: runLength ${runLength} exceeds remaining ${remaining}`);
+        }
+        for (let i = 0; i < runLength; i++) {
+            values[index] = value;
+            index++;
+        }
+    }
+    return values;
+};
 const decodeId = (buffer) => {
     const bytes = buffer.shiftN(idBytesTypeValueLength);
     return idBytesToId(bytes);
@@ -1124,9 +1220,10 @@ export const encodeFlags = (buffer, 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);
+    const length = globalThis.Math.min(count, 8);
+    const flags = new Array(length);
+    for (let i = 0; i < length; i++) {
+        flags[i] = (byte & (1 << i)) !== 0;
     }
     return flags;
 };
@@ -1146,6 +1243,7 @@ export const encodeAndEncryptDbChange = (deps) => (message, key) => {
     buffer.extend(timestampToTimestampBytes(message.timestamp));
     encodeFlags(buffer, [
         message.change.isInsert,
+        // Encode nullable boolean as two flags: presence + value.
         message.change.isDelete != null,
         message.change.isDelete ?? false,
     ]);
@@ -1159,7 +1257,7 @@ export const encodeAndEncryptDbChange = (deps) => (message, key) => {
     }
     // Add PADMÉ padding (ignored during decoding)
     buffer.extend(createPadmePadding(buffer.getLength()));
-    const { nonce, ciphertext } = deps.symmetricCrypto.encrypt(buffer.unwrap(), key);
+    const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(buffer.unwrap(), key);
     buffer.reset();
     buffer.extend(nonce);
     encodeLength(buffer, ciphertext);
@@ -1171,19 +1269,19 @@ export const encodeAndEncryptDbChange = (deps) => (message, key) => {
  * owner's encryption key. Verifies that the embedded timestamp matches the
  * expected timestamp to ensure message integrity.
  */
-export const decryptAndDecodeDbChange = (deps) => (message, key) => {
+export const decryptAndDecodeDbChange = (message, key) => {
     try {
         const buffer = createBuffer(message.change);
-        const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
+        const nonce = buffer.shiftN(xChaCha20Poly1305NonceLength);
         const ciphertext = buffer.shiftN(decodeLength(buffer));
-        const plaintextBytes = deps.symmetricCrypto.decrypt(ciphertext, key, nonce);
+        const plaintextBytes = decryptWithXChaCha20Poly1305(XChaCha20Poly1305Ciphertext.orThrow(ciphertext), Entropy24.orThrow(nonce), key);
         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));
+        const timestamp = timestampBytesToTimestamp(TimestampBytes.orThrow(buffer.shiftN(timestampBytesLength)));
         if (!eqTimestamp(timestamp, message.timestamp)) {
             return err({
                 type: "ProtocolTimestampMismatchError",
@@ -1289,23 +1387,23 @@ const isSmallInt = (value) => value >= 0 && value < 20;
 export const ProtocolValueType = {
     // 0-19 small ints
     // SQLite types
-    String: NonNegativeInt.orThrow(20),
-    Number: NonNegativeInt.orThrow(21),
-    Null: NonNegativeInt.orThrow(22),
-    Bytes: NonNegativeInt.orThrow(23),
+    String: /*#__PURE__*/ NonNegativeInt.orThrow(20),
+    Number: /*#__PURE__*/ NonNegativeInt.orThrow(21),
+    Null: /*#__PURE__*/ NonNegativeInt.orThrow(22),
+    Bytes: /*#__PURE__*/ NonNegativeInt.orThrow(23),
     // We can add more types for other DBs or anything else later.
     // Optimized types
-    NonNegativeInt: NonNegativeInt.orThrow(30),
+    NonNegativeInt: /*#__PURE__*/ 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),
+    EmptyString: /*#__PURE__*/ NonNegativeInt.orThrow(31), // 1 byte vs 2 bytes (50% reduction)
+    Base64Url: /*#__PURE__*/ NonNegativeInt.orThrow(32),
+    Id: /*#__PURE__*/ NonNegativeInt.orThrow(33),
+    Json: /*#__PURE__*/ NonNegativeInt.orThrow(34),
     // new Date().toISOString()   - 24 bytes
     // encoded with fixed length  - 8 bytes
     // encode as NonNegativeInt   - 6 bytes (additional 25% reduction)
-    DateIsoWithNonNegativeTime: NonNegativeInt.orThrow(35),
-    DateIsoWithNegativeTime: NonNegativeInt.orThrow(36), // 9 bytes
+    DateIsoWithNonNegativeTime: /*#__PURE__*/ NonNegativeInt.orThrow(35),
+    DateIsoWithNegativeTime: /*#__PURE__*/ NonNegativeInt.orThrow(36), // 9 bytes
     // TODO: Operations (from 40)
     // Increment, Decrement, Patch, whatever.
 };