Data Structures

This document specifies every data structure used in AgenticComm's core library and persistence layer. All structures are defined in Rust and serialized using bincode for on-disk storage. Field-level constraints, defaults, and invariants are documented for each structure.

Message

The fundamental unit of communication. Every message is immutable after creation -- once persisted, its fields cannot be modified.

Fields

MessageType Enum

#[repr(u8)]
pub enum MessageType {
    Text = 0,
    Command = 1,
    Query = 2,
    Response = 3,
    Broadcast = 4,
    Notification = 5,
    Acknowledgment = 6,
    Error = 7,
}

Serialized as a single u8. Values 8-255 are reserved for future message types and must be rejected by parsers.

MessageStatus Enum

#[repr(u8)]
pub enum MessageStatus {
    Created = 0,
    Sent = 1,
    Delivered = 2,
    Acknowledged = 3,
    Failed = 4,
    DeadLetter = 5,
    Archived = 6,
}

Priority Enum

#[repr(u8)]
pub enum Priority {
    Critical = 0,
    High = 1,
    Normal = 2,
    Low = 3,
    Background = 4,
}

Validation Rules for Message

• sender must be non-empty and at most 128 bytes. Must match pattern [a-zA-Z0-9_-]+.
• content must be non-empty. Maximum 1,048,576 bytes.
• topic, if present, must be non-empty, at most 256 bytes, and match pattern [a-zA-Z0-9_-]+(\.[a-zA-Z0-9_*#-]+)*.
• correlation_id, if present, must be a valid UUID v4 string.
• ttl, if present, must be > 0.
• channel_id must refer to an existing channel in the store.

Channel

A named communication context. Channels own messages and define delivery semantics.

Fields

ChannelType Enum

#[repr(u8)]
pub enum ChannelType {
    Direct = 0,
    Group = 1,
    Broadcast = 2,
    PubSub = 3,
}

ChannelState Enum

#[repr(u8)]
pub enum ChannelState {
    Active = 0,
    Paused = 1,
    Draining = 2,
    Closed = 3,
}

Validation Rules for Channel

• name must be non-empty, at most 128 bytes. Must match pattern [a-zA-Z0-9_-]+(/[a-zA-Z0-9_-]+)*. Slashes are allowed for hierarchical naming (e.g., team/backend/alerts).
• owner must be a valid participant ID.
• Direct channels must have exactly 2 participants.
• Broadcast channels must have exactly 1 participant with Owner role.
• Channel names must be unique within a store.
• Maximum 100 tags per channel, each tag at most 64 bytes.

Participant

A member of a channel with an assigned role.

Fields

ParticipantRole Enum

#[repr(u8)]
pub enum ParticipantRole {
    Owner = 0,
    Member = 1,
    Observer = 2,
}

Subscription

A pub/sub subscription linking a participant to a topic pattern on a channel.

Fields

MatchMode Enum

#[repr(u8)]
pub enum MatchMode {
    Exact = 0,    // "build.frontend.complete"
    Wildcard = 1, // "build.*.complete" (single segment wildcard)
    MultiLevel = 2, // "build.#" (zero or more segments)
}

Match mode is inferred from the topic pattern at subscription creation time. Patterns containing * are Wildcard. Patterns ending with # are MultiLevel. All other patterns are Exact.

ChannelConfig

Configuration controlling channel behavior.

Fields

DeliveryMode Enum

#[repr(u8)]
pub enum DeliveryMode {
    AtMostOnce = 0,  // Fire and forget. No retry.
    AtLeastOnce = 1, // Retry until acknowledged or max_retries exhausted.
    ExactlyOnce = 2, // Deduplication + at-least-once. Requires correlation_id.
}

RetentionPolicy Enum

pub enum RetentionPolicy {
    Forever,
    Duration(u64),  // seconds
    Count(u64),     // max messages
    Size(u64),      // max bytes
}

Serialized as: tag byte (0=Forever, 1=Duration, 2=Count, 3=Size) followed by a u64 value for non-Forever variants.

MessageFilter

A filter used to query messages by various criteria.

Fields

SortField Enum

pub enum SortField {
    CreatedAt,
    Priority,
    Sender,
    MessageType,
}

SortOrder Enum

pub enum SortOrder {
    Ascending,
    Descending,
}

MessageMetadata

Structured key-value metadata attached to a message. Used for application-specific data that does not fit into the core message fields.

Fields

MetadataValue Enum

pub enum MetadataValue {
    String(String),   // Max 4096 bytes
    Integer(i64),
    Float(f64),
    Boolean(bool),
    Null,
}

Metadata is serialized as a length-prefixed sequence of key-value pairs. Keys are sorted (BTreeMap) for deterministic serialization.

CommStore

The in-memory representation of a .acomm file. Holds all channels, messages, subscriptions, and indexes.

Fields

Invariants

• next_channel_id is always greater than the maximum channel ID in channels.
• next_message_id is always greater than the maximum message ID in messages.
• Every message's channel_id references a channel in channels.
• Every subscription's channel_id references a PubSub channel in channels.
• Direct channels have exactly 2 participants.
• Broadcast channels have exactly 1 owner; other participants are observers.

Index Structures

Indexes are maintained in-memory for fast lookup and serialized to the .acomm file for persistence.

ChannelMessageIndex

Maps channel IDs to the message IDs belonging to that channel.

pub struct ChannelMessageIndex {
    // channel_id -> sorted Vec of message_ids
    index: HashMap<u64, Vec<u64>>,
}

TimestampIndex

Maps time ranges to message IDs for fast temporal queries.

pub struct TimestampIndex {
    // Sorted vec of (timestamp, message_id) for binary search
    entries: Vec<(u64, u64)>,
}

Temporal queries use binary search on the entries vector. A query for messages between timestamp A and B performs two binary searches (lower bound on A, upper bound on B) and returns the slice between them.

TopicIndex

Maps topic strings to message IDs for fast pub/sub queries.

pub struct TopicIndex {
    // exact topic -> sorted Vec of message_ids
    exact: HashMap<String, Vec<u64>>,
    // topic segment count for wildcard matching
    segment_cache: HashMap<String, Vec<String>>,
}

SenderIndex

Maps sender participant IDs to their message IDs.

pub struct SenderIndex {
    // sender -> sorted Vec of message_ids
    index: HashMap<String, Vec<u64>>,
}

CorrelationIndex

Maps correlation IDs to all messages in the thread.

pub struct CorrelationIndex {
    // correlation_id -> sorted Vec of message_ids
    index: HashMap<String, Vec<u64>>,
}

Serialization

Bincode

All structures are serialized to binary format using bincode (version 2). Bincode is chosen over JSON for three reasons:

1. Compact: Bincode produces 5-10x smaller output than JSON for the same data.
2. Fast: Serialization and deserialization are zero-allocation for fixed-size types.
3. Type-safe: Bincode preserves Rust type information, preventing deserialization of incompatible data.

Compression

Message content is compressed using flate2 (gzip level 6). The compression is applied to the content block as a whole, not per-message, because adjacent messages often share vocabulary (agent names, technical terms) that compress better together.

Compression ratio benchmarks:

Endianness

All multi-byte integers are stored in little-endian format, matching bincode's default behavior and the native byte order of x86-64 and ARM64 platforms.