feagi-state-manager

Runtime state management for FEAGI - cross-platform, RTOS-compatible, and WASM-ready.

Features

• Lock-free atomic operations for high-frequency state access (5-20ns reads, 10-30ns writes)
• Multi-platform support: std, no_std, wasm, wasm-threaded
• Memory-mapped state for cross-process synchronization
• Agent registry with read-optimized locking
• Event streaming for state change notifications
• Persistence with binary serialization

Platform Support

Usage

Basic Usage

use feagi_state_manager::{StateManager, BurstEngineState};

// Create or attach to shared state
let state = StateManager::new()?;

// Lock-free read (<20ns)
let burst_state = state.get_burst_engine_state();

// Lock-free write (<30ns)
state.set_burst_engine_state(BurstEngineState::Running);

// Update statistics
state.set_neuron_count(1_000_000);
state.set_synapse_count(50_000_000);

Agent Management

use feagi_state_manager::{AgentInfo, AgentType};

// Register an agent (write-lock, rare operation)
let agent = AgentInfo::new(
    "video_agent_01".into(),
    AgentType::Sensory,
    capabilities,
    transport,
);
state.register_agent(agent)?;

// Get all agents (read-lock)
let agents = state.get_agents();

Event Streaming

// Subscribe to state changes
let rx = state.subscribe_events();

loop {
    match rx.recv() {
        Ok(StateEvent::BurstEngineStateChanged(state)) => {
            println!("Burst engine: {:?}", state);
        }
        Ok(StateEvent::AgentRegistered(id)) => {
            println!("Agent connected: {}", id);
        }
        _ => {}
    }
}

Architecture

┌─────────────────────────────────────┐
│   Memory-Mapped Core State          │  ← Lock-free atomic operations
│   (64-byte cache-line aligned)      │     5-20ns reads, 10-30ns writes
└─────────────────────────────────────┘
          ↓
┌─────────────────────────────────────┐
│   Agent Registry                    │  ← Arc<RwLock> (read-optimized)
│   Cortical Lock Manager             │  ← Wait-free algorithm
│   FCL Window Size Cache             │  ← Rarely accessed
└─────────────────────────────────────┘

Platform-Specific Implementation

Standard (std)

use parking_lot::RwLock;
use crossbeam::channel;

let registry = Arc::new(RwLock::new(AgentRegistry::new()));
let (tx, rx) = channel::bounded(1000);

RTOS (no_std)

use spin::RwLock;
use heapless::spsc::Queue;

let registry = RwLock::new(AgentRegistry::new());
let queue = Queue::<StateEvent, 128>::new();

WASM (single-threaded)

use std::cell::RefCell;

let registry = RefCell::new(AgentRegistry::new());
// No locks needed - single-threaded!

WASM (multi-threaded)

use wasm_sync::Mutex;

let registry = Arc::new(Mutex::new(AgentRegistry::new()));
// Uses Atomics.wait/notify under the hood

Performance Targets

Cargo Features

[dependencies]
feagi-state-manager = { version = "2.0", features = ["std"] }

Available features:

• std (default): Standard Rust with full features
• no_std: RTOS/embedded targets
• wasm: WebAssembly (single-threaded)
• wasm-threaded: WebAssembly with Web Workers

Building

Standard

cargo build --release

RTOS/Embedded

cargo build --release --no-default-features --features no_std --target thumbv7em-none-eabihf

WASM

cargo build --release --no-default-features --features wasm --target wasm32-unknown-unknown

Testing

# Unit tests
cargo test

# Integration tests
cargo test --workspace

# Benchmarks
cargo bench

Status

🚧 In Development - Core skeleton complete, implementation in progress.

Completed

• ✅ Crate structure
• ✅ Module stubs
• ✅ Platform feature gates
• ✅ Core state definition

In Progress

• 🚧 Memory-mapped state implementation
• 🚧 Agent registry
• 🚧 Cortical lock manager
• 🚧 Event streaming

Planned

• 📋 Full state manager implementation
• 📋 Python bindings (PyO3)
• 📋 Comprehensive tests
• 📋 Benchmarks
• 📋 Documentation

Contributing

See ARCHITECTURE.md for design principles and contribution guidelines.

License

Apache-2.0

Related Crates

• feagi-types: Core data structures

• feagi-burst-engine: NPU execution

• feagi-brain-development: Neurogenesis

• feagi-plasticity: Synaptic learning