Struct CommStore 

pub struct CommStore {

    pub channels: HashMap<u64, Channel>,
    pub messages: HashMap<u64, Message>,
    pub subscriptions: HashMap<u64, Subscription>,
    pub dead_letters: Vec<DeadLetter>,
    pub consent_gates: Vec<ConsentGateEntry>,
    pub trust_levels: HashMap<String, CommTrustLevel>,
    pub temporal_queue: Vec<TemporalMessage>,
    pub federation_config: FederationConfig,
    pub hive_minds: HashMap<u64, HiveMind>,
    pub comm_log: Vec<CommunicationLogEntry>,
    pub audit_log: Vec<AuditEntry>,
    pub rate_limit_config: RateLimitConfig,
    pub semantic_operations: Vec<SemanticOperation>,
    pub semantic_conflicts: Vec<SemanticConflict>,
    pub affect_states: HashMap<String, AffectState>,
    pub affect_resistance: f64,
    pub pending_consent_requests: Vec<ConsentRequest>,
    pub meld_sessions: Vec<MeldSession>,
    pub zone_policies: HashMap<String, ZonePolicyConfig>,
    pub key_store: Vec<KeyEntry>,
    pub lamport_counter: u64,
    pub rate_trackers: HashMap<String, RateTracker>,
    pub key_pair: Option<CommKeyPair>,
    pub agents: HashMap<String, CommunicatingAgent>,
    pub bridge_config: BridgeConfig,
    pub embeddings: HashMap<u64, Vec<f32>>,
    /* private fields */
}

The main communication store holding channels, messages, and subscriptions.

Fields

channels: HashMap<u64, Channel>

All channels, keyed by channel id.

messages: HashMap<u64, Message>

All messages, keyed by message id.

subscriptions: HashMap<u64, Subscription>

All subscriptions, keyed by subscription id.

dead_letters: Vec<DeadLetter>

Dead letter queue for undeliverable messages.

consent_gates: Vec<ConsentGateEntry>

Consent gates: (grantor, grantee, scope) -> ConsentGateEntry.

trust_levels: HashMap<String, CommTrustLevel>

Trust level overrides: agent_id -> trust_level.

temporal_queue: Vec<TemporalMessage>

Temporal message queue.

federation_config: FederationConfig

Federation configuration.

hive_minds: HashMap<u64, HiveMind>

Hive minds.

comm_log: Vec<CommunicationLogEntry>

Communication log entries.

audit_log: Vec<AuditEntry>

Audit log entries.

rate_limit_config: RateLimitConfig

Rate limit configuration.

semantic_operations: Vec<SemanticOperation>

Semantic operations log.

semantic_conflicts: Vec<SemanticConflict>

Semantic conflicts.

affect_states: HashMap<String, AffectState>

Per-agent affect states.

affect_resistance: f64

Affect contagion resistance (global default).

pending_consent_requests: Vec<ConsentRequest>

Pending consent requests.

meld_sessions: Vec<MeldSession>

Meld sessions.

zone_policies: HashMap<String, ZonePolicyConfig>

Per-zone federation policies.

key_store: Vec<KeyEntry>

Key metadata for channel encryption.

lamport_counter: u64

Global Lamport counter for causal ordering of messages.

rate_trackers: HashMap<String, RateTracker>

Per-sender rate tracking (not persisted — rebuilt at runtime).

key_pair: Option<CommKeyPair>

Optional Ed25519 key pair for cryptographic message signing. Not serialized — must be set at runtime via set_signing_key.

agents: HashMap<String, CommunicatingAgent>

Registered communicating agents (agent_id -> CommunicatingAgent).

bridge_config: BridgeConfig

Bridge configuration for sister integrations. Not serialized — must be set at runtime via set_bridge_config.

embeddings: HashMap<u64, Vec<f32>>

Embedding vectors for semantic search, keyed by message ID.

Each entry maps a message ID to its embedding vector (e.g. from an external model). Supports brute-force cosine similarity search.

Implementations

impl CommStore

pub fn new() -> Self

Create a new empty communication store.

pub fn set_bridge_config(&mut self, config: BridgeConfig)

Set the bridge configuration for sister integrations.

pub fn register_agent(&mut self, agent: CommunicatingAgent) -> CommResult<()>

Register a new communicating agent.

pub fn get_agent(&self, agent_id: &str) -> Option<&CommunicatingAgent>

Get a registered agent by ID.

pub fn list_agents(&self) -> Vec<&CommunicatingAgent>

List all registered agents.

pub fn update_agent_availability( &mut self, agent_id: &str, availability: Availability, ) -> CommResult<()>

