# PhantomOS
An asynchronous, distributed operating system framework with integrated information theory (IIT) based entity component system (ECS) architecture.
## Overview
PhantomOS is an experimental operating system built in Rust, designed around principles of emergence, resonance, and integrated information. It combines:
- **Distributed Event Bus** - Async message passing between system components
- **ECS Graph Architecture** - Entity-component system with graph-based topology
- **Field-Based Computing** - Resonant field synthesis for state management
- **Adaptive Control** - Self-tuning controllers based on feedback signals
- **Safety Kernel** - Runtime validation and safety enforcement
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ PhantomKernel │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │SensorService│ │SignalEngine │ │ControlEngine│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ │ │
│ ┌────┴────┐ │
│ │EventBus │ │
│ └────┬────┘ │
│ │ │
│ ┌──────────┴──────────┐ │
│ │ SafetyKernel │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Distributed Cluster │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ ECSNode │ │ ECSNode │ │ ECSNode │ │ ECSNode │ │
│ │ #0 │ │ #1 │ │ #2 │ │ #3 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ └────────────┴───────────┴────────────┘ │
│ DistributedBus │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Aggregator │ │ Topology │ │ Field │ │
│ │ │ │ Scheduler │ │ Engine │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Components
### Core Modules
| `bus` | Event bus for local message passing |
| `dist_bus` | Distributed event bus for cluster communication |
| `kernel` | Main system bootstrap and lifecycle |
| `sensors` | Hardware abstraction for sensor input |
| `signal_engine` | Signal processing and system state synthesis |
| `control_engine` | PID-like control with actuator commands |
| `safety` | Runtime safety validation and alerting |
### ECS Modules
| `ecs/graph` | Graph structure for entity relationships |
| `ecs/node` | Distributed ECS node implementation |
| `ecs_solver` | IIT-based Phi maximization approximation |
### Field & Adaptive Modules
| `field/state` | Field state and system state structs |
| `field/engine` | Field synthesis from system state |
| `adaptive/controller` | Self-tuning adaptive controller |
### Scheduler Modules
| `scheduler/topology` | Load-based entity migration scheduler |
| `scheduler/spectral` | Graph Laplacian computation |
## Quick Start
### Prerequisites
- Rust 1.70+ with Cargo
- Tokio runtime (included via dependencies)
### Build
```bash
cargo build --release
```
### Run
```bash
cargo run
```
### Check
```bash
cargo check
```
## Configuration
Key parameters in `src/main.rs`:
```rust
let bus = DistributedBus::new(2048); // Event buffer size
let graph = ECSGraph::new(10_000); // Graph node capacity
let aggregator = Aggregator::new(bus.clone(), 10_000); // Mask size
```
## System State
The system maintains a `SystemState` with three core metrics:
- **Entropy** - Measure of disorder (0.0 - ∞)
- **Coherence** - Phase alignment (0.0 - 1.0)
- **Resonance** - Oscillatory coupling (0.0 - ∞)
## Events
### Local Events (`bus::Event`)
- `SensorFrame` - Raw sensor data
- `SystemState` - Processed state
- `ControlCommand` - Actuator outputs
- `SafetyAlert` - Safety violations
### Distributed Events (`dist_bus::DistributedEvent`)
- `SystemState` - Shared state across nodes
- `FieldState` - Synthesized field representation
- `Feedback` - Control feedback signals
- `EntityMigration` - Topology rebalancing
- `SafetyAlert` - Distributed safety alerts
## Safety Limits
Configurable in `src/safety/kernel.rs`:
```rust
const MAX_ENERGY: f64 = 10.0; // Per-command limit
const MAX_AMPLITUDE: f64 = 1000.0; // Field amplitude limit
```
## Architecture Decisions
1. **Async/Await** - All I/O and event handling is non-blocking
2. **Broadcast Channels** - Tokio broadcast for pub/sub event distribution
3. **Arc + Mutex** - Shared state management across tasks
4. **Graph Topology** - Entity relationships modeled as weighted graphs
5. **Spectral Methods** - Laplacian-based topology analysis
## Development
### Project Structure
```
PhantomOS/
├── Cargo.toml
├── src/
│ ├── lib.rs # Library exports
│ ├── main.rs # Binary entry point
│ ├── kernel.rs # System bootstrap
│ ├── bus.rs # Local event bus
│ ├── dist_bus.rs # Distributed bus (legacy)
│ ├── dist/ # Distributed modules
│ │ ├── bus.rs
│ │ ├── events.rs
│ │ └── mod.rs
│ ├── ecs/ # ECS modules
│ │ ├── graph.rs
│ │ ├── node.rs
│ │ └── mod.rs
│ ├── field/ # Field computing
│ │ ├── engine.rs
│ │ ├── state.rs
│ │ └── mod.rs
│ ├── adaptive/ # Adaptive control
│ │ ├── controller.rs
│ │ └── mod.rs
│ ├── scheduler/ # Topology management
│ │ ├── topology.rs
│ │ ├── spectral.rs
│ │ └── mod.rs
│ ├── safety/ # Safety kernel
│ │ ├── kernel.rs
│ │ └── mod.rs
│ ├── aggregator.rs # State aggregation
│ ├── control_engine.rs # Control logic
│ ├── ecs_node.rs # Legacy ECS node
│ ├── ecs_solver.rs # IIT solver
│ ├── hal.rs # Hardware abstraction
│ ├── sensors.rs # Sensor service
│ ├── signal_engine.rs # Signal processing
│ └── simulation.rs # Resonator simulation
└── README.md
```
## License
See LICENSE file for details.
## References
- Integrated Information Theory (IIT) - Tononi et al.
- Entity Component System pattern
- Distributed systems consensus
- Resonant computing architectures