# Sovereign Ledger: VirtIO Block Driver

## Overview
Phase 10 "The Sovereign Ledger" introduces persistent storage capabilities to **Rumpk** via a custom **VirtIO Block Driver**. This allows the **NipBox** userland to perform direct sector-level I/O operations on a raw disk image (`storage.img`), establishing the foundation for a future Sovereign Filesystem.

## Architecture

### 1. Hardware Abstraction (L0 HAL)
- **Driver:** `hal/virtio_block.zig`
- **Device ID:** `0x1001` (Legacy Block) or `0x1042` (Modern).
- **Transport:** Leverages `hal/virtio_pci.zig` for universal PCI resource discovery and I/O port allocation.
- **Mechanism:** Synchronous Polling (Busy Wait).
  - Uses a 3-Descriptor Chain per request:
    1.  **Header:** `VirtioBlkReq` (Type, Priority, Sector).
    2.  **Buffer:** Data payload (512 bytes).
    3.  **Status:** Completion byte (0 = OK).
- **Orchestration:** Initialized in `hal/entry_riscv.zig` via `hal_io_init`.

### 2. Kernel Core (L1 Logic)
- **Command Ring:** Adds `CMD_BLK_READ` (0x600) and `CMD_BLK_WRITE` (0x601) to `ion.nim`.
- **Arguments:** `BlkArgs` structure marshals `sector`, `buffer_ptr`, and `len` across the User/Kernel boundary.
- **Dispatch:** `kernel.nim` routes these commands from the `chan_cmd` ring directly to the HAL functions `virtio_blk_read/write`.

### 3. Userland Shim (Membrane)
- **Syscalls:** `libc_shim.zig` exposes `nexus_blk_read` and `nexus_blk_write`.
- **Packaging:** These wrappers construct the `BlkArgs` struct and invoke `nexus_syscall`.

### 4. Userland Application (NipBox)
- **Command:** `dd`
- **Syntax:**
  - `dd read <sector>`: Dumps the first 16 bytes of the sector in Hex.
  - `dd write <sector> <string>`: Writes the string (UTF-8) to the sector, zero-padded.
- **Protocol:** Uses the new IO syscalls to interact with the Ledger.

## Deployment & Verification
- **Disk Image:** `build/storage.img` (Raw, 32MB).
- **QEMU:** Attached via `-drive if=none,format=raw,file=build/storage.img,id=hd0 -device virtio-blk-pci,drive=hd0,disable-modern=on`.
- **Status:**
  - **Write:** Confirmed successful (Hexdump valid on host).
  - **Read:** Driver operation successful, data verification ongoing.
  - **Boot:** Stable initialization of both Network and Block devices simultaneously (via fixed PCI I/O allocation).

## Next Steps
- **Data Integrity:** Investigate zero-readback issue (likely buffer address mapping or flag polarity).
- **Filesystem:** Implement a minimalist inode-based FS (SovFS) on top of the raw ledger.
- **Async I/O:** Move from busy-polling to Interrupt-driven (Virtqueue Notification) for high throughput.