# Nexus Project Vision
## The Hybrid Unikernel That Never Dies

**Version:** 3.0 (The Factory Update)
**Date:** January 3, 2026
**Status:** v0.9 (Grafting Factory Operational)

---

## The Core Vision: The Nexus Factory

Nexus is not just an operating system. It is a **Liquid OS Factory** designed to evolve.

We reject the false choice between "using existing ecosystems" (Linux/BSD) and "building something new" (Unikernels). We do both, in phases.

### The Strategy: Graft. Evolve. Sovereignize.

1.  **Graft (NIIX Bootstrap)**: We define the OS using **KDL Schemas**. The factory (`nexus build`) ingests foreign artifacts (Linux drivers, BSD security tools, Alpine userland) via `nip` adapters. We sanitize them (strip docs/debug), pledge them (apply security constraints), and output deterministic **Cells** (`.npk`).
2.  **Evolve (Sovereignization)**: Once bootstrapped, we replace the grafted organs one by one. We strip `io-sock` and POSIX networking, replacing them with **ION Rings** (lock-free channels) and **UTCP** (Sovereign transport).
3.  **Endgame (Full Sovereignty)**: The final OS has zero dependencies on Linux or BSD code. it is a pure, mathematically provable Unikernel ecosystem authenticated by **ProvChain**.

---

## 1. NIIX: The Grafting Engine (Phase 1)

**"We graft concepts, not codebases."**

We use `nip` as a **Universal Adaptor**. It fetches, mutates, and freezes foreign code into our single address space universe.

| Source | Grafted Component | Why? |
|--------|-------------------|------|
| **Linux (Chimera)** | Drivers (GPU, WiFi) | Immediate hardware support without 10-year dev cycle. |
| **OpenBSD** | `pledge` / `unveil` | Best-in-class security primitives (logic ported). |
| **NetBSD** | Rump Kernels | Usable TCP/IP stack in userspace (temporary shim). |
| **Alpine** | `musl` / `busybox` | Minimal POSIX shim for compatibility. |

**The Workflow:**
1.  **Map**: `nexus build` reads `system.kdl`.
2.  **Filter**: `nip` fetches external pkg, strips bloat/docs to <5% size.
3.  **Reduce**: Compiles into a static `.npk` Cell with a **Variant-CID**.

---

## 2. Sovereign Evolution: Ditching the Baggage (Phase 2)

We do not stay grafted forever. We evolve away from the "Dinosaur" tech.

### Networking: The Network Membrane

> "The Kernel delivers the mail; it does not read the letter."

We reject the monolithic kernel stack (Linux model). TCP/IP is a singularity of entropy—when it fails, the system dies. 

**The Solution:** The TCP/IP stack lives in the **Membrane** (`libnexus.a`), not the Kernel (Rumpk). The Kernel is a dumb, high-performance **Layer-2 Switch** (The **NetSwitch**).

| Layer | Component | Role |
|-------|-----------|------|
| L0 | `hal/virtio_net.zig` | Raw frame I/O (Dumb Pipe) |
| L1 | `core/netswitch.nim` | L2/L3 Demux, Per-Process Ring Routing |
| L2 | ION Rings (Private Pair) | Zero-Copy Transport (`proc_rx`, `proc_tx`) |
| L3 | `libs/membrane/net/` | LwIP (Grafted) TCP/IP Stack |
| L4 | POSIX Shim | `socket()`, `connect()`, `send()` |

**Result:** If `curl` crashes due to a malformed packet, only `curl` dies. The Kernel survives. **Sovereignty Level 10: Network Isolation.**

**See:** [SPEC-017: The Network Membrane](/.agents/specs/SPEC-017-NETWORK-MEMBRANE.md)

### Sovereign Transport: UTCP

For internal Nexus-to-Nexus traffic, we use **UTCP** (Unikernel Transport Control Protocol).

*   **Identity-Centric:** Nodes dial by **CellID** (SipHash-128), not IP address.
*   **EtherType Fork:** Legacy IPv4 (`0x0800`) → LwIP. Sovereign (`0x88B5`) → UTCP.
*   **NACK-Based Reliability:** We only scream when we miss a packet. Superior to TCP's ACK-heavy model.
*   **DDoS Immunity:** NetSwitch drops packets for unknown `CellID`s. No open ports to scan.

**See:** [SPEC-018: UTCP Sovereign Transport](/.agents/specs/SPEC-018-UTCP-SOVEREIGN-TRANSPORT.md)

### Concurrency: Echo Chambers

We reject the "Thread Soup".
*   **Concept**: **Echo Chambers**.
*   **Mechanism**: CPU cores are isolated. Data moves, code stays.
*   **Benefit**: Zero lock contention. Linear scaling.

### Security: Computable Trust
*   **ProvChain**: Every artifact, every boot, every heartbeat is logged to an immutable ledger.
*   **Verification**: `nexus verify` checks the Ed25519 signature + Content ID (CID) of the running kernel against the ledger.

---

## 3. The Flagship Profiles (STCs)

We build five specific "Standard Template Constructs" (STCs).

| Profile | Binary | Role | Strategy |
|---------|--------|------|----------|
| **Tinybox** | 32KB | **The Spark** | Pure Rust/Nim bootloader. 100% Sovereign. |
| **Cryptobox** | 1.2MB | **The Vault** | HSMs/Satellites. Grafted NetBSD rump + EROFS shield. |
| **Dragonbox** | 40MB | **The Swarm** | K8s/Cloud. Stripped Linux kernel + `containerd`. |
| **Nexbox** | 150MB | **The Forge** | Dev Workstation. Full Linux Graft (Alpine/Chimera base). |
| **Linbox** | 500MB+ | **The Station** | Desktop. KDE Plasma on Wayland (Grafted). |

---

## 4. Implementation Roadmap

### Q1 2026: The Grafting Factory (Current)
*   **Goal**: Demonstrate the "Factory" pipeline & GUI Isolation.
*   **Tech**: `nexus build --profile=tinybox` + **Surface Manager MVP**.
*   **Validation**: Graft BSD `pledge` logic; Prove GUI isolation without X11 (Anti-Qubes).
*   **Registry**: DuckDB implementation for semantic package queries.

### Q2 2026: The Sovereign Shift
*   **Goal**: First "Pure" NPLs & Peer-to-Peer Comms.
*   **Tech**: **Membrane** (Userland Networking) + **UTCP v1.0**.
*   **Action**: Replace `LwIP` with Zig HAL; Kill `qrexec` with Sovereign Channels.
*   **Hardware**: VisionFive 2 (RISC-V) Demo.

### Q3 2026: The Unikernel Dominance
*   **Goal**: Rumkv v1.0 & Desktop Profile.
*   **Tech**: Radiation-Hardened Kernel + **Nexbox Desktop**.
*   **Target**: ESA/Military contracts & Qubes OS Refugees.
*   **Killer Feature**: Hot-swap NPLs (Crash = Restart in 2ms).

---

## 5. Why We Will Win

**QNX** is a dinosaur. They have military contracts but closed, stagnant code.
**Qubes OS** is security theater. It relies on a massive ~20M line "Dom0" (Linux) attack surface.
**Linux** is a fatberg. It cannot be fixed, only layered over.

**Nexus** is a **Factory**. We steal their fire (drivers/apps) but leave their ash (legacy/bloat) behind. We build the system they wish they had 20 years ago.

*Forge Unbreakable. Graft Smart. Evolve Forever.*