# Rumpk

Sovereign unikernel. Zig (L0 HAL) + Nim (L1 kernel logic). Dual-arch: RISC-V 64 and ARM64.

**Status:** Experimental — boots on QEMU, 14/14 fibers (riscv64), 9/9 fibers (aarch64)
**License:** [Libertaria Sovereign License (LSL) v1.0](LICENSE)

## Build

### Prerequisites

- Zig 0.15.x
- Nim 2.0.x
- QEMU (for boot testing)
- bash

### Quick Start

```bash
# Clone
git clone https://git.sovereign-society.org/nexus/rumpk.git
cd rumpk

# Build kernel (RISC-V 64, default)
bash build_nim.sh riscv64     # Nim -> C -> .o
bash build_lwip.sh            # LwIP static lib
zig build                     # Link final kernel ELF

# Boot test
./run.sh
```

### ARM64

```bash
bash build_nim.sh aarch64
bash build_lwip.sh
zig build -Darch=aarch64
./run_aarch64.sh
```

### Full Build (kernel + NipBox userland + initrd)

```bash
bash build_full.sh riscv64    # or: bash build_full.sh aarch64
zig build                     # or: zig build -Darch=aarch64
```

## Architecture

```
rumpk/
├── boot/              L0: Entry points, linker scripts (Zig/ASM)
├── hal/               L0: Hardware Abstraction (Zig)
│   ├── entry_riscv.zig    RISC-V boot, MMU, page tables
│   ├── entry_aarch64.zig  ARM64 boot, MMU, GIC
│   ├── virtio_net.zig     VirtIO network driver
│   ├── virtio_block.zig   VirtIO block driver
│   ├── virtio_mmio.zig    VirtIO MMIO transport (ARM64)
│   ├── virtio_pci.zig     VirtIO PCI transport (RISC-V)
│   ├── mm.zig             Memory management
│   ├── channel.zig        IPC ring buffers
│   └── cspace.zig         Capability space (HAL side)
├── core/              L1: Kernel logic (Nim)
│   ├── kernel.nim         kmain, boot sequence
│   ├── sched.nim          Spectrum scheduler (Photon/Matter/Gravity/Void)
│   ├── fiber.nim          Cooperative fiber management
│   ├── ion.nim            ION memory allocator
│   ├── cspace.nim         Capability enforcement
│   ├── ontology.nim       System Truth Ledger
│   ├── netswitch.nim      Network fiber (DHCP/TCP/ICMP)
│   ├── loader.nim         ELF loader + BKDL manifest
│   └── fs/                VFS + LittleFS bridge
├── libs/
│   ├── membrane/          POSIX adaptation layer
│   │   ├── libc.nim       Freestanding libc for Nim
│   │   ├── net_glue.nim   LwIP <-> kernel bridge
│   │   └── compositor.nim Display compositor
│   └── libertaria/        Libertaria Wire Format integration
├── npl/nipbox/            NipBox userland shell (21 commands)
├── apps/                  Subject binaries, linker scripts
└── vendor/                LwIP, LittleFS, mksh (vendored)
```

### Design Principles

- **Two-language split**: Zig for hardware (deterministic, zero-alloc), Nim for logic (expressive, ARC)
- **Capability security**: CSpace + Pledge + BKDL manifests. No ambient authority.
- **Spectrum scheduling**: 4-tier priority (Photon 2ms, Matter 10ms, Gravity 50ms, Void unlimited)
- **System Truth Ledger**: Every security event recorded. Auditable kernel state.

## NexusOS Workspace

Rumpk is the kernel component of NexusOS. The full system consists of:

| Repository | Purpose | Build |
|------------|---------|-------|
| [rumpk](https://git.sovereign-society.org/nexus/rumpk) | Kernel | `zig build` |
| [nip](https://git.sovereign-society.org/nexus/nip) | Package manager | `nim c nip.nim` |
| [nexus](https://git.sovereign-society.org/nexus/nexus) | Build toolkit | `nim c src/nexus.nim` |
| [nipbox](https://git.sovereign-society.org/nexus/nipbox) | Userland shell | Built into rumpk via `build_full.sh` |
| [nexfs](https://git.sovereign-society.org/nexus/nexfs) | Flash filesystem | `zig build test` |

### Clone All Repos

```bash
mkdir nexus-workspace && cd nexus-workspace
for repo in rumpk nip nexus nipbox nexfs; do
  git clone https://git.sovereign-society.org/nexus/${repo}.git
done
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon).

## Stewardship

Copyright (c) 2025-2026 Markus Maiwald
Stewardship: Self Sovereign Society Foundation