1  # NeuralOS & Laya-Core: Test-First Engineering Execution Plan
   2  
   3  **Document ID:** `NEURALOS-EXEC-PLAN-v2.0`  
   4  **Chief Architect:** Shubham Sharma  
   5  **Target Appliance:** Dell Node-01 (Intel Core i5-3337U Ivy Bridge @ 1.80GHz, 2C/4T, 7.3 GB RAM, ADATA 240 GB SSD)  
   6  **Date:** November 2026  
   7  **Methodology:** Strict Test-First Driven Development (TFDD)  
   8  
   9  ---
  10  
  11  ## 1. System Target Architecture Summary
  12  
  13  ```
  14  Dell Node-01 (7,305 MB Physical DRAM)
  15  ├── Core 0 (Housekeeping & IRQs):
  16  │   ├── Linux Kernel 7.0 (MGLRU, THP madvise, ZRAM 1.2GB cap)
  17  │   ├── Ubuntu Base (SSH, NetworkManager, Tor proxy :9050, TorrServer :8090)
  18  │   └── PID 1 (neuralos-init) & hardware interrupt routing (irqaffinity=0)
  19  └── Cores 1–3 (Dedicated AI Compute):
  20      ├── laya.slice (cgroup v2: MemoryMin=4500M, CPUWeight=10000)
  21      │   ├── laya-daemon (Rust Edition 2024, AVX + F16C intrinsics)
  22      │   ├── /dev/shm/laya_arena (64 MB lockless SPSC/MPSC ring + futex_waitv)
  23      │   ├── Tier-0A Router (daachorse SIMD Aho-Corasick, < 2 µs)
  24      │   ├── Tier-0B Router (Int8 Model2Vec static embeddings, < 25 µs)
  25      │   ├── Tier-1 MoE (Granite-3.0-3B-A800M Q4_K_M, 800M active params, Q8_0 KV)
  26      │   └── Wasmtime Subagent Pool (< 350 µs cold start, < 2 MB RAM per agent)
  27      └── /dev/tty1 Framebuffer Surface (Ratatui Native TUI, 4 MB RAM)
  28  ```
  29  
  30  ---
  31  
  32  ## 2. Immediate Prerequisites
  33  
  34  ### Step 0.1: Install Rust Toolchain on Dell Node-01
  35  Dell Node-01 requires the stable Rust toolchain (Edition 2024 / cargo >= 1.82):
  36  ```bash
  37  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
  38  source "$HOME/.cargo/env"
  39  ```
  40  
  41  ### Step 0.2: Configure Compiler Flags for Ivy Bridge
  42  Create `/home/agent/.cargo/config.toml` on Dell Node-01 to ensure all binaries generate valid Ivy Bridge vector code without AVX2 illegal instructions:
  43  ```toml
  44  [target.x86_64-unknown-linux-gnu]
  45  rustflags = ["-C", "target-cpu=ivybridge", "-C", "target-feature=+avx,+f16c"]
  46  
  47  [profile.release]
  48  opt-level = 3
  49  lto = "fat"
  50  codegen-units = 1
  51  panic = "abort"
  52  ```
  53  
  54  ---
  55  
  56  ## 3. Phase-by-Phase Roadmap
  57  
  58  ### PHASE 1: Host OS Pruning & Kernel Memory Tuning (Days 1–2)
  59  * **Goal:** Reduce host idle RAM from 1,850 MB to **< 150 MB**, freeing **~7.1 GB of physical DRAM** for AI models.
  60  * **Test Gate:** `tests/test_phase1_kernel.sh` (fails if idle RAM > 220 MB or MGLRU is disabled).
  61  * **Tasks:**
  62    1. Write `tests/test_phase1_kernel.sh`.
  63    2. Switch default target to headless `multi-user.target`.
  64    3. Purge desktop bloat (`snapd`, `gnome`, `gdm3`).
  65    4. Configure `/etc/sysctl.d/99-neuralos.conf` (`vm.swappiness=100`, `vm.vfs_cache_pressure=50`).
  66    5. Enable MGLRU (`/sys/kernel/mm/lru_gen/enabled = 0x0007`).
  67    6. Enable Transparent HugePages in `madvise` mode (`/sys/kernel/mm/transparent_hugepage/enabled = madvise`).
  68    7. Configure ZRAM: 2.4 GB uncompressed disksize, backed by max 1.2 GB physical RAM with `zstd`.
  69    8. Create `/etc/systemd/system/laya.slice` and `/etc/systemd/system/agent-sandbox.slice`.
  70  * **Validation:** Run `bash tests/test_phase1_kernel.sh` -> Output `[ALL PASSED]`.
  71  
  72  ---
  73  
  74  ### PHASE 2: Lockless 64-Byte Cache-Aligned Shared Memory IPC (Days 3–6)
  75  * **Goal:** Replace HTTP/JSON socket overhead with a zero-copy shared memory arena achieving **< 4.5 µs P99 latency**.
  76  * **Test Gate:** `crates/laya-ipc/tests/ipc_torture.rs` (10-million packet torture test, zero heap allocations, 64-byte alignment proof).
  77  * **Tasks:**
  78    1. Implement `LayaIpcDescriptor` in `crates/laya-ipc`:
  79       ```rust
  80       #[repr(C, align(64))]
  81       pub struct LayaIpcDescriptor {
  82           pub request_id: u64,
  83           pub arena_offset: u32,
  84           pub payload_len: u32,
  85           pub intent_code: u16,
  86           pub flags: u16,
  87           pub confidence_q8: u8,
  88           pub source_agent_id: u8,
  89           pub _reserved: [u8; 42],
  90       }
  91       ```
  92    2. Implement SPSC/MPSC circular ring buffers with isolated `read_idx` and `write_idx` cache lines.
  93    3. Implement hybrid adaptive spin-then-futex polling using `futex_waitv`.
  94    4. Run Criterion benchmark `cargo bench --bench ipc_ring`.
  95  
  96  ---
  97  
  98  ### PHASE 3: Tier-0A (SIMD) & Tier-0B (Int8 Static Embedding) Router (Days 7–10)
  99  * **Goal:** Classify 80% of user queries in **< 25 µs** without running a neural transformer layer.
 100  * **Test Gate:** `tests/router_eval.rs` using `golden_intents_200.jsonl` (F1 score >= 96.5%, zero false positive tool executions on out-of-distribution queries).
 101  * **Tasks:**
 102    1. Create `tests/golden_intents_200.jsonl` (200 categorized real-world queries).
 103    2. Implement **Tier-0A** in `crates/laya-router`: `daachorse` SIMD Double-Array Aho-Corasick automaton for deterministic slash/system commands (< 2 µs).
 104    3. Implement **Tier-0B**: Static Int8 embeddings (`Model2Vec` / `potion-base-8M` quantized to 256 dimensions) with AVX/SSE4.2 cosine similarity against 500 tool centroids (< 25 µs).
 105    4. Implement confidence threshold gating ($\tau \ge 0.82 \rightarrow$ fast-path tool execution; $\tau < 0.82 \rightarrow$ route to Tier-1 SLM).
 106  
 107  ---
 108  
 109  ### PHASE 4: Tier-1 MoE/SLM Engine & Wasmtime Sandboxing (Days 11–16)
 110  * **Goal:** Run deep reasoning and multi-step agent planning with **100% in-DRAM execution** and microsecond subagent isolation.
 111  * **Test Gate:** `tests/test_wasm_jail.rs` (cold start <= 350 µs, memory cap strictly enforced, capability-based filesystem jail).
 112  * **Tasks:**
 113    1. Compile `llama.cpp` Rust bindings with Ivy Bridge flags: `GGML_AVX=ON`, `GGML_F16C=ON`, `GGML_AVX2=OFF`.
 114    2. Deploy `Granite-3.0-3B-A800M-Instruct-Q4_K_M.gguf` with `Q8_0` quantized KV-cache (8,192 token window pinned via `mlock`).
 115    3. Configure Wasmtime pooling allocator (`wasmtime::PoolingAllocationConfig`, 16 pre-allocated linear memory slots).
 116    4. Implement capability-based WASI file and network descriptors for subagent tools.
 117  
 118  ---
 119  
 120  ### PHASE 5: Hardware IRQ Isolation & Native `/dev/tty1` Cockpit (Days 17–20)
 121  * **Goal:** Eliminate token generation jitter and deliver an instant-boot physical cockpit on Dell Node-01.
 122  * **Test Gate:** `tests/test_jitter_under_load.sh` (inter-token latency degradation <= 3.5% under 100% background CPU/IO stress).
 123  * **Tasks:**
 124    1. Pin all hardware interrupts to Core 0 (`irqaffinity=0`).
 125    2. Isolate Threads 1..3 for AI inference (`nohz_full=1-3`, `rcu_nocbs=1-3`).
 126    3. Build `crates/laya-tui` in Rust using `ratatui` + `crossterm`.
 127    4. Create systemd drop-in `getty@tty1.service.d/override.conf` to launch `laya-tui` on boot (< 2.8s boot time, 4 MB RAM).
 128    5. Run master scoreboard benchmark: `sudo ./scripts/run_scoreboard.sh`.
 129