Architecture Overview

Nexus OS is organized into strict architectural layers. Each layer has a single responsibility and communicates with adjacent layers through well-defined interfaces.

Layer Diagram

┌─────────────────────────────────────────────────┐
│                  Applications (NPK)              │
│            Firefox · KDE · User Programs         │
├─────────────────────────────────────────────────┤
│              NipCells / Nexters                   │
│         Lightweight & Heavy Isolation             │
├──────────┬──────────┬──────────┬────────────────┤
│ Surface  │ Signal   │ Membrane │  nip           │
│ Manager  │ Forge    │ (Net)    │  (Packages)    │
│ Display  │ A/V/R    │ TCP/IP   │  Graft/Build   │
├──────────┴──────────┴──────────┴────────────────┤
│              Capability Algebra                   │
│     Pledge · Unveil · CSpace · ProvChain          │
├─────────────────────────────────────────────────┤
│              ION Rings (IPC)                      │
│       Lock-free SPSC Ring Buffers                 │
├─────────────────────────────────────────────────┤
│              Rumpk Kernel                         │
│   Scheduler · Memory · SysTable · NetSwitch       │
├─────────────────────────────────────────────────┤
│              Zig HAL                              │
│   VirtIO · UART · GIC · Timer · MMU               │
├─────────────────────────────────────────────────┤
│              Rumkv Hypervisor                     │
│         Type-1 (EL2 / Ring-1 / M-Mode)           │
├─────────────────────────────────────────────────┤
│              nexus-boot                           │
│         Bootloader (<300 LOC)                     │
└─────────────────────────────────────────────────┘

Layer Responsibilities

Boot Layer

nexus-boot is a stripped Limine fork. Less than 300 lines of code. Multi-architecture. Gets the hardware to a known state and hands off to Rumkv or Rumpk. Optional Hall of Fame splash screen.

Hypervisor Layer

Rumkv is a Type-1 hypervisor operating at the highest privilege level (ARM64 EL2, x86 Ring-1, RISC-V M-Mode). It provides hardware isolation between guests and the Rumpk kernel. It is verified with NetBSD ARM64 guests and with a proof-mode Nexus-Linux NipCell that reaches Linux /init and loads the Nexus bridge modules.

Kernel Layer

Rumpk is a 280KB event-driven unikernel. It provides:

• The Harmonic Scheduler with four time spectrums
• ION Rings for zero-copy IPC
• The Kernel Protocol — the stable contract between userland and kernel (typed packets, signed descriptors, capability verbs)
• The Trap ABI — the CPU-facing entry surface (an implementation detail, not the contract)
• The NetSwitch — an L2 packet demuxer

The kernel boundary is a protocol, not a fixed syscall table. Applications target the Kernel Protocol through libnexus; the trap ABI underneath is allowed to change per architecture and per version.

Security Layer

The Capability Algebra provides 7 primitive verbs (SPAWN, SEND, RECV, MAP, MASK, TICK, GRANT). Every operation requires an explicit capability. Pledge/unveil restricts processes to minimum privilege. The Kinetic Economy prevents DoS through energy budgets. ProvChain logs everything.

IPC Layer

ION Rings are lock-free single-producer/single-consumer ring buffers. All inter-process communication flows through them. Zero-copy. No locks. No contention.

Service Layers

• Membrane — Userland TCP/IP (grafted LwIP) + sovereign UTCP transport
• Surface Manager — Sovereign compositor with zero-copy rendering
• SignalForge — Audio, video, and radio signal processing
• nip — Universal package manager with grafting from any ecosystem

Application Layer

Applications run as NPK (Nip Packages) inside NipCells (lightweight isolation) or Nexters (heavy containers with namespace/jail/VM isolation). Every application is sandboxed. Every binary is signed.

For foreign kernels and driver worlds, Nexus uses Linux NipCells. The current M9 proof is QEMU-verified in proof mode; production default start wiring and real cross-boundary data exchange remain follow-up work.

Design Principles

The Kernel Delivers the Mail; It Does Not Read the Letter

The kernel is deliberately minimal. TCP/IP processing, filesystem logic, and display composition all live in userland services. If any service crashes, the kernel survives and restarts it.

Data Moves, Code Stays

CPU cores are isolated. Data flows through ION Rings between fibers. No shared-memory concurrency. No mutex soup. Linear scaling to 256+ cores via DragonflyBSD LWKT message-passing.

Graft What Works, Harden Later

Nexus strategically borrows from Linux (drivers), OpenBSD (security primitives), NetBSD (rump kernels), and Alpine (musl/busybox) — wrapping everything in sovereign abstractions. Foreign code is sanitized, pledged, and frozen into deterministic packages.

One Codebase, Many Targets

The build toolkit reads KDL blueprints and produces bootable images for any target profile. The same code compiles down to a 256-byte sensor firmware or a 40MB cluster node. Feature flags control what gets included.

Component Map

Component	Language	Size	Status
Rumpk	Nim + Zig	280KB	v0.9 Complete
Rumkv	Nim + Zig	—	ARM64 EL2 Complete
NexFS	Zig	—	v0.3.0 (51/51 tests)
Membrane	Nim	—	Operational
UTCP	Zig	~200 LOC	Integrated
LWF	Zig	~15K LOC	24/24 test suites
nip	Nim	—	MVP Complete
nexus-boot	—	<300 LOC	v1 Complete
nexus build	Nim	~2MB	~50% Complete