Update agent availability/presence.

pub fn unregister_agent(&mut self, agent_id: &str) -> CommResult<()>

Remove a registered agent.

pub fn set_signing_key(&mut self, key_pair: CommKeyPair)

Set the Ed25519 key pair used for signing outgoing messages.

pub fn get_public_key(&self) -> Option<String>

Get the hex-encoded Ed25519 public key, if a key pair is set.

pub fn verify_message_signature(&mut self, message_id: u64) -> bool

Verify that a message’s signature is valid.

Ed25519 signatures are 64 bytes (128 hex chars). If the stored signature is that length and a key pair is set, Ed25519 verification is attempted first. Falls back to SHA-256 hash comparison for legacy signatures (64 hex chars / 32 bytes).

Returns true if valid (or no signature stored), false if mismatch.

pub fn pause_channel(&mut self, channel_id: u64) -> CommResult<()>

Pause a channel. Blocks new sends and receives.

pub fn resume_channel(&mut self, channel_id: u64) -> CommResult<()>

Resume a paused channel back to Active state.

pub fn drain_channel(&mut self, channel_id: u64) -> CommResult<()>

Set a channel to Draining state. Allows receive but blocks send.

pub fn close_channel(&mut self, channel_id: u64) -> CommResult<()>

Close a channel. Blocks all operations.

pub fn send_message( &mut self, channel_id: u64, sender: &str, content: &str, msg_type: MessageType, ) -> CommResult<Message>

Send a message to a channel.

Enforces rate limiting, consent gates, and channel state before delivering. If the channel is Paused, Draining, or Closed, the message is automatically dead-lettered and an error is returned.

pub fn send_message_with_priority( &mut self, channel_id: u64, sender: &str, content: &str, msg_type: MessageType, priority: MessagePriority, ) -> CommResult<Message>

Send a message with a specific priority.

pub fn receive_messages( &mut self, channel_id: u64, recipient: Option<&str>, since: Option<DateTime<Utc>>, ) -> CommResult<Vec<Message>>

Receive messages from a channel, optionally filtered by recipient and time.

Verifies message signatures on retrieval and logs a warning audit event if any signature does not match. Mismatched messages are still returned (reads are never blocked).

pub fn acknowledge_message( &mut self, message_id: u64, recipient: &str, ) -> CommResult<()>

Acknowledge receipt of a message.

pub fn broadcast( &mut self, channel_id: u64, sender: &str, content: &str, ) -> CommResult<Vec<Message>>

Broadcast a message to all participants in a broadcast channel.

pub fn send_reply( &mut self, channel_id: u64, message_id: u64, sender: &str, content: &str, msg_type: MessageType, ) -> CommResult<Message>

Send a reply linked to a parent message.

pub fn get_thread(&self, thread_id: &str) -> Vec<Message>

Get all messages in a thread, ordered by timestamp.

pub fn get_replies(&self, message_id: u64) -> Vec<Message>

Get all direct replies to a specific message.

pub fn create_channel( &mut self, name: &str, channel_type: ChannelType, config: Option<ChannelConfig>, ) -> CommResult<Channel>

Create a new communication channel.

pub fn join_channel( &mut self, channel_id: u64, participant: &str, ) -> CommResult<()>

Join a channel as a participant.

pub fn leave_channel( &mut self, channel_id: u64, participant: &str, ) -> CommResult<()>

Leave a channel.

pub fn list_channels(&self) -> Vec<Channel>

List all channels.

pub fn get_channel(&self, channel_id: u64) -> Option<Channel>

Get a specific channel by id.

pub fn set_channel_config( &mut self, channel_id: u64, config: ChannelConfig, ) -> CommResult<()>

Update channel configuration.

pub fn subscribe( &mut self, topic: &str, subscriber: &str, ) -> CommResult<Subscription>

Subscribe to a topic.

pub fn unsubscribe(&mut self, subscription_id: u64) -> CommResult<()>

Remove a subscription.

pub fn publish( &mut self, topic: &str, sender: &str, content: &str, ) -> CommResult<Vec<Message>>

Publish a message to all subscribers of a topic.

pub fn dead_letter_count(&self) -> usize

Return the number of dead letters in the queue.

pub fn list_dead_letters(&self) -> Vec<DeadLetter>

List all dead letters, sorted by dead-lettered time (oldest first).

pub fn replay_dead_letter(&mut self, index: usize) -> CommResult<Message>

Attempt to replay (re-send) a dead letter by index.

If the channel is now available and active, the message is re-sent and removed from the dead letter queue. Otherwise, the retry count is incremented and the dead letter remains.

