Wire Protocol

ConvergeDB uses a custom binary protocol over TCP. All multi-byte integers are little-endian.

Frame format

Every message is a frame: a 12-byte header followed by a variable-length payload.

┌─────────┬───────┬──────────┬────────┬──────────────┬───────┐
│ version │ flags │ stream   │ opcode │ payload_len  │ crc16 │
│ u8      │ u8    │ u16 LE   │ u16 LE │ u32 LE       │ u16 LE│
│ (1B)    │ (1B)  │ (2B)     │ (2B)   │ (4B)         │ (2B)  │
└─────────┴───────┴──────────┴────────┴──────────────┴───────┘

• version: Protocol version (currently 1).
• flags: Reserved, currently 0.
• stream_id: Correlates request/response pairs. 0 for fire-and-forget operations.
• opcode: Identifies the frame type (see below).
• payload_len: Byte length of the payload following the header.
• crc16: CRC-16/XMODEM over the first 10 header bytes.

Opcodes

Client to server

Opcode	Value	Description
CONNECT	0x01	Source authentication and connection setup.
ASSERT	0x02	Assert full entity state (fire-and-forget).
RETRACT	0x03	Retract entity assertion (fire-and-forget).
QUERY	0x04	Point read (request-response via stream_id).
SUBSCRIBE	0x05	Subscribe to entity kind changes.
UNSUBSCRIBE	0x06	Cancel a subscription.
HEARTBEAT	0x07	Keep-alive.
PATCH	0x08	Partial field update with presence bitmask.
SOURCE_EPOCH_BEGIN	0x09	Begin source epoch reconciliation.
SOURCE_EPOCH_END	0x0A	End source epoch, retract stale entities.
BATCH	0x0B	Batch of mixed write operations (ADR-0009).
CREATE_KIND	0x10	Register a new entity kind.
GET_KIND	0x11	Read-only schema resolution.

Server to client

Opcode	Value	Description
STATE	0x81	Entity state notification (created, updated, or bootstrap).
DELETED	0x82	Entity deleted notification.
BOOTSTRAP_BEGIN	0x83	Bootstrap snapshot start marker.
BOOTSTRAP_END	0x84	Bootstrap snapshot end marker.
ACK	0x85	Acknowledgement.
ERROR	0x86	Error response.
EVENT	0x87	Per-assert event for event-stream kinds.

BATCH payload format

The BATCH opcode packs multiple write operations into a single frame. The SDK uses this transparently when flushing more than one buffered operation.

op_count (u16 LE)
[sub-op]*

Each sub-op starts with an op_type byte matching the corresponding individual opcode, followed by the operation’s fields. Every sub-op ends with an explicit meta_len(u16 LE) + metadata section, even when metadata is empty (2 zero bytes).

Assert sub-op (op_type 0x02)

op_type(u8) + kind_id(u16) + entity_id(32B) + fd_len(u32) + field_data + meta_len(u16) + metadata

Retract sub-op (op_type 0x03)

op_type(u8) + kind_id(u16) + entity_id(32B) + meta_len(u16) + metadata

Patch sub-op (op_type 0x08)

op_type(u8) + kind_id(u16) + entity_id(32B) + presence_mask(u64) + fd_len(u32) + field_data + meta_len(u16) + metadata

Server-side processing

When the server receives a BATCH frame, it decodes all sub-ops, groups them by target partition (determined by hashing kind_id + entity_id), and sends a single batched message per partition to the engine thread. This reduces per-partition channel pressure from N messages to 1 per partition touched by the batch.