Skip to content

Latest commit

 

History

History
275 lines (207 loc) · 10.8 KB

README.md

File metadata and controls

275 lines (207 loc) · 10.8 KB

WOS - WebAssembly Operating System

Educational microkernel OS in pure Rust — runs entirely in your browser

Live Demo License

Live Demo • Quick Start • Architecture • Sovereign AI Stack

Overview

WOS (WebAssembly Operating System) is an educational microkernel that demonstrates fundamental OS concepts — processes, memory management, file systems, IPC — in a safe, deterministic environment that runs directly in any modern browser.

Part of the Sovereign AI Stack, WOS serves as the runtime foundation for browser-based ML inference and educational computing environments.

Key Features

  • 100% Safe Rust — #![forbid(unsafe_code)] enforced at crate level
  • Pure WASM — No plugins, runs in any modern browser
  • Functional Design — Immutable state transitions, deterministic execution
  • Time-Travel Debugging — Bidirectional execution replay with full snapshots
  • Extreme TDD — 94%+ coverage, 98.5% mutation score

Quick Start

# Install WASM target
rustup target add wasm32-unknown-unknown

# Build and serve
make wasm && make serve

# Open http://localhost:8000

Try the Shell

help              # Available commands
ps                # List processes
ls /proc          # Process filesystem
cat /proc/1/status  # View init process
echo $?           # Last exit code
vim hello.txt     # Modal editor

Architecture

WOS implements a classic microkernel with minimal trusted computing base:

┌─────────────────────────────────────────────────────────────┐
│                     Browser (WASM Runtime)                  │
├─────────────────────────────────────────────────────────────┤
│  Userspace                                                  │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │  init   │ │  shell  │ │   vim   │ │ programs│          │
│  │ (PID 1) │ │         │ │         │ │ ls,cat..│          │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘          │
├───────┴──────────┴──────────┴──────────┴──────────────────┤
│                     System Call Interface                   │
├─────────────────────────────────────────────────────────────┤
│  Microkernel (~2000 lines)                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │Scheduler │ │  Memory  │ │   VFS    │ │   IPC    │      │
│  │Round-Robin│ │  Manager │ │  ProcFS  │ │ Messages │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
└─────────────────────────────────────────────────────────────┘

Pure Functional Syscalls

All operations follow the functional pattern — state flows in, new state flows out:

pub fn dispatch_syscall(
    state: KernelState,
    syscall: SystemCall,
    pid: ProcessId,
) -> Result<(KernelState, SyscallOutput), KernelError>

No global state. No side effects. Fully deterministic.

System Calls

Category Syscalls
Process fork, exec, exit, waitpid, getpid, kill
File I/O open, close, read, write
Memory mmap, munmap
Signals sigaction, sigprocmask
IPC send, recv

Sovereign AI Stack Integration

WOS is a component of the Sovereign AI Stack, providing browser-based runtime capabilities:

┌─────────────────────────────────────────────────────────────┐
│                    batuta (Orchestration)                   │
├─────────────────────────────────────────────────────────────┤
│     realizar          │           pacha                     │
│   (Inference)         │      (Model Registry)               │
├───────────────────────┴─────────────────────────────────────┤
│                    aprender (ML Algorithms)                 │
├─────────────────────────────────────────────────────────────┤
│      trueno           │          WOS                        │
│   (SIMD Compute)      │   (Browser Runtime)                 │
└─────────────────────────────────────────────────────────────┘

Stack Components

Component Purpose Link
batuta Stack orchestration crates.io/crates/batuta
aprender ML algorithms crates.io/crates/aprender
trueno SIMD/GPU compute crates.io/crates/trueno
WOS Browser runtime interactive.paiml.com/wos

Quality Compliance

WOS adheres to strict quality standards enforced by the PAIML toolchain.

PMAT Comply

Verified compliance with pmat quality standards:

pmat comply check            # ✓ COMPLIANT
pmat analyze tdg             # TDG Grade: A+
pmat quality-gate --strict   # All gates pass

Compliance Status:

✓ Version Currency: v2.213.1
✓ Config Files: All present
✓ Git Hooks: PMAT enforcement installed
✓ Quality Thresholds: Configured
✓ Deprecated Features: None

Metrics: TDG A+ (99.3/100) • 94% coverage • 98.5% mutation score

Probar Comply

Status: COMPLETE — Zero JavaScript achieved

Requirement Status Notes
Zero JavaScript ✓ Pure WASM, no app.js
WASM Init ✓ #[wasm_bindgen(start)] auto-init
DOM via web-sys ✓ All DOM ops in Rust
Event Handlers ✓ Terminal, panels, controls

Architecture:

  • wos/src/wasm_init.rs - Pure WASM entry point
  • wos/src/dom.rs - web-sys DOM abstractions
  • dist/wos/wos.js - wasm-bindgen glue only (required by browsers)
  • dist/wos/index.html - Minimal WASM loader (no app logic)

Quality Gates

All commits must pass:

make quality                # Fast checks (<30s)
make quality-complete       # Full validation

Development

Prerequisites

  • Rust 1.70+ with wasm32-unknown-unknown target
  • ruchy — Development server with hot reload

Commands

make build          # Build all crates
make wasm           # Build WASM binary
make serve          # Start dev server (ruchy)
make test           # Run Rust tests
make e2e            # Run E2E tests
make coverage       # Generate coverage report
make mutants        # Run mutation testing

Project Structure

wos/
├── kernel/         # Microkernel (~2000 lines)
│   ├── scheduler.rs    # Round-robin scheduling
│   ├── memory.rs       # Virtual memory
│   ├── syscall.rs      # System calls
│   └── trace.rs        # Time-travel debugging
├── shared/         # Shared types
│   ├── vfs.rs          # Virtual filesystem
│   ├── parser.rs       # Command parsing
│   └── pipeline.rs     # Pipeline execution
├── userspace/      # User programs
│   ├── shell.rs        # Interactive shell
│   ├── programs.rs     # ls, cat, ps, etc.
│   └── vim/            # Modal editor
├── wos/            # WASM bindings
└── dist/wos/       # Browser frontend

Educational Use

WOS teaches OS concepts through hands-on exploration:

Concept WOS Implementation
Process Management fork/exec, process trees, PID namespace
Memory Management Virtual memory, page tables, R/W/X permissions
File Systems VFS abstraction, ProcFS, file descriptors
IPC Message passing, synchronous/async patterns
Scheduling Round-robin, fairness guarantees
Time-Travel Debug State snapshots, bidirectional replay

Why WebAssembly?

  • Safety: WASM sandbox prevents crashes and corruption
  • Accessibility: Runs in any browser, zero installation
  • Debuggability: Full state inspection at any execution point
  • Determinism: Reproducible tests, predictable behavior

Contributing

  1. Maintain #![forbid(unsafe_code)]
  2. Add tests for all new functionality (85%+ coverage target)
  3. Run make quality before committing
  4. Follow conventional commit format

License

MIT License — see LICENSE for details.

Links

WOS — Educational OS for the Sovereign AI Stack

Live Demo • Documentation • Issues