docs.rs failed to build phantom_os-0.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

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

Module	Description
`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

Module	Description
`ecs/graph`	Graph structure for entity relationships
`ecs/node`	Distributed ECS node implementation
`ecs_solver`	IIT-based Phi maximization approximation

Field & Adaptive Modules

Module	Description
`field/state`	Field state and system state structs
`field/engine`	Field synthesis from system state
`adaptive/controller`	Self-tuning adaptive controller

Scheduler Modules

Module	Description
`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

cargo build --release

Run

cargo run

Check

cargo check

Configuration

Key parameters in src/main.rs:

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:

const MAX_ENERGY: f64 = 10.0;      // Per-command limit
const MAX_AMPLITUDE: f64 = 1000.0;  // Field amplitude limit

Architecture Decisions

Async/Await - All I/O and event handling is non-blocking
Broadcast Channels - Tokio broadcast for pub/sub event distribution
Arc + Mutex - Shared state management across tasks
Graph Topology - Entity relationships modeled as weighted graphs
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

phantom_os 0.1.0