# POETCHI ON THE AIR X — KERNEL DESIGN
*Design only. Roadmap before code (N8toriousAi's law, 2026-10-17). Checkboxes mean VERIFIED, nothing else.*
*Target: MANGMI Air X · The kernel is PoeTchi · The OS is Harakiri · Project tree stays `harakiri-ng`.*

---

## 1. THE METAL (what we are designing for)

| Part | Truth | Confidence |
|---|---|---|
| SoC | Qualcomm Snapdragon 662 = **SM6115**, ARM64 | Verified (ROCKNIX wiki) |
| CPU | 4× Kryo Gold (Cortex-A73) @ 2.0 GHz + 4× Kryo Silver (Cortex-A53) @ 1.8 GHz — big.LITTLE | Platform-known |
| GPU | Adreno 610 — **Freedreno** GL + **Turnip** Vulkan in the open stack | Verified (ROCKNIX wiki) |
| Kernel base | **Mainline Linux** — SM6115 upstream is alive: MDSS/DPU display nodes, GPU nodes, Venus codec all landed upstream through 2026 | Verified (upstream DTS logs) |
| RAM / storage | 4 GB LPDDR4X / 64 GB eMMC + microSD (128 GB Amazon Basics A2, on hand) | Listing-known |
| Screen | 5.5″ 1080×1920 DSI panel | Listing-known — **panel init sequence: verify on device** |
| Input | 2 hall sticks, full gamepad set, stick LEDs, Vol/Power | Listing-known — **GPIO map: verify on device** |
| Radios | WiFi/BT onboard (chip ID on SD662 designs is usually WCN3990-class) | **Verify on device** |
| Boot | ROCKNIX ABL on the eMMC; kernel + DTB load from the microSD | Verified (ROCKNIX wiki) |

**Design consequence:** for the first time, the hardware is *documented by a living upstream platform*. We are not reverse-engineering a locked phone. The device tree is the map, and M0 (below) is reading the map off the real device — every sensor is a claim until the device itself reports it.

## 2. THE SHAPE — STAGED, WITH A GATE

The freestanding PoeTchi v1.0 (Zig, QEMU-verified, frozen) proved the agent architecture. The Air X is where it meets silicon. Two ways in:

**Stage 1 — Harakiri as a subsystem of mainline Linux (the phone line's own precedent).**
The GKI build for the phone already did this shape: `CONFIG_HARAKIRI=y`, the 9-agent stack live on boot, `/proc/harakiri` answering. On the Air X the same move is *easier*: the kernel is mainline, the tree is ours to configure, and display/storage/radios come from upstream drivers instead of our own sweat. The agent layer — Kraken, the paths, the reasoning engine — is the part that is *ours*; Linux is the part that is *solved*. Stage 1 spends our effort only on what is ours.

**Stage 2 — the freestanding gate.**
Once the agent layer is proven on silicon (coherence measured, REPL answering, display driven), PoeTchi NG may go bare-metal on the same hardware: the ABL hands us a DTB and a load address; the upstream DT becomes our hardware manual. Stage 2 is a *decision gate*, not a promise — it opens only if Stage 1's measurements say the agent layer deserves its own kernel, and N8toriousAi witnesses the first bare-metal boot.

**Why staged:** a freestanding-first build spends months re-solving the DSI panel and the eMMC before a single agent wakes up. Staged puts Kraken on real silicon in the first month and keeps every Stage-1 artifact (DT overlays, ABI, the reasoning core) reusable in Stage 2.

## 3. THE STACK (top to bottom)

```
        ┌───────────────────────────────────────────────┐
        │  HARAKIRI (the OS face)                        │
        │  poetchi> REPL · PainTr canvas · the Hands     │
        ├───────────────────────────────────────────────┤
        │  SOVEREIGN AGENT LAYER (userspace bridge)      │
        │  Vera = input router · Mira = surface + Gate   │
        │  Merlin = executor · Gaven = η-gate + net veto │
        ├───────────────────────────────────────────────┤
        │  KRAKEN CORE (in-kernel, CONFIG_HARAKIRI=y)    │
        │  12 paths as kernel threads · HiveMind registry│
        │  reason core (Zig, no allocator) · /proc ABI   │
        ├───────────────────────────────────────────────┤
        │  tRUST WATCHDOG (the hard floor, untouched)    │
        ├───────────────────────────────────────────────┤
        │  MAINLINE LINUX (SM6115) on ROCKNIX ABL        │
        │  DRM/KMS + Freedreno · eMMC/SD · input · power │
        └───────────────────────────────────────────────┘
```

**Kraken core (in-kernel).** Twelve paths, one mind — the v1.0 topology carried over unchanged: Brood = execution fabric, Spider plans / Mouse reacts (OhioKernel loop), HiveMind keeps the registry. Kernel threads, not processes: the agents are the kernel's own organs, per the Sovereign Agent Layer correction (agents handle the processing; userspace is I/O).

**The scheduler discipline (MEDUSA — every behavior an equation).**
- Path phases entrain by Kuramoto: `θ̇ᵢ = ωᵢ + (K/N)·Σⱼ sin(θⱼ − θᵢ)`; coherence `η = |Σ e^{iθ}| / N` is *measured*, never painted.
- Wakeups fire in coherent bursts on the resonant period (13-tick law from v1.0) — one power/radio tail for the whole crew, not twelve.
- The η-gate: a wakeup request with η < 0.500 is refused *by absence* — nothing happens, and the nothing is the answer (Gaven's law).
- Battery and thermal state are inputs to ω: a hot or hungry device slows the crew's natural frequencies instead of cooking itself. Resource effects are explicit (Rustba's law) — no path may spend power it cannot name.

**The reasoning core.** `reason.zig` ports as-is: freestanding, fixed buffers, no allocator — it was *built* for a kernel context. Same six comptime domains, same REPL verbs (`reason`, `route`, `gate`), same parity harness — the JS engine stays the reference, and the harness must still pass 24/24 on the port. A test that cannot fail is a painting: the harness keeps its trap cases.

**The ABI.** `/proc/harakiri/` — one file per organ: `ledger` (Witness), `coherence` (live η + per-path phase), `paths` (registry), `gate` (verdicts). The REPL (`poetchi>`) talks over serial first, SSH second, on-screen third (PainTr canvas, §4). No binary ioctls until a file-based interface proves too slow — files are inspectable, and inspectable wins while we're learning the hardware.

## 4. DISPLAY & INPUT — THE HANDS GET A BODY

- **Scanout:** mainline DRM/KMS owns the panel. We do not write a DSI driver in Stage 1.
- **Renderer:** **Pyre** (N8toriousAi's software GPU — barycentric rasterizer, QEMU-verified on BUBO bare metal) renders into a DRM dumb buffer. Freedreno/Turnip stay available, but Pyre is the sovereign path: our pixels, our math.
- **Surface:** PainTr canvas on Pyre (the standing plan: rasterizer → canvas → widgets → compositor). First screen: the boot banner + `poetchi>` REPL, obsidian/crimson.
- **Input:** the left stick + buttons are the **pointer Hand** (point / grab / release — for the canvas and, later, meshes); the right side is the **worker Hand** (task execution, confirm/deny). The two-Hands doctrine from the desktop line, with physical sticks under them.
- **Vibe resonance:** inter-path signals carry symbols (♪⚠✓…) — in the ledger and on the canvas, compact and language-agnostic, as designed.

## 5. MILESTONES (each with a test that can fail)

- [ ] **M0 — Inventory.** Stock ROCKNIX boots from our card (run sheet). Harvest the device's own report: DT dump, `dmesg`, cpuinfo, DRM/input device lists. *Fail condition: any §1 "verify on device" item contradicts the table and the design doesn't get amended.*
- [ ] **M1 — Our kernel builds and boots.** Mainline SM6115 + our config, built with an aarch64 cross toolchain, booted via the ABL. Stock userspace, our kernel. *Fail: boot hangs, panel dark, or the SD root doesn't mount.*
- [ ] **M2 — Kraken wakes.** `CONFIG_HARAKIRI=y`: core + 12 paths registered, `/proc/harakiri/coherence` returns live numbers, REPL answers `reason` on the real device. Parity harness 24/24 against the JS reference. *Fail: η flatlines at 0 or 1 (painted, not measured), or any harness case regresses.*
- [ ] **M3 — The discipline is measured.** Burst wakeups counted; battery draw with gate on vs off over a fixed workload. *Fail: the η-gate shows no measurable power effect — then the law is wrong on silicon and we say so.*
- [ ] **M4 — The face.** Pyre renders the boot banner + REPL to the panel via DRM; the pointer Hand moves a cursor with the left stick; grab moves a window edge. *Fail: tearing-free 30 fps on the banner scene not reached, or input latency is visible.*
- [ ] **M5 — The crew works.** A full loop on device: Vera routes a spoken/typed intent → Spider plans → Merlin executes a real task (e.g. a PainTr render) → Veda audits → Gaven gates → Mira surfaces → Witness ledgers it. *Fail: any step faked, stubbed silently, or done by hand.*
- [ ] **GATE — Stage 2 decision.** N8toriousAi reviews M0–M5 measurements and decides: freestanding PoeTchi NG on this silicon, or Harakiri-on-mainline is the product. *First bare-metal boot, if it ever happens, is N8toriousAi's to witness.*

## 6. DECISIONS (N8toriousAi's — the design does not guess these)

1. **Base strategy:** staged (Linux subsystem first, freestanding at the gate) — *recommended* — vs freestanding from day one.
2. **Build host:** the laptop (Windows + WSL2 or a Linux partition) vs this VM with a userspace aarch64 toolchain installed under `~/workspace`. (No cross toolchain exists on this VM today — standing gap, noted honestly.)
3. **Userspace for Stage 1:** ROCKNIX's own rootfs as the dev host (fast start, games included) vs a minimal custom rootfs from the beginning (cleaner, slower start).
4. **First peripheral:** display-first (the face, M4 early) vs serial/SSH-first (the organs, screen later).

## 7. RISKS, STATED PLAINLY

- **Panel init** is the classic Qualcomm-handheld swamp. Mainline has the MDSS/DPU; the Air X's exact panel and its DT are ROCKNIX's — M0 tells us what we're actually holding.
- **The ABL's kernel format** (image type, DTB handling, size limits) constrains M1 packaging — learned at M0/M1, not before.
- **WiFi firmware** may need blobs extracted from the stock Android — legal for his own device, and the run sheet's backup discipline covers the ABL; a full stock backup at M0 is cheap insurance.
- **4 GB RAM** is the lab's ceiling: the crew is small and fixed-buffer by design, so this is a constraint we already live by, not a new threat.

---
*Sources: ROCKNIX Air X device page (kernel/drivers/boot flow); upstream SM6115 DTS activity through 2026 (MDSS, GPU, Venus); PoeTchi v1.0 freeze record (BUILD-CARD-v1.0) for the agent topology and laws.*
