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

package/dist/src/Evolu/Protocol.d.ts

@@ -3,33 +3,54 @@
  *
  * 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.
- *
- * ### 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}                |                            |
- *
- * Every protocol message belongs to an {@link Owner}.
+ * transfer, ownership, real-time broadcasting, request-response semantics, and
+ * error handling.
+ *
+ * ### Message structure
+ *
+ * | 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
+ *
+ * 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,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 ProtocolSyncError}: A serious relay-side synchronization failure
  *   occurred.
+ * - {@link ProtocolQuotaExceededError}: Storage or billing quota exceeded.
  * - {@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
+ * ### 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?
  *
@@ -82,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.
@@ -118,26 +148,94 @@
  * 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 { NonEmptyReadonlyArray } from "../Array.js";
+import { Brand } from "../Brand.js";
 import { Buffer } from "../Buffer.js";
-import { CreateRandomBytesDep, EncryptionKey, SymmetricCryptoDecryptError, SymmetricCryptoDep } from "../Crypto.js";
-import { ReadonlyRecord } from "../Object.js";
+import { EncryptionKey, RandomBytesDep, SymmetricCryptoDecryptError, SymmetricCryptoDep } from "../Crypto.js";
 import { Result } from "../Result.js";
 import { SqliteValue } from "../Sqlite.js";
-import { Id, NanoId, NonNegativeInt, PositiveInt } from "../Type.js";
-import { Brand } from "../Types.js";
-import { OwnerId, OwnerWithWriteAccess, WriteKey } from "./Owner.js";
-import { BinaryTimestamp, NodeId, Timestamp } from "./Timestamp.js";
-/** Maximum size of the entire protocol message in bytes. */
-export declare const maxProtocolMessageSize: PositiveInt;
-/** Maximum size of the ranges in bytes. */
-export declare const maxProtocolMessageRangesSize: PositiveInt;
+import { NonNegativeInt, PositiveInt } from "../Type.js";
+import { Owner, OwnerId, OwnerWriteKey } from "./Owner.js";
+import { BaseRange, CrdtMessage, DbChange, EncryptedCrdtMessage, EncryptedDbChange, FingerprintRange, RangeType, SkipRange, StorageDep } from "./Storage.js";
+import { NodeId, Timestamp } from "./Timestamp.js";
+/**
+ * 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 declare const ProtocolMessageMaxSize: import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int">, number, import("../Type.js").IntError, number, import("../Type.js").NumberError>, "Between1000000-100000000", import("../Type.js").BetweenError<1000000, 100000000>, import("../Type.js").IntError | import("../Type.js").NumberError>;
+export type ProtocolMessageMaxSize = typeof ProtocolMessageMaxSize.Type;
+/**
+ * Default {@link ProtocolMessageMaxSize} (1MB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export declare const defaultProtocolMessageMaxSize: ProtocolMessageMaxSize;
+/**
+ * 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 declare const ProtocolMessageRangesMaxSize: import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int">, number, import("../Type.js").IntError, number, import("../Type.js").NumberError>, "Between3000-100000", import("../Type.js").BetweenError<3000, 100000>, import("../Type.js").IntError | import("../Type.js").NumberError>;
+export type ProtocolMessageRangesMaxSize = typeof ProtocolMessageRangesMaxSize.Type;
+/**
+ * Default {@link ProtocolMessageRangesMaxSize} (30KB).
+ *
+ * The standard size used across Evolu implementations. Relays with more
+ * resources can configure larger sizes to reduce roundtrips.
+ */
+export declare const defaultProtocolMessageRangesMaxSize: ProtocolMessageRangesMaxSize;
 /** Evolu Protocol Message. */
 export type ProtocolMessage = Uint8Array & Brand<"ProtocolMessage">;
 /** Evolu Protocol version. */
 export declare const protocolVersion: NonNegativeInt;
+export declare const MessageType: {
+    /** Request message from initiator (client) to non-initiator (relay). */
+    readonly Request: 0;
+    /** Response message from non-initiator (relay) to initiator (client). */
+    readonly Response: 1;
+    /** Broadcast message from non-initiator (relay) to subscribed clients. */
+    readonly Broadcast: 2;
+};
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+export declare const SubscriptionFlags: {
+    /** No subscription changes for this owner. */
+    readonly None: 0;
+    /** Subscribe to updates for this owner. */
+    readonly Subscribe: 1;
+    /** Unsubscribe from updates for this owner. */
+    readonly Unsubscribe: 2;
+};
+export type SubscriptionFlag = (typeof SubscriptionFlags)[keyof typeof SubscriptionFlags];
 export declare const ProtocolErrorCode: {
     readonly NoError: 0;
     /** A code for {@link ProtocolWriteKeyError}. */
@@ -146,112 +244,11 @@ export declare const ProtocolErrorCode: {
     readonly WriteError: 2;
     /** A code for {@link ProtocolSyncError}. */
     readonly SyncError: 3;
+    /** A code for {@link ProtocolQuotaExceededError}. */
+    readonly QuotaExceededError: 4;
 };
 type ProtocolErrorCode = (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
-/**
- * Evolu Protocol Storage
- *
- * The protocol is agnostic to storage implementation details—any storage can be
- * plugged in, as long as it implements this interface. Implementations must
- * handle their own errors; return values only indicates overall success or
- * failure.
- */
-export interface Storage {
-    readonly getSize: (ownerId: BinaryOwnerId) => NonNegativeInt | null;
-    readonly fingerprint: (ownerId: BinaryOwnerId, begin: NonNegativeInt, end: NonNegativeInt) => Fingerprint | null;
-    /**
-     * Computes fingerprints with their upper bounds in one call.
-     *
-     * This function can be replaced with many fingerprint/findLowerBound calls,
-     * but implementations can leverage it for batching and more efficient
-     * fingerprint computation.
-     */
-    readonly fingerprintRanges: (ownerId: BinaryOwnerId, buckets: ReadonlyArray<NonNegativeInt>, upperBound?: RangeUpperBound) => ReadonlyArray<FingerprintRange> | null;
-    readonly findLowerBound: (ownerId: BinaryOwnerId, begin: NonNegativeInt, end: NonNegativeInt, upperBound: RangeUpperBound) => NonNegativeInt | null;
-    readonly iterate: (ownerId: BinaryOwnerId, begin: NonNegativeInt, end: NonNegativeInt, callback: (timestamp: BinaryTimestamp, index: NonNegativeInt) => boolean) => void;
-    /**
-     * Authorizes the initiator's {@link WriteKey} for the given
-     * {@link BinaryOwnerId}.
-     *
-     * For a client that does not expect foreign writes, return `false`.
-     */
-    readonly validateWriteKey: (ownerId: BinaryOwnerId, writeKey: WriteKey) => boolean;
-    /** Write encrypted {@link CrdtMessage}s to storage. */
-    readonly writeMessages: (ownerId: BinaryOwnerId, messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>) => boolean;
-    /** Read encrypted {@link DbChange}s from storage. */
-    readonly readDbChange: (ownerId: BinaryOwnerId, timestamp: BinaryTimestamp) => EncryptedDbChange | null;
-}
-export interface StorageDep {
-    readonly storage: Storage;
-}
-/** An encrypted {@link CrdtMessage}. */
-export interface EncryptedCrdtMessage {
-    readonly timestamp: Timestamp;
-    readonly change: EncryptedDbChange;
-}
-/** Encrypted DbChange */
-export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
-/**
- * A CRDT message that combines a unique {@link Timestamp} with a
- * {@link DbChange}.
- */
-export interface CrdtMessage {
-    readonly timestamp: Timestamp;
-    readonly change: DbChange;
-}
-/**
- * A DbChange is a change to a table row. Together with a unique
- * {@link Timestamp}, it forms a {@link CrdtMessage}.
- */
-export interface DbChange {
-    readonly table: Base64Url256;
-    readonly id: Id;
-    readonly values: ReadonlyRecord<Base64Url256, SqliteValue>;
-}
-export declare const RangeType: {
-    readonly Fingerprint: 1;
-    readonly Skip: 0;
-    readonly Timestamps: 2;
-};
-export type RangeType = (typeof RangeType)[keyof typeof RangeType];
-export declare const InfiniteUpperBound: unique symbol;
-export type InfiniteUpperBound = typeof InfiniteUpperBound;
-/**
- * Union type for Range's upperBound: either a {@link BinaryTimestamp} or
- * {@link InfiniteUpperBound}.
- */
-export type RangeUpperBound = BinaryTimestamp | InfiniteUpperBound;
-interface BaseRange {
-    readonly upperBound: RangeUpperBound;
-}
-export interface SkipRange extends BaseRange {
-    readonly type: typeof RangeType.Skip;
-}
-export interface FingerprintRange extends BaseRange {
-    readonly type: typeof RangeType.Fingerprint;
-    readonly fingerprint: Fingerprint;
-}
-/**
- * A cryptographic hash used for efficiently comparing collections of
- * {@link BinaryTimestamp}s.
- *
- * It consists of the first {@link fingerprintSize} bytes of the SHA-256 hash of
- * one or more timestamps.
- */
-export type Fingerprint = Uint8Array & Brand<"Fingerprint">;
-export declare const fingerprintSize: NonNegativeInt;
-/** A fingerprint of an empty range. */
-export declare const zeroFingerprint: Fingerprint;
-export interface TimestampsRange extends BaseRange {
-    readonly type: typeof RangeType.Timestamps;
-    readonly timestamps: ReadonlyArray<BinaryTimestamp>;
-}
-export interface TimestampsRangeWithTimestampsBuffer extends BaseRange {
-    readonly type: typeof RangeType.Timestamps;
-    readonly timestamps: TimestampsBuffer;
-}
-export type Range = SkipRange | FingerprintRange | TimestampsRange;
-export type ProtocolError = ProtocolUnsupportedVersionError | ProtocolInvalidDataError | ProtocolWriteKeyError | ProtocolWriteError | ProtocolSyncError;
+export type ProtocolError = ProtocolUnsupportedVersionError | ProtocolInvalidDataError | ProtocolWriteKeyError | ProtocolWriteError | ProtocolSyncError | ProtocolQuotaExceededError | ProtocolTimestampMismatchError;
 /** Base interface for all protocol errors. */
 export interface ProtocolErrorBase {
     readonly ownerId: OwnerId;
@@ -272,34 +269,55 @@ export interface ProtocolInvalidDataError {
     readonly data: globalThis.Uint8Array;
     readonly error: unknown;
 }
-/** Error when a {@link WriteKey} is invalid, missing, or fails validation. */
+/** Error when a {@link OwnerWriteKey} is invalid, missing, or fails validation. */
 export interface ProtocolWriteKeyError extends ProtocolErrorBase {
     readonly type: "ProtocolWriteKeyError";
 }
 /**
- * Error when a write fails due to storage limits or billing requirements.
- * Indicates the need to expand capacity or resolve payment issues.
+ * Error indicating a serious relay-side write failure. Clients should log this
+ * error and show a generic sync error to the user.
  */
 export interface ProtocolWriteError extends ProtocolErrorBase {
     readonly type: "ProtocolWriteError";
 }
 /**
- * Error indicating a synchronization failure during the protocol exchange. Used
- * for unexpected or generic sync errors not covered by other error types.
+ * Error indicating a serious relay-side synchronization failure. Clients should
+ * log this error and show a generic sync error to the user.
  */
 export interface ProtocolSyncError extends ProtocolErrorBase {
     readonly type: "ProtocolSyncError";
 }
+/**
+ * Error when storage or billing quota is exceeded. Clients should prompt the
+ * user to upgrade their plan or expand capacity.
+ *
+ * TODO: Add callback to relay config to check quota and return this error when
+ * limits are reached.
+ */
+export interface ProtocolQuotaExceededError extends ProtocolErrorBase {
+    readonly type: "ProtocolQuotaExceededError";
+}
+/**
+ * Error when embedded timestamp doesn't match expected timestamp in
+ * EncryptedDbChange. Indicates potential tampering or corruption of CRDT
+ * messages.
+ */
+export interface ProtocolTimestampMismatchError {
+    readonly type: "ProtocolTimestampMismatchError";
+    readonly expected: Timestamp;
+    readonly embedded: Timestamp;
+}
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
- * 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 declare const createProtocolMessageFromCrdtMessages: (deps: SymmetricCryptoDep & CreateRandomBytesDep) => (owner: OwnerWithWriteAccess, messages: NonEmptyReadonlyArray<CrdtMessage>, maxSize?: PositiveInt) => ProtocolMessage;
+export declare const createProtocolMessageFromCrdtMessages: (deps: RandomBytesDep & SymmetricCryptoDep) => (owner: Owner, messages: NonEmptyReadonlyArray<CrdtMessage>, maxSize?: ProtocolMessageMaxSize) => ProtocolMessage;
 /** Creates a {@link ProtocolMessage} for sync. */
-export declare const createProtocolMessageForSync: (deps: StorageDep) => (ownerId: OwnerId) => ProtocolMessage | null;
+export declare const createProtocolMessageForSync: (deps: StorageDep) => (ownerId: OwnerId, subscriptionFlag?: SubscriptionFlag) => ProtocolMessage | null;
+export declare const createProtocolMessageForUnsubscribe: (ownerId: OwnerId) => ProtocolMessage;
 /**
  * Mutable builder for constructing {@link ProtocolMessage} respecting size
  * limits.
@@ -313,13 +331,24 @@ export interface ProtocolMessageBuffer {
     readonly unwrap: () => ProtocolMessage;
     readonly getSize: () => PositiveInt;
 }
-export declare const createProtocolMessageBuffer: (ownerId: OwnerId, options?: {
-    readonly errorCode?: ProtocolErrorCode;
-    readonly writeKey?: WriteKey;
-    readonly totalMaxSize?: PositiveInt | undefined;
-    readonly rangesMaxSize?: PositiveInt | undefined;
+export declare const createProtocolMessageBuffer: (ownerId: OwnerId, options: {
+    readonly totalMaxSize?: ProtocolMessageMaxSize | undefined;
+    readonly rangesMaxSize?: ProtocolMessageRangesMaxSize | undefined;
     readonly version?: NonNegativeInt;
-}) => ProtocolMessageBuffer;
+} & ({
+    readonly messageType: typeof MessageType.Request;
+    readonly writeKey?: OwnerWriteKey;
+    readonly subscriptionFlag?: SubscriptionFlag;
+} | {
+    readonly messageType: typeof MessageType.Response;
+    readonly errorCode: ProtocolErrorCode;
+} | {
+    readonly messageType: typeof MessageType.Broadcast;
+})) => ProtocolMessageBuffer;
+export interface TimestampsRangeWithTimestampsBuffer extends BaseRange {
+    readonly type: typeof RangeType.Timestamps;
+    readonly timestamps: TimestampsBuffer;
+}
 export interface TimestampsBuffer {
     readonly add: (timestamp: Timestamp) => void;
     readonly addInfinite: () => void;
@@ -329,67 +358,71 @@ export interface TimestampsBuffer {
 }
 export declare const createTimestampsBuffer: () => TimestampsBuffer;
 export interface ApplyProtocolMessageAsClientOptions {
-    getWriteKey?: (ownerId: OwnerId) => WriteKey | null;
+    getWriteKey?: (ownerId: OwnerId) => OwnerWriteKey | null;
     /** For testing purposes only; should not be used in production. */
     version?: NonNegativeInt;
-    totalMaxSize?: PositiveInt;
-    rangesMaxSize?: PositiveInt;
+    rangesMaxSize?: ProtocolMessageRangesMaxSize;
 }
-export declare const applyProtocolMessageAsClient: (deps: StorageDep) => (inputMessage: Uint8Array, { getWriteKey, version, totalMaxSize, rangesMaxSize, }?: ApplyProtocolMessageAsClientOptions) => Result<ProtocolMessage | null, ProtocolError>;
+/**
+ * Result type for {@link applyProtocolMessageAsClient} that distinguishes
+ * between responses to client requests and broadcast messages.
+ */
+export type ApplyProtocolMessageAsClientResult = {
+    readonly type: "response";
+    readonly message: ProtocolMessage;
+} | {
+    readonly type: "no-response";
+} | {
+    readonly type: "broadcast";
+};
+export declare const applyProtocolMessageAsClient: (deps: StorageDep) => (inputMessage: Uint8Array, options?: ApplyProtocolMessageAsClientOptions) => Promise<Result<ApplyProtocolMessageAsClientResult, ProtocolInvalidDataError | ProtocolSyncError | ProtocolUnsupportedVersionError | ProtocolWriteError | ProtocolWriteKeyError | ProtocolQuotaExceededError>>;
 export interface ApplyProtocolMessageAsRelayOptions {
     /** To subscribe an owner for broadcasting. */
     subscribe?: (ownerId: OwnerId) => void;
+    /** To unsubscribe an owner from broadcasting. */
+    unsubscribe?: (ownerId: OwnerId) => void;
     /** To broadcast a protocol message to all subscribers. */
     broadcast?: (ownerId: OwnerId, message: ProtocolMessage) => void;
-    totalMaxSize?: PositiveInt;
-    rangesMaxSize?: PositiveInt;
+    totalMaxSize?: ProtocolMessageMaxSize;
+    rangesMaxSize?: ProtocolMessageRangesMaxSize;
 }
-export declare const applyProtocolMessageAsRelay: (deps: StorageDep) => (inputMessage: Uint8Array, { subscribe, broadcast, totalMaxSize, rangesMaxSize, }?: ApplyProtocolMessageAsRelayOptions, 
-/** For testing purposes only; should not be used in production. */
-version?: number & Brand<"Int"> & Brand<"NonNegative">) => Result<ProtocolMessage | null, ProtocolInvalidDataError>;
-/** Binary representation of {@link Id}. */
-export type BinaryId = Uint8Array & Brand<"BinaryId">;
-export declare const binaryIdLength: NonNegativeInt;
-export declare const idToBinaryId: (id: Id) => BinaryId;
-export declare const binaryIdToId: (binaryId: BinaryId) => Id;
-/** Binary representation of {@link OwnerId}. */
-export type BinaryOwnerId = Uint8Array & Brand<"BinaryOwnerId">;
-export declare const ownerIdToBinaryOwnerId: (ownerId: OwnerId) => BinaryOwnerId;
-export declare const binaryOwnerIdToOwnerId: (binaryOwnerId: BinaryOwnerId) => OwnerId;
-/**
- * Base64Url string with maximum length of 256 characters. Encoding strings as
- * Base64UrlString saves up to 25% in size compared to regular strings.
- */
-export declare const Base64Url256: import("../Type.js").BrandType<import("../Type.js").Type<"Brand", string & Brand<"Base64Url">, string, import("../Type.js").RegexError<"Base64Url">, string, import("../Type.js").StringError>, "MaxLength256", import("../Type.js").MaxLengthError<256>, import("../Type.js").StringError | import("../Type.js").RegexError<"Base64Url">>;
-export type Base64Url256 = typeof Base64Url256.Type;
-/**
- * Union type for all variants of Base64Url strings with limited length. All
- * these types use Base64Url alphabet and are < 256 characters.
- */
-export type Base64Url256Variant = Base64Url256 | Id | NanoId | OwnerId;
 /**
- * Converts a Base64Url string to a Uint8Array for binary storage. This encoding
- * is more space-efficient than UTF-8 for Base64Url strings.
+ * Result type for {@link applyProtocolMessageAsRelay}.
+ *
+ * Unlike {@link ApplyProtocolMessageAsClientResult}, relays always respond with
+ * a message to provide sync completion feedback. This ensures the initiator can
+ * reliably detect when synchronization is complete, even when there's nothing
+ * to sync. Clients may choose not to respond in certain cases (like when they
+ * receive broadcast messages or when they lack a write key for syncing).
  */
-export declare const base64Url256ToBytes: (string: Base64Url256Variant) => globalThis.Uint8Array;
-export declare const decodeBase64Url256: (buffer: Buffer, stringLength: number) => Base64Url256Variant;
+export interface ApplyProtocolMessageAsRelayResult {
+    readonly type: "response";
+    readonly message: ProtocolMessage;
+}
+export declare const applyProtocolMessageAsRelay: (deps: StorageDep) => (inputMessage: Uint8Array, options?: ApplyProtocolMessageAsRelayOptions, 
+/** For testing purposes only; should not be used in production. */
+version?: number & Brand<"Int"> & Brand<"NonNegative">) => Promise<Result<ApplyProtocolMessageAsRelayResult, ProtocolInvalidDataError>>;
 /**
  * Evolu uses MessagePack to handle all number variants except for
  * NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
  */
 export declare const encodeNumber: (buffer: Buffer, number: number) => void;
 export declare const decodeNumber: (buffer: Buffer) => number;
-export declare const binaryTimestampToFingerprint: (timestamp: BinaryTimestamp) => Fingerprint;
 /**
  * Encodes and encrypts a {@link DbChange} using the provided owner's encryption
  * key. Returns an encrypted binary representation as {@link EncryptedDbChange}.
+ *
+ * The format includes the protocol version for backward compatibility and the
+ * timestamp for tamper-proof verification that the timestamp matches the change
+ * data.
  */
-export declare const encodeAndEncryptDbChange: (deps: SymmetricCryptoDep) => (change: DbChange, key: EncryptionKey) => EncryptedDbChange;
+export declare const encodeAndEncryptDbChange: (deps: SymmetricCryptoDep) => (message: CrdtMessage, key: EncryptionKey) => EncryptedDbChange;
 /**
- * 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 declare const decryptAndDecodeDbChange: (deps: SymmetricCryptoDep) => (change: EncryptedDbChange, key: EncryptionKey) => Result<DbChange, SymmetricCryptoDecryptError | ProtocolInvalidDataError>;
+export declare const decryptAndDecodeDbChange: (deps: SymmetricCryptoDep) => (message: EncryptedCrdtMessage, key: EncryptionKey) => Result<DbChange, SymmetricCryptoDecryptError | ProtocolInvalidDataError | ProtocolTimestampMismatchError>;
 /**
  * Encodes a non-negative integer into a variable-length integer format. It's
  * more efficient than encoding via {@link encodeNumber}.
@@ -409,21 +442,33 @@ export declare const encodeString: (buffer: Buffer, value: string) => void;
 export declare const decodeString: (buffer: Buffer) => string;
 export declare const encodeNodeId: (buffer: Buffer, nodeId: NodeId) => void;
 export declare const decodeNodeId: (buffer: Buffer) => NodeId;
-export declare const encodeBase64Url256: (buffer: Buffer, string: Base64Url256Variant) => void;
-export declare const decodeBase64Url256WithLength: (buffer: Buffer) => Base64Url256;
 export declare const ProtocolValueType: {
     readonly String: NonNegativeInt;
     readonly Number: NonNegativeInt;
     readonly Null: NonNegativeInt;
-    readonly Binary: NonNegativeInt;
-    readonly Id: NonNegativeInt;
-    readonly Base64Url256: NonNegativeInt;
+    readonly Bytes: NonNegativeInt;
     readonly NonNegativeInt: NonNegativeInt;
+    readonly EmptyString: NonNegativeInt;
+    readonly Base64Url: NonNegativeInt;
+    readonly Id: NonNegativeInt;
     readonly Json: NonNegativeInt;
     readonly DateIsoWithNonNegativeTime: NonNegativeInt;
     readonly DateIsoWithNegativeTime: NonNegativeInt;
 };
 export declare const encodeSqliteValue: (buffer: Buffer, value: SqliteValue) => void;
 export declare const decodeSqliteValue: (buffer: Buffer) => SqliteValue;
+/**
+ * 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 declare const decodeProtocolMessageToJson: (_protocolMessage: ProtocolMessage, _isInitiator: boolean) => unknown;
 export {};
 //# sourceMappingURL=Protocol.d.ts.map