Frame Mesh - Cross-Instance Synchronization

Distributed computing and cross-instance synchronization for AI systems.

Extracted from the Frame microservices architecture.

Features

• Event System: Distributed event tracking with vector clocks
• Cross-Instance Sync: Eventual consistency across multiple instances
• Node Registry: Trusted node management and discovery
• Context Sharing: Cross-instance context awareness for better responses
• Execution Delegation: Distributed task execution and load balancing

Quick Start

[dependencies]
sam-distributed = "0.1.0"

Dependency Architecture

frame-mesh depends on:

frame-mesh
├── frame-catalog (database, retrieval)
└── frame-presence (session management)

Used by: Frame core for distributed coordination

Position in Frame ecosystem:

frame-catalog ──┬→ frame-mesh
                │
frame-presence ─┘

use sam_distributed::{EventStore, SyncManager, NodeRegistry};
use frame_catalog::Database;

// Initialize components
let db = Database::new("distributed.db")?;
let event_store = EventStore::new(&db)?;
let node_registry = NodeRegistry::new(&db)?;

// Register trusted nodes
node_registry.register_node("node-1", "192.168.1.100:8080")?;
node_registry.register_node("node-2", "192.168.1.101:8080")?;

// Create sync manager
let sync = SyncManager::new(event_store, node_registry);

// Sync with peers
sync.sync_with_peers().await?;

Modules

• events (253 LOC) - Event types and vector clocks
• event_store (196 LOC) - Event persistence
• sync (304 LOC) - Cross-instance synchronization
• cross_instance (295 LOC) - Cross-instance messaging
• node_registry (301 LOC) - Node tracking and trust
• executor (368 LOC) - Distributed task execution

Event System

Track distributed events with vector clocks:

use sam_distributed::{MemoryEvent, MemoryEventType, VectorClock};

let mut clock = VectorClock::new();
clock.increment("node-1");

let event = MemoryEvent::new(
    MemoryEventType::ChunkAdded { document_id: "doc-123".to_string() },
    "node-1".to_string(),
    clock,
);

event_store.store_event(&event)?;

Synchronization

Sync state across multiple instances:

use sam_distributed::{SyncManager, SyncStrategy};

let sync = SyncManager::new(event_store, node_registry);

// Push updates to peers
sync.push_updates("node-1").await?;

// Pull updates from peers
sync.pull_updates("node-1").await?;

// Bidirectional sync
let result = sync.sync_with_peer("node-1").await?;
println!("Synced {} events", result.events_synced);

Node Registry

Manage trusted nodes:

use sam_distributed::{NodeRegistry, TrustStatus};

let registry = NodeRegistry::new(&db)?;

// Register node
registry.register_node("node-1", "192.168.1.100:8080")?;

// Update trust status
registry.update_trust_status("node-1", TrustStatus::Trusted)?;

// List trusted nodes
let nodes = registry.list_trusted_nodes()?;
for node in nodes {
    println!("{}: {}", node.node_id, node.address);
}

Cross-Instance Context

Share context across instances:

use sam_distributed::CrossInstanceContext;

let context = CrossInstanceContext::new(db, session_store)?;

// Get active sessions across all instances
let sessions = context.get_active_sessions("user-123").await?;

// Retrieve from remote instance if local cache miss
let retriever = context.create_retriever(node_registry);
let results = retriever.retrieve_with_fallback("query", 5).await?;

Distributed Execution

Delegate tasks to remote nodes:

use sam_distributed::{RetrievalExecutor, RetrievalStats};

// Local execution
let executor = RetrievalExecutor::Local(retrieval_system);
let results = executor.retrieve("query", 5).await?;

// Remote execution (requires gRPC setup)
#[cfg(feature = "grpc")]
{
    let executor = RetrievalExecutor::Remote(grpc_client);
    let results = executor.retrieve("query", 5).await?;
}

// Get stats
let stats = executor.get_stats().await?;
println!("Total queries: {}", stats.total_queries);

gRPC Support (Future)

gRPC client and server implementations are planned for future releases. Example implementations are available in the examples/ directory but require protobuf definitions to compile.

Compatibility

• Rust Edition: 2021
• MSRV: 1.70+
• Platforms: All (tested on Linux, macOS, Windows)

Dependencies

• frame-catalog - Database, retrieval system
• frame-presence - Session management
• rusqlite (0.31) - Persistence
• tokio (1.0) - Async runtime
• parking_lot (0.12) - Synchronization

Testing

# Run all tests
cargo test

# Run with logging
RUST_LOG=debug cargo test

# Build with gRPC support (requires proto definitions)
cargo build --features grpc

License

MIT - See LICENSE for details.

Author

Magnus Trent magnus@blackfall.dev

Links

• GitHub: https://github.com/Blackfall-Labs/sam-distributed