research-notes/blog/content/notes/002-building-the-scaffolding/files/architecture.md

# Maxwell Architecture

## Technical Specification

> **Note:** This is a reference architecture for research.

---

## System Overview

Maxwell is a Type-2 Hypervisor Controller that manages Firecracker microVMs (or WASM modules) through an economic scheduler. It replaces the concept of "time slices" with "quanta of action" purchased through continuous auction.

```
┌─────────────────────────────────────────────────────────────────┐
│                     USER SPACE (Agents)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ Agent A     │  │ Agent B     │  │ Agent C     │              │
│  │ (MicroVM)   │  │ (MicroVM)   │  │ (WASM)      │              │
│  │ Wallet: 5k  │  │ Wallet: 200 │  │ Wallet: 0   │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          │ vsock                                │
├──────────────────────────┼──────────────────────────────────────┤
│                     MAXWELL DAEMON (Ring 0)                     │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐        │
│  │ Auction       │  │ Thermal       │  │ Wallet        │        │
│  │ Engine        │  │ Controller    │  │ Ledger        │        │
│  │ (Vickrey)     │  │ (PID)         │  │ (Crypto)      │        │
│  └───────────────┘  └───────────────┘  └───────────────┘        │
│                          │                                      │
├──────────────────────────┼──────────────────────────────────────┤
│                     HARDWARE LAYER                              │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐        │
│  │ CPU/KVM       │  │ RAPL/MSR      │  │ Thermal       │        │
│  │               │  │ (Energy)      │  │ Sensors       │        │
│  └───────────────┘  └───────────────┘  └───────────────┘        │
└─────────────────────────────────────────────────────────────────┘
```

---

## Layer 0: The Physics Interface

### Thermal Sensor Subsystem

Reads real hardware telemetry with microsecond precision.

```rust
/// Model Specific Register addresses for Intel CPUs
const MSR_RAPL_POWER_UNIT: u32 = 0x606;
const MSR_PKG_ENERGY_STATUS: u32 = 0x611;
const IA32_THERM_STATUS: u32 = 0x19C;

pub trait ThermalSensor: Send + Sync {
    /// Die temperature in Celsius
    fn read_die_temp(&self) -> f64;

    /// Joules consumed since boot
    fn read_energy_consumed(&self) -> u64;

    /// Current power draw in Watts
    fn read_power_draw(&self) -> f64;
}
```

---

## Layer 1: The Auction Scheduler

### Replacing CFS with the Vickrey Engine

The Completely Fair Scheduler (CFS) is removed. In its place: a second-price sealed-bid auction running every 10ms.

```rust
pub struct VickreyEngine {
    /// Max-heap of bids, sorted by bid amount
    bid_heap: BinaryHeap<Bid>,
    /// Current market-clearing price
    spot_price: Joule,
    /// Thermal controller reference
    thermal: Arc<dyn ThermalSensor>,
}

impl VickreyEngine {
    /// Called every 10ms by timer interrupt
    pub fn clear_market(&mut self) -> Vec<Execution> {
        // 1. Calculate supply based on thermal headroom
        let temp = self.thermal.read_die_temp();
        self.spot_price = self.calculate_spot_price(temp);

        // 2. Clear the auction - winner pays second-highest price
        let mut winners = Vec::new();

        while let Some(bid) = self.bid_heap.pop() {
            if bid.amount >= self.spot_price {
                winners.push(Execution {
                    pid: bid.pid,
                    payment: self.spot_price,
                    duration_ms: 10,
                });
            } else {
                break;
            }
        }

        winners
    }
}
```

---

## Layer 2: The Wallet System

Every process has an economic identity.

```rust
pub struct Wallet {
    /// Ed25519 public key (owner identity)
    pub address: [u8; 32],
    /// Current balance in atomic Joule units
    pub balance: AtomicU64,
    /// Maximum authorized spend per tick
    pub max_bid: Joule,
}

impl Wallet {
    pub fn debit(&self, amount: Joule) -> Result<(), InsolvencyError> {
        let current = self.balance.load(Ordering::SeqCst);
        if current < amount.0 {
            return Err(InsolvencyError::InsufficientFunds);
        }
        // Atomic CAS to prevent double-spend
        self.balance.compare_exchange(
            current,
            current - amount.0,
            Ordering::SeqCst,
            Ordering::SeqCst,
        )
    }
}
```

### Landauer's Tax (Entropy Accounting)

```rust
/// Landauer's principle: minimum energy to erase 1 bit
/// At room temperature (300K): kT × ln(2) ≈ 2.87 × 10^-21 J
const LANDAUER_CONSTANT: f64 = 2.87e-21;

pub fn calculate_erasure_tax(bytes_freed: u64) -> Joule {
    let bits = bytes_freed * 8;
    let theoretical_cost = bits as f64 * LANDAUER_CONSTANT;
    let practical_cost = theoretical_cost * 1e12; // Hardware inefficiency
    Joule(practical_cost as u64)
}
```

---

## Execution Flow: The 10ms Tick

```
1. TIMER INTERRUPT fires
       │
       ▼
2. READ PHYSICS
   ├── Read MSR: Die Temperature
   ├── Read RAPL: Energy consumed
   └── Calculate: Thermal headroom
       │
       ▼
3. SET MARKET PRICE
   └── spot_price = f(temperature, power_budget)
       │
       ▼
4. CLEAR AUCTION
   ├── Sort bids (heap pop)
   ├── Accept bids >= spot_price
   └── Debit wallets (Vickrey: pay second price)
       │
       ▼
5. EXECUTE WINNERS
   ├── Resume winning VMs
   └── Keep losers frozen
       │
       ▼
6. CHECK INSOLVENCY
   └── If wallet < 0: trigger APOPTOSIS
```

---

## Project Layout

```
maxwell/
├── core/                    # Kernel Logic
│   ├── src/
│   │   ├── auction.rs       # Vickrey Engine
│   │   ├── thermal.rs       # Sensor Interface
│   │   ├── wallet.rs        # Crypto-Accounting
│   │   ├── landauer.rs      # Entropy Tax
│   │   └── verification.rs  # Proof of Inference
├── hypervisor/              # VM Management
│   ├── src/
│   │   ├── firecracker.rs   # Firecracker API client
│   │   ├── vsock.rs         # Inter-VM communication
│   │   └── cgroup.rs        # Resource isolation
├── daemon/                  # Main Process
│   ├── src/
│   │   └── main.rs          # PID 1 entry point
├── ebpf/                    # Instrumentation
│   ├── src/
│   │   ├── entropy.bpf.c    # Memory tracking
│   │   └── syscall.bpf.c    # Syscall audit
├── agents/                  # Example Agents
│   ├── scientist/           # "Good" agent
│   └── miner/               # "Bad" agent (for testing)
└── tui/                     # Terminal Dashboard
    └── src/
        └── main.rs          # ratatui interface
```