pub fn clear_dead_letters(&mut self)

Clear all dead letters from the queue.

pub fn expire_messages(&mut self) -> usize

Expire messages that have exceeded their channel’s TTL.

Scans all messages. If the channel has ttl_seconds > 0 and the message is older than the TTL, the message is moved to the dead letter queue with reason Expired.

Returns the count of expired messages.

pub fn compact(&mut self) -> usize

Compact the store by removing messages from closed channels and enforcing retention policies.

Returns the count of removed messages.

pub fn query_history( &self, channel_id: u64, filter: &MessageFilter, ) -> Vec<Message>

Query message history with filters.

pub fn search_messages( &self, query_text: &str, max_results: usize, ) -> Vec<Message>

Full-text search across all messages.

pub fn get_message(&self, message_id: u64) -> Option<Message>

Get a specific message by id.

pub fn save(&self, path: &Path) -> CommResult<()>

Save the store to a .acomm file (bincode + zstd + binary header).

Acquires an exclusive CommFileLock for the duration of the write so that concurrent readers/writers on the same path do not corrupt data.

The on-disk format is: [ACOM header (48 bytes)] [zstd(bincode(store))]. The ACOM header includes a Blake3 hash of the compressed payload so that corruption can be detected on load. The FLAG_ZSTD flag (bit 0) is set to indicate Zstd compression; older files without this flag are treated as gzip-compressed on read.

pub fn load(path: &Path) -> CommResult<Self>

Load a store from a .acomm file.

Acquires a shared CommFileLock for the duration of the read so that concurrent writers are held off while the data is being read.

Supports three on-disk variants:

• v3 with FLAG_ZSTD (current): ACOM header + Zstd-compressed payload.
• v2/v3 without FLAG_ZSTD (legacy): ACOM header + gzip-compressed payload.
• v1 (oldest): raw gzip with embedded ACOMM001 header.

pub fn stats(&self) -> CommStoreStats

Get summary statistics for the store.

pub fn grant_consent( &mut self, grantor: &str, grantee: &str, scope: ConsentScope, reason: Option<String>, expires_at: Option<String>, ) -> CommResult<&ConsentGateEntry>

Grant consent from grantor to grantee for a specific scope.

pub fn revoke_consent( &mut self, grantor: &str, grantee: &str, scope: &ConsentScope, ) -> CommResult<()>

Revoke consent.

pub fn check_consent( &self, grantor: &str, grantee: &str, scope: &ConsentScope, ) -> bool

Check if consent is granted.

pub fn list_consent_gates(&self, agent: Option<&str>) -> Vec<&ConsentGateEntry>

List all consent gates, optionally filtered by agent.

pub fn set_trust_level( &mut self, agent_id: &str, level: CommTrustLevel, ) -> CommResult<()>

Set trust level for an agent.

pub fn get_trust_level(&self, agent_id: &str) -> CommTrustLevel

Get trust level for an agent (default: Standard).

pub fn list_trust_levels(&self) -> &HashMap<String, CommTrustLevel>

List all trust level overrides.

pub fn schedule_message( &mut self, channel_id: u64, sender: &str, content: &str, target: TemporalTarget, affect: Option<AffectState>, ) -> CommResult<&TemporalMessage>

Schedule a message for future delivery.

pub fn list_scheduled(&self) -> Vec<&TemporalMessage>

List all scheduled (undelivered) temporal messages.

pub fn cancel_scheduled(&mut self, temporal_id: u64) -> CommResult<()>

Cancel a scheduled message.

pub fn deliver_pending_temporal(&mut self) -> usize

Deliver all pending temporal messages that are due (Immediate targets). Returns the number of messages delivered.

pub fn send_affect_message( &mut self, channel_id: u64, sender: &str, content: &str, affect: AffectState, ) -> CommResult<Message>

Send a message with affect/emotional context.

pub fn configure_federation( &mut self, enabled: bool, local_zone: &str, default_policy: FederationPolicy, ) -> CommResult<()>

Configure federation settings.

pub fn get_federation_config(&self) -> &FederationConfig

Get current federation configuration.

pub fn add_federated_zone(&mut self, zone: FederatedZone) -> CommResult<()>

Add a federated zone.

pub fn remove_federated_zone(&mut self, zone_id: &str) -> CommResult<()>

Remove a federated zone.

pub fn list_federated_zones(&self) -> &[FederatedZone]

List all federated zones.

pub fn form_hive( &mut self, name: &str, coordinator: &str, decision_mode: CollectiveDecisionMode, ) -> CommResult<&HiveMind>

Form a new hive mind.

