# Maxwell Roadmap

## From Concept to Proof of Concept

---

## The Real Deliverables

Maxwell is a research project.

| Deliverable           | Purpose                                                                        | Required? |
| --------------------- | ------------------------------------------------------------------------------ | --------- |
| **Planning Video**    | Shows _how you think_—the whiteboard session breaking down the three paradoxes | **YES**   |
| **Baseline Data**     | Proves Linux CFS wastes energy on parasites—the "before" in your story         | **YES**   |
| **The Narrative**     | The interview answer and GitHub README                                         | **YES**   |
| Sprint 1 (Real MSRs)  | Deeper systems credibility, thermal-aware pricing                              | Optional  |
| Sprint 2-4 (Full PoC) | Maxwell kills the Leech—the "after" that proves the thesis                     | Optional  |

---

## Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      ROADMAP PHASES                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  DAY 0          BASELINE        SPRINT 1        SPRINT 2        │
│  ──────         ────────        ────────        ────────        │
│  Environment    Control         Physics         Hypervisor      │
│  Setup          Experiment      Engine          Integration     │
│     │              │               │               │            │
│     ▼              ▼               ▼               ▼            │
│  Rust crates    Agents +        Real MSR/RAPL   Firecracker     │
│  + toolchain    Linux CFS       + PID control   + Vsock         │
│                 + Metrics                                       │
│                                                                 │
│  ════════════════════════════════════════════════════════════   │
│  │ Research COMPLETE HERE  │     (Optional for commercial)      │
│  ════════════════════════════════════════════════════════════   │
│                                                                 │
│  SPRINT 3        SPRINT 4                                       │
│  ────────        ────────                                       │
│  Economy         Multi-Agent                                    │
│  Implementation  Demo                                           │
│     │               │                                           │
│     ▼               ▼                                           │
│  Landauer's      Natural Selection                              │
│  Tax + eBPF      Dashboard + Video                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Research Validation Summary

The following parameters have been empirically validated:

| Component            | Original Assumption | Research Finding                         | Status           |
| -------------------- | ------------------- | ---------------------------------------- | ---------------- |
| Pause/Resume Latency | <10ms achievable    | <10ms requires CPU pinning + RT priority | ✅ Conditional   |
| eBPF Overhead        | ~500ns, <1%         | 480ns validated; needs ringbuf for <1%   | ✅ Validated     |
| RAPL Accuracy        | ±5%                 | ±5% only on calibrated hosts (Tier 1)    | ✅ Conditional   |
| PID Time Constant    | τ=1s fixed          | τ varies 0.3-3.5s by hardware class      | ✅ Implemented   |
| GSP PoA Bound        | 1.618               | 1.618 at steady-state; 1.8-2.2 dynamic   | ✅ Validated     |

---

## Day 0: Environment Setup

### Hardware Requirements

Bare metal is required. You cannot develop a thermal-aware hypervisor inside a cloud VM because the hypervisor hides the physics.

### Day 0 Exit Criteria

- [ ] Rust nightly compiles
- [ ] Firecracker binary runs
- [ ] MSR readable: `sudo rdmsr 0x611` returns a value
- [ ] Project compiles: `cargo build`

---

## Baseline: The Control Experiment

**Goal:** Build agents and measurement infrastructure. Run Linux CFS baseline. Capture data showing "fair" scheduling wastes energy.

### Baseline Exit Criteria

- [ ] Both agents build and run in Docker
- [ ] Metrics collection captures temp, power, primes at 1Hz
- [ ] 5-minute baseline run completes without errors
- [ ] Summary shows efficiency (primes/Joule) under "fair" scheduling

---

## Sprint 1: The Physics Engine

**Goal:** Replace MockThermal with real hardware telemetry.

- Step 1.1: MSR Interface (read real temperature)
- Step 1.2: PID Controller (smooth price response)
- Step 1.3: Stress Test (verify under load)

---

## Sprint 2: The Cell Membrane

**Goal:** Replace thread-sleep with actual VM containment.

- Step 2.1: Firecracker Jailer
- Step 2.2: Vsock Tunnel
- Step 2.3: Pause/Resume Control (<10ms latency)

---

## Sprint 3: The Economy

**Goal:** Implement Landauer's Tax.

- Step 3.1: eBPF Instrumentation (track munmap/madvise)
- Step 3.2: Tax Logic (debit wallet on memory free)
- Step 3.3: Bankruptcy Handler (trigger apoptosis)

---

## Sprint 4: The Demonstration

**Goal:** Multi-agent natural selection demo with dashboard.

- Step 4.1: The Good Agent (Scientist - finds primes)
- Step 4.2: The Bad Agent (Miner - burns cycles, churns memory)
- Step 4.3: Dashboard (TUI showing auction, thermal, wallets)

### The Demo Script

1. Launch both agents with equal funding
2. Watch Miner drive thermal load → prices spike
3. Miner burns through capital → apoptosis
4. Temperature drops → Scientist resumes at lower price

**Closing line:** "We demonstrated that resource constraints can enforce economic discipline on autonomous agents."