From 96ee0a0112d5d86259f3d277e41d380333df8a7f Mon Sep 17 00:00:00 2001
From: Markus Maiwald <markus@maiwald.work>
Date: Tue, 6 Jan 2026 18:40:30 +0100
Subject: [PATCH] docs(core): add Network Membrane technical documentation

---
 docs/Network_Membrane.md | 60 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 docs/Network_Membrane.md

diff --git a/docs/Network_Membrane.md b/docs/Network_Membrane.md
new file mode 100644
index 0000000..040d664
--- /dev/null
+++ b/docs/Network_Membrane.md
@@ -0,0 +1,60 @@
+# Nexus Network Membrane (Grafted LwIP)
+
+**Status:** Experimental / Grafted (Phase 1)
+**Version:** v0.1 (Hybrid Polling)
+**Location:** `core/rumpk/libs/membrane`
+
+## Overview
+
+The Network Membrane is a userland networking stack running inside the `init` process (Subject Zero). It provides TCP/IP capabilities to the Nexus Sovereign Core by "grafting" the lightweight IP (LwIP) stack onto the Nexus ION (Input/Output Nexus) ring architecture.
+
+This implementation follows **SPEC-017 (The Network Membrane)** and **SPEC-701 (The Sovereign Network)**.
+
+## Architecture
+
+### 1. The Graft (LwIP Integration)
+Nexus avoids writing a TCP/IP stack from scratch for Phase 1. Instead, we compile LwIP as a static library (`libnexus.a`) linked into the userland payload.
+*   **Mode:** `NO_SYS` (No OS threads). LwIP is driven by a single event loop.
+*   **Memory:** Static buffers (Pbufs) managed by `ion_client`.
+
+### 2. The Glue (`net_glue.nim`)
+Bridging Nim userland and C LwIP:
+*   **`pump_membrane_stack()`**: The heartbeat function. It must be called repeatedly by the main loop. It:
+    *   Checks `sys_now()` for timer expiration (DHCP fine/coarse, TCP fast/slow).
+    *   Polls `ion_net_rx` for inbound packets from the Kernel (NetSwitch).
+    *   Injects packets into `netif->input`.
+*   **`ion_linkoutput`**: The LwIP callback to send packets. Uses `ion_net_tx` to push packets to the Kernel.
+
+### 3. Syscall Interface
+LwIP requires system services provided via `libc.nim` and the `SysTable`:
+*   **`sys_now()`**: Returns monotonic time in milliseconds using `rdtime` (via `syscall_get_time_ns`).
+*   **`printf/abort`**: Mapped to `console_write` syscalls.
+
+## Current Limitations (v1.1.1)
+
+### 1. The "Busy Wait" Workaround
+**Issue:** The kernel Scheduler currently lacks a hardware Timer Driver for `wfi` (Wait For Interrupt).
+**Symptom:** Calling `nanosleep` (0x65) puts the fiber to sleep forever because no timer interrupt wakes the CPU.
+**Workaround:** `init.nim` uses a busy-wait loop (`while sys_now() - start < 10: yield()`). This keeps the network stack responsive but results in high CPU usage.
+**Fix Planned:** Implement ACLINT/SBI Timer driver in HAL.
+
+### 2. No IP Acquisition (Ingress)
+**Issue:** While Egress (DHCP DISCOVER) works and is verified, no Ingress packets (DHCP OFFER) are received.
+**Suspected Cause:** VirtIO interrupts might be masked or not delegated correctly, preventing `NetSwitch` from seeing inbound traffic.
+
+## Usage
+
+The stack is initialized automatically by `init`:
+```nim
+import libs/membrane/net_glue
+
+membrane_init()
+while true:
+  pump_membrane_stack()
+  # Sleep/Yield
+```
+
+## Logs & Debugging
+*   **Egress:** grep for `[Membrane] Egress Packet`
+*   **Timers:** grep for `[Membrane] DHCP Fine Timer`
+*   **Packet Dump:** Enable `LWIP_DEBUG` in `lwipopts.h` (requires recompile).