pub fn dissolve_hive(&mut self, hive_id: u64) -> CommResult<()>

Dissolve a hive mind.

pub fn join_hive( &mut self, hive_id: u64, agent_id: &str, role: HiveRole, ) -> CommResult<()>

Join a hive mind.

pub fn leave_hive(&mut self, hive_id: u64, agent_id: &str) -> CommResult<()>

Leave a hive mind.

pub fn list_hives(&self) -> Vec<&HiveMind>

List all hive minds.

pub fn get_hive(&self, hive_id: u64) -> Option<&HiveMind>

Get a specific hive mind.

pub fn log_communication( &mut self, content: &str, role: &str, topic: Option<String>, linked_message_id: Option<u64>, affect: Option<AffectState>, ) -> &CommunicationLogEntry

Log a communication context entry.

pub fn get_comm_log(&self, limit: Option<usize>) -> &[CommunicationLogEntry]

Get communication log entries.

pub fn log_audit( &mut self, event_type: AuditEventType, agent_id: &str, description: &str, related_id: Option<String>, )

Log an audit event.

pub fn get_audit_log(&self, limit: Option<usize>) -> Vec<&AuditEntry>

Get recent audit log entries.

pub fn rotate_audit_log(&mut self, max_entries: usize) -> usize

Rotate audit log, keeping only the most recent entries.

pub fn enforce_audit_retention(&mut self, cutoff_timestamp: &str) -> usize

Enforce retention policy, removing entries older than cutoff timestamp.

pub fn export_audit_log(&self) -> Value

Export audit log as JSON array.

pub fn send_semantic( &mut self, channel_id: u64, sender: &str, topic: &str, focus_nodes: Vec<String>, depth: u64, ) -> CommResult<SemanticOperation>

Send a semantic message (structured meaning payload).

pub fn extract_semantic(&self, message_id: u64) -> CommResult<SemanticOperation>

Extract semantics from a message.

pub fn graft_semantic( &mut self, source_id: u64, target_id: u64, strategy: &str, ) -> CommResult<SemanticOperation>

Graft (merge) semantic layers.

pub fn list_semantic_conflicts( &self, channel_id: Option<u64>, severity: Option<&str>, ) -> Vec<&SemanticConflict>

List semantic conflicts.

pub fn get_affect_state(&self, agent_id: &str) -> Option<&AffectState>

Get the current affect state for an agent.

pub fn set_affect_resistance(&mut self, resistance: f64) -> f64

Set the affect resistance threshold.

pub fn process_affect_contagion( &mut self, channel_id: u64, ) -> Vec<(String, f64, f64, f64)>

Process affect contagion across all participants in a channel.

For each message with affect metadata (valence, arousal, dominance), apply a simple contagion model: each receiver’s state is nudged toward the sender’s state, weighted by (1 - affect_resistance).

pub fn get_affect_history(&self, agent: &str) -> AffectHistory

Retrieve the full affect history for an agent.

Builds a history from the current affect state and any messages sent by or to the agent that carried affect metadata.

pub fn apply_affect_decay(&mut self, decay_rate: f64)

Apply temporal decay to all agent affect states.

Each dimension is multiplied by (1.0 - decay_rate), then clamped to valid ranges: valence [-1.0, 1.0], arousal [0.0, 1.0], dominance [0.0, 1.0].

pub fn forward_message( &mut self, original_id: u64, target_channel: u64, forwarder: &str, ) -> Result<u64, String>

Forward a message to another channel with echo tracking metadata.

Creates a new message in target_channel with content prefixed “[Forwarded] “ and metadata tracking the forwarding chain.

pub fn query_echo_chain(&self, message_id: u64) -> Vec<EchoChainEntry>

Trace the full forwarding (echo) chain of a message.

Follows “forwarded_from” metadata backwards to the root, then searches forward for all messages forwarded from any message in the chain.

pub fn get_echo_depth(&self, message_id: u64) -> u32

Get the forwarding depth of a message in its echo chain.

Returns the “echo_depth” metadata value, or 0 if the message is an original (not forwarded).

pub fn summarize_conversation( &self, channel_id: u64, ) -> Result<ConversationSummaryDetailed, String>

Generate detailed conversation statistics for a channel.

pub fn hive_think( &self, hive_id: u64, question: &str, timeout_ms: u64, ) -> CommResult<Value>

Broadcast a question to all hive members and return aggregated response.

pub fn initiate_meld( &mut self, partner_id: &str, depth: &str, duration_ms: u64, ) -> MeldSession

Initiate a deep mind-meld session with a partner agent.

pub fn list_pending_consent( &self, agent_id: Option<&str>, consent_type: Option<&str>, ) -> Vec<&ConsentRequest>

List pending consent requests.

pub fn respond_consent( &mut self, request_id: &str, response: &str, ) -> CommResult<()>

Respond to a pending consent request.

pub fn query_relationships( &self, agent_id: &str, relationship_type: Option<&str>, depth: u64, ) -> Value

Query relationships for an agent including trust, channels, and consent.

pub fn conversation_at_time(&self, channel_id: u64, timestamp: u64) -> Value

Query the conversation state at a specific point in time.

pub fn changes_in_range(&self, channel_id: u64, start: u64, end: u64) -> Value

Get changes between two timestamps for a channel.

pub fn query_echoes(&self, message_id: u64, depth: u64) -> CommResult<Value>

Query conversation echoes (messages that reference or reply to a message).

pub fn query_conversations( &self, channel_id: Option<u64>, participant: Option<&str>, limit: u64, ) -> Vec<ConversationSummary>

Query conversation summaries.

pub fn get_federation_status(&self) -> Value

Get federation status.

pub fn set_federation_policy( &mut self, zone_id: &str, allow_semantic: bool, allow_affect: bool, allow_hive: bool, max_message_size: u64, ) -> ZonePolicyConfig

Set federation policy for a zone.

pub fn ground_claim(&self, claim: &str) -> GroundingResult

Ground a claim against the communication store.

pub fn generate_key( &mut self, algorithm: &str, channel_id: Option<u64>, ) -> CommResult<KeyEntry>

Generate a new key entry with metadata.

Creates a key entry with a pseudo-random fingerprint. This is a stub that manages key metadata; real cryptographic key material would be generated by a dedicated crypto layer.

pub fn list_keys(&self) -> Vec<&KeyEntry>

List all key entries.

pub fn get_key(&self, key_id: u64) -> CommResult<&KeyEntry>

Get a specific key by ID.

pub fn rotate_key(&mut self, key_id: u64) -> CommResult<KeyEntry>

Rotate a key: mark the old key as “rotated” and create a new key with the same algorithm and channel binding.

pub fn revoke_key(&mut self, key_id: u64) -> CommResult<()>

Revoke a key by ID.

pub fn export_key(&self, key_id: u64) -> CommResult<String>

Export a key’s fingerprint (stub for real key export).

pub fn ground_evidence(&self, query: &str) -> Vec<GroundingEvidence>

Search messages, channels, and agents for evidence matching a query.

Returns detailed evidence entries with timestamps and relevance scores.

pub fn ground_suggest(&self, query: &str, limit: usize) -> Vec<String>

Return fuzzy/contains suggestions based on agent names, channel names, or message content matching the query.

pub fn assign_comm_ids(&mut self)

Assign CommIds to all messages and channels that don’t already have one.

Deterministically derives the UUID from the legacy u64 id so that repeated calls are idempotent.

pub fn get_message_by_comm_id(&self, comm_id: &CommId) -> Option<&Message>

Look up a message by its CommId.

pub fn get_channel_by_comm_id(&self, comm_id: &CommId) -> Option<&Channel>

Look up a channel by its CommId.

pub fn send_rich_message( &mut self, channel_id: u64, sender: &str, content: MessageContent, msg_type: MessageType, ) -> CommResult<Message>

Send a message with rich content.

Sends a regular message and attaches a MessageContent (serialized as JSON) to the rich_content_json field.

pub fn get_rich_content( &self, message_id: u64, ) -> CommResult<Option<MessageContent>>

Get the rich content of a message (if any).

pub fn store_embedding(&mut self, message_id: u64, embedding: Vec<f32>)

Store an embedding vector for a message.

The embedding is typically produced by an external model (e.g. an LLM embedding endpoint) and associated with the message’s ID so that semantic_search can find semantically similar messages later.

pub fn semantic_search( &self, query_embedding: &[f32], top_k: usize, ) -> Vec<(u64, f32)>

Find the top-k most semantically similar messages to a query embedding.

Performs brute-force cosine similarity over all stored embeddings and returns up to top_k results sorted by descending similarity. Each result is a (message_id, similarity) pair where similarity is in the range [-1.0, 1.0].

pub fn cosine_similarity(a: &[f32], b: &[f32]) -> f32

Compute the cosine similarity between two vectors.

Returns a value in [-1.0, 1.0]. If either vector has zero magnitude the function returns 0.0 to avoid division by zero.

Trait Implementations

impl Clone for CommStore

fn clone(&self) -> CommStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CommStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CommStore

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CommStore

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CommStore

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.