stellarOS

A bare-metal operating system written in Rust, targeting RISC-V and AArch64 (ARM64), with an integrated Decentralized AI OS layer built directly into the kernel.

---

What is this?

stellarOS is not a typical toy kernel. It is a full-stack OS that combines:

• A complete monolithic kernel (scheduler, memory manager, VFS, IPC, SMP, syscalls)
• Multi-architecture support: RISC-V (riscv64gc-unknown-none-elf) and AArch64
• A Decentralized Knowledge Network (DKN) layer with P2P networking, Raft consensus, and distributed storage
• An AI inference engine and agent runtime (WASM sandbox, knowledge graphs)
• A cryptographic identity layer (Ed25519, AES-GCM, ChaCha20-Poly1305)
• A Knowledge Kernel with semantic memory engines, graph storage, and fuzzy search

---

Architecture

┌─────────────────────────────────────────────────┐
│               User Space (U-mode)               │
└────────────────────┬────────────────────────────┘
                     │ ecall
┌────────────────────▼────────────────────────────┐
│              Kernel Space (S-mode)              │
│                                                 │
│  trap → syscall → scheduler → memory/paging     │
│  VFS → ext2 → drivers (UART, VirtIO, PLIC)      │
│  IPC · SMP · ELF loader · debug                 │
│                                                 │
│  ── Decentralized AI OS Layers ──────────────── │
│  Identity · Agent Runtime · Memory Kernel       │
│  Knowledge Kernel · DKN P2P · Raft Consensus    │
│  Distributed Storage · AI Inference · Crypto    │
└────────────────────┬────────────────────────────┘
                     │ MMIO
┌────────────────────▼────────────────────────────┐
│         QEMU virt / bare metal hardware         │
│  UART · CLINT · PLIC · VirtIO-blk · GICv3      │
└─────────────────────────────────────────────────┘

See docs/architecture-overview.md for the full component map and data flow diagrams.

---

Features

Traditional Kernel Subsystems

• Physical memory allocator (bitmap-based) + SV39 paging (RISC-V) / 4-level paging (AArch64)
• Kernel heap allocator
• Round-robin preemptive scheduler with time slices
• Process management (fork, exec, exit, wait) + PCB/PID allocator
• VFS + Ext2 filesystem
• POSIX-subset syscall interface with argument validation
• UART, PLIC, CLINT/Generic Timer, VirtIO block and network drivers
• SMP multi-core support with spinlocks and per-CPU data
• IPC: pipes, signals, semaphores
• ELF loader
• User-mode isolation (U/S privilege separation)
• GDB remote debugging via UART

Decentralized AI OS Layers

Layer	Description
Decentralized Identity	Ed25519 keypairs, DID documents, capability tokens
Agent Runtime	WASM sandbox (wasmi), lifecycle management, resource budgets
Memory Kernel	Semantic memory engines: mapping, protection, lifecycle, governance
Knowledge Kernel	Graph store, fuzzy search, semantic matching, knowledge embeddings
DKN P2P	Noise-XX handshake, gossip protocol, hybrid logical clocks
Raft Consensus	Leader election, log replication, cluster membership
Distributed Storage	Content-addressed storage (CAS), replication, migration
AI Inference	Quantized inference engine, SIMD/NEON acceleration
Cryptography	SHA-2, AES-GCM, ChaCha20-Poly1305, Ed25519
Token Economics	Compute marketplace, staking, reward distribution

---

Getting Started

See docs/getting-started.md for build prerequisites, toolchain setup, and QEMU boot instructions.

Quick start (RISC-V)

# Install Rust + RISC-V target
rustup target add riscv64gc-unknown-none-elf
rustup component add llvm-tools-preview

# Build and run in QEMU
make run

Quick start (AArch64)

rustup target add aarch64-unknown-none
make run-arm64

---

Testing

stellarOS uses property-based testing (proptest) extensively for correctness guarantees.

# Run all host-side tests
make test

# Run a specific test suite
cargo test --test memory_tests

# Generate coverage report
make coverage

---

Project Structure

src/
├── arch/
│   ├── arm64/       # AArch64 port: GICv3, 4-level paging, NEON/SVE, SMP
│   └── mod.rs
├── dkn/             # Decentralized Knowledge Network subsystem
│   ├── p2p.rs       # P2P networking
│   ├── raft.rs      # Raft consensus
│   ├── gossip.rs    # Gossip protocol
│   └── ...
├── engines/         # Knowledge Kernel memory engines
├── knowledge/       # Knowledge graph, semantic memory
├── memory.rs        # Physical allocator
├── paging.rs        # SV39 page tables
├── scheduler.rs     # Preemptive scheduler
├── syscall.rs       # Syscall dispatch
└── ...
docs/
├── architecture-overview.md
├── getting-started.md
└── tutorials/
tests/               # 100+ test suites (unit + property-based)

---

License

MIT

---

References

• RISC-V Privileged Architecture Specification
• ARMv8-A Architecture Reference Manual
• The Rustonomicon