ruvector/crates/rvm/README.md

RVM — The Virtual Machine Built for the Agentic Age

Agents don't fit in VMs. They need something that understands how they think.

Part of the RuVector ecosystem. Uses RuVix kernel primitives and RVF package format. Designed for Cognitum Seed, Appliance, and future chip targets.

Traditional hypervisors were built for an era of static server workloads — long-running VMs with predictable resource needs. AI agents are different. They spawn in milliseconds, communicate in dense, shifting graphs, share context across trust boundaries, and die without warning. VMs are the wrong abstraction.

RVM replaces VMs with coherence domains — lightweight, graph-structured partitions whose isolation, scheduling, and memory placement are driven by how agents actually communicate. When two agents start talking more, RVM moves them closer. When trust drops, RVM splits them apart. Every mutation is proof-gated. Every action is witnessed. The system understands its own structure.

Agent swarm → [RVM Coherence Engine] → Optimal Placement → Witness Proof
                    ↑                                            │
                    └──── Agent Communication Graph ─────────────┘
                          (< 50µs adaptive re-partitioning)

No KVM. No Linux. No VMs. Bare-metal Rust. Built for agents.

Traditional VM:     VM₁  VM₂  VM₃  VM₄    (static, opaque boxes — agents don't fit)
                    ─────────────────────
RVM:                ┌─A──B─┐  ┌─C─┐  D    (dynamic, agent-driven domains)
                    │  ↔   │──│ ↔ │──↔    (edges = agent communication weight)
                    └──────┘  └───┘        (auto-split when trust or coupling changes)

What Agents Need vs What They Get

What Agents Need	VMs / Containers	RVM
Sub-millisecond spawn	Seconds to boot	< 10µs partition switch
Dense, shifting comms graph	Static NIC-to-NIC	Graph-weighted CommEdges, auto-rebalanced
Shared context with isolation	All or nothing	Capability-gated shared memory, proof-checked
Per-agent fault containment	Whole-VM crash	F1–F4 graduated rollback, no reboot needed
Auditable every action	External log bolted on	64-byte witness on every syscall, hash-chained
Hibernate and reconstruct	Kill and restart	Dormant tier → rebuilt from witness log
Run on 64KB MCUs	Needs gigabytes	Seed profile: 64KB–1MB, capability-enforced

---

Why RVM?

Dynamic Re-isolation and Self-Healing Boundaries. Because RVM uses graph-theoretic mincut algorithms, it can dynamically restructure its isolation boundaries to match how workloads actually communicate. If an agent in one partition begins communicating heavily with an agent in another, RVM automatically triggers a partition split and migrates the agent to optimise placement — no manual configuration. No existing hypervisor can split or merge live partitions along a graph-theoretic cut boundary.

Memory Time Travel and Deep Forensics. Traditional virtual memory permanently overwrites state or blindly swaps it to disk. RVM stores dormant memory as a checkpoint combined with a delta-compressed witness trail. Any historical state can be perfectly rebuilt on demand — days or weeks later — because every privileged action is recorded in a tamper-evident, hash-chained witness log. External forensic tools can reconstruct past states to answer precise questions such as "which task mutated this vector store between 14:00 and 14:05 on Tuesday?"

Targeted Fault Rollback Without Global Reboots. When the kernel detects a coherence violation or memory corruption it does not crash. Instead it finds the last known-good checkpoint, replays the witness log, explicitly skips the mutation that caused the failure, and resumes from a corrected state (DC-14, failure classes F1–F3).

Deterministic Multi-Tenant Edge Orchestration. Existing edge orchestrators rely on Linux-based VMs or containers, inheriting scheduling unpredictability and no guarantee of bounded latency with provable isolation. RVM enables scenarios such as an autonomous vehicle where safety-critical sensor-fusion agents (Reflex mode, < 10 µs switch) are strictly isolated from low-priority infotainment agents, or a smart factory floor running hard real-time PLC control loops safely alongside ML inference agents.

High-Assurance Security on Extreme Microcontrollers. Through its Seed hardware profile (ADR-138), RVM brings capability-enforced isolation, proof-gated execution, and witness attestation to deeply constrained IoT devices with as little as 64 KB of RAM. Delivering this level of zero-trust, auditable security on microcontroller-class hardware is a novel capability not provided by any existing embedded operating system.

---

Architecture

+----------------------------------------------------------+
|                       rvm-kernel                         |
|                                                          |
|  +-----------+  +-----------+  +------------+            |
|  | rvm-boot  |  | rvm-sched |  | rvm-memory |            |
|  +-----+-----+  +-----+-----+  +------+-----+            |
|        |              |               |                   |
|  +-----+--------------+---------------+------+            |
|  |               rvm-partition               |            |
|  +-----+---------+-----------+----------+----+            |
|        |         |           |          |                 |
|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |
|  | rvm-cap| |rvm-witness| |rvm-proof| |rvm-security|     |
|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |
|        |         |           |          |                 |
|  +-----+---------+-----------+----------+----+            |
|  |               rvm-types                   |            |
|  +-----+-------------------------------------+            |
|        |                                                  |
|  +-----+--+  +----------+  +-------------+               |
|  | rvm-hal|  | rvm-wasm |  |rvm-coherence|               |
|  +--------+  +----------+  +-------------+               |
+----------------------------------------------------------+

Layer 4: Persistent State
         witness log │ compressed dormant memory │ RVF checkpoints
         ─────────────────────────────────────────────────────────
Layer 3: Execution Adapters
         bare partition │ WASM partition │ service adapter
         ─────────────────────────────────────────────────────────
Layer 2: Coherence Engine (OPTIONAL — DC-1)
         graph state │ mincut │ pressure scoring │ migration
         ─────────────────────────────────────────────────────────
Layer 1: RVM Core (Rust, no_std)
         partitions │ capabilities │ scheduler │ witnesses
         ─────────────────────────────────────────────────────────
Layer 0: Machine Entry (assembly, <500 LoC)
         reset vector │ trap handlers │ context switch

First-Class Kernel Objects

Object	Purpose
Partition	Coherence domain container — unit of scheduling, isolation, and migration
Capability	Unforgeable authority token with 7 rights (READ, WRITE, GRANT, REVOKE, EXECUTE, PROVE, GRANT_ONCE)
Witness	64-byte hash-chained audit record emitted by every privileged action
MemoryRegion	Typed, tiered, owned memory (Hot/Warm/Dormant/Cold) with move semantics
CommEdge	Inter-partition communication channel — weighted edge in the coherence graph
DeviceLease	Time-bounded, revocable hardware device access
CoherenceScore	Graph-derived locality and coupling metric
CutPressure	Isolation signal — high pressure triggers migration or split
RecoveryCheckpoint	State snapshot for rollback and reconstruction

---

Crate Structure

Crate	Purpose
rvm-types	Foundation types: addresses, IDs, capabilities, witness records, coherence scores
rvm-hal	Platform-agnostic hardware abstraction traits (MMU, timer, interrupts)
rvm-cap	Capability-based access control with derivation trees and three-tier proof
rvm-witness	Append-only witness trail with hash-chain integrity
rvm-proof	Proof-gated state transitions (P1/P2/P3 tiers), TEE pipeline, cryptographic signers (Ed25519, HMAC-SHA256)
rvm-partition	Partition lifecycle, split/merge, capability tables, communication edges
rvm-sched	Coherence-weighted 2-signal scheduler (deadline urgency + cut pressure)
rvm-memory	Guest physical address space management with tiered placement
rvm-coherence	Unified coherence engine: graph, mincut, scoring, pressure, adaptive, pluggable backends, edge decay
rvm-boot	Deterministic 7-phase boot sequence with witness gating
rvm-wasm	Optional WebAssembly guest runtime
rvm-security	Unified security gate: capability check + proof verification + witness log
rvm-kernel	Full integration: coherence engine, IPC→graph feeding, scheduler, split/merge, security gates, tier management

Dependency Graph

rvm-types (foundation, no deps)
    ├── rvm-hal
    ├── rvm-cap
    ├── rvm-witness
    ├── rvm-proof ← rvm-cap + rvm-witness
    ├── rvm-partition ← rvm-hal + rvm-cap + rvm-witness
    ├── rvm-sched ← rvm-partition + rvm-witness
    ├── rvm-memory ← rvm-hal + rvm-partition + rvm-witness
    ├── rvm-coherence ← rvm-partition + rvm-sched [OPTIONAL]
    ├── rvm-boot ← rvm-hal + rvm-partition + rvm-witness + rvm-sched + rvm-memory
    ├── rvm-wasm ← rvm-partition + rvm-cap + rvm-witness [OPTIONAL]
    ├── rvm-security ← rvm-cap + rvm-proof + rvm-witness
    └── rvm-kernel ← ALL

---

Build

# Check (no_std by default)
cargo check

# Run all 648 tests
cargo test --workspace --lib

# Run 21 criterion benchmarks
cargo bench

# Build with std support
cargo check --features std

# Cross-compile for AArch64 bare-metal
rustup target add aarch64-unknown-none
make build    # or: cargo build --target aarch64-unknown-none -p rvm-kernel --release

# Boot on QEMU (requires qemu-system-aarch64)
make run      # boots at 0x4000_0000, PL011 UART output

---

Design Constraints (ADR-132 through ADR-140)

ID	Constraint	Status
DC-1	Coherence engine is optional; system degrades gracefully	Implemented — adaptive engine, static fallback
DC-2	MinCut budget: 50 µs per epoch	Implemented — Stoer-Wagner with iteration budget, ~331ns measured
DC-3	Capabilities are unforgeable, monotonically attenuated	Implemented — constant-time P1, 4096-nonce ring
DC-4	2-signal priority: deadline_urgency + cut_pressure_boost	Implemented
DC-5	Three systems cleanly separated (kernel + coherence + agents)	Enforced — feature-gated
DC-6	Degraded mode when coherence unavailable	Implemented — enter/exit with witnesses, scheduler zeroes CutPressure
DC-7	Migration timeout enforcement (100 ms)	Implemented — MigrationTracker with auto-abort
DC-8	Capabilities follow objects during partition split	Implemented — scored region assignment
DC-9	Coherence score range [0.0, 1.0] as fixed-point	Implemented — u16 basis points
DC-10	Epoch-based witness batching (no per-switch records)	Implemented
DC-11	Merge requires coherence above threshold + adjacency + resources	Implemented — 3-check validation
DC-12	Max 256 physical VMIDs, multiplexed for >256 partitions	Implemented
DC-13	WASM is optional; native bare partitions are first class	Enforced
DC-14	Failure classes: transient, recoverable, permanent, catastrophic	Implemented — F1-F4 with escalation
DC-15	All types are no_std, forbid(unsafe_code), deny(missing_docs)	Enforced

---

Benchmarks

Operation	ADR Target	Measured	Ratio
Witness emit (v1, legacy verify-only format)	< 500 ns	~17 ns	29x faster
Witness v2 append (96 B record, keyed BLAKE3 chain MAC)	< 1 µs	~112 ns	8x faster
Witness v2 segment seal (256 records, Merkle root + sign)	—	~61 µs	one signature per segment, off the per-record path
P1 capability verify	< 1 µs	< 1 ns	>1000x faster
P2 proof pipeline	< 100 µs	~996 ns	100x faster
Partition switch	< 10 µs	not validated	hardware hot path unimplemented (HARDWARE_SWITCH_IMPLEMENTED == false); host benches measure only run-queue selection and register-file copy, which are lower bounds
MinCut 16-node	< 50 µs	~331 ns	150x faster
Coherence score (16-node)	budgeted	~84 ns	—
Buddy alloc/free cycle	fast	~184 ns	—
FNV-1a hash (64 bytes)	fast	~28 ns	—
Security gate P1	fast	~17 ns	—
Witness chain verify (64 records)	fast	~892 ns	—

Run cargo bench for full criterion results with HTML reports.

Implementation Status

Crate	Tests	Key Features
rvm-types	~40 types	64-byte WitnessRecord (compile-time asserted), ~40 ActionKind variants, 34 error variants
rvm-hal	16	AArch64 EL2: stage-2 page tables, PL011 UART, GICv2, ARM generic timer
rvm-cap	40	Constant-time P1, nonce ring (4096 + watermark), P3 derivation chain verification, epoch revocation
rvm-witness	29	SHA-256 hash chain (FNV-1a fallback), HMAC-SHA256 signing, 16MB ring buffer, StrictSigner, RLE-compressed replay
rvm-proof	45	Proof engine, context builder, constant-time P2 (all 6 rules), P3 deep verification (SHA-256 + Merkle + WitnessSigner), TEE pipeline, Ed25519/HMAC-SHA256/DualHmac signers
rvm-partition	86	Lifecycle state machine, IPC message queues, device leases, scored split/merge, remove()
rvm-sched	49	2-signal priority, SMP coordinator, VMID-aware switch, SwitchContext::init(), degraded fallback
rvm-memory	110	Buddy allocator with coalescing, 4-tier management, LZ4-style RLE compression, reconstruction
rvm-coherence	59	Unified coherence engine, pluggable MinCut/Coherence backends, edge decay, bridge to ruvector
rvm-boot	26	7-phase measured boot, attestation digest, HAL init, entry point
rvm-wasm	33	7-state agent lifecycle, HostContext trait, section parser (13 section types), migration
rvm-security	45	Unified security gate (P1/P2/P3), SignedSecurityGate with per-link signature verification, input validation, attestation chain, DMA budget
rvm-kernel	62	Full integration: IPC→coherence, scheduler, split/merge, security gates, degraded mode, device leases, tier mgmt
Integration	48	17 e2e scenarios: agent lifecycle, split pressure, memory tiers, cap chain, boot timing
Benchmarks	21	Criterion benchmarks for all performance-critical paths
Total	648	0 failures, 0 clippy warnings

Security Audit Results

11 findings from formal security review, 8 fixed in code:

Severity	Finding	Status
Critical	P1 timing side channel	Fixed — constant-time bitmask
High	Revocation didn't invalidate descendants	Fixed — iterative subtree sync
High	Cross-partition host memory overlap	Fixed — global overlap check
Medium	Generation counter wrap aliasing	Fixed — skip gen 0
Medium	next_id overflow	Fixed — checked_add
Medium	Recursive revoke stack overflow	Fixed — iterative stack
Medium	Incomplete merge preconditions	Fixed — full validation
Low	Terminated agent slots never freed	Fixed — set None
Medium	Nonce ring too small (64)	Fixed — upgraded to 4096 + watermark
Medium	TOCTOU in quota check	Fixed — atomic check_and_record
Low	NullSigner always-true	Fixed — StrictSigner + deprecation

---

🔍 RVM vs State of the Art (12 differences)

	RVM	KVM/Firecracker	seL4	Theseus OS
Primary abstraction	Coherence domains (graph-partitioned)	Virtual machines	Processes + capabilities	Cells (intralingual)
Isolation driver	Dynamic mincut + cut pressure	Hardware EPT/NPT	Formal verification + caps	Rust type system
Scheduling signal	Structural coherence (graph metrics)	CPU time / fairness	Priority / round-robin	Cooperative
Memory model	4-tier reconstructable (Hot/Warm/Dormant/Cold)	Demand paging	Untyped memory + retype	Single address space
Audit trail	Witness-native (64B hash-chained records)	External logging	Not built-in	Not built-in
Mutation control	Proof-gated (3-layer: P1/P2/P3)	Unix permissions	Capability tokens	Rust ownership
Partition operations	Live split/merge along graph cuts	Not supported	Not supported	Not supported
Linux dependency	None — bare-metal	Yes (KVM is a kernel module)	None	None
Language	95-99% Rust, <500 LoC assembly	C	C + Isabelle/HOL proofs	Rust
Target	Edge, IoT, agents	Cloud servers	Safety-critical	Research
Boot time	< 250ms to first witness	~125ms (Firecracker)	Varies	N/A
Partition switch	< 10µs	~2-5µs (VM exit)	~0.5-1µs (IPC)	N/A (no isolation)

✨ 6 Novel Capabilities (No Prior Art)

1. Kernel-Level Graph Control Loop

No existing OS uses spectral graph coherence metrics as a scheduling signal. RVM's coherence engine runs mincut algorithms in the kernel's scheduling loop — graph structure directly drives where computation runs, when partitions split, and which memory stays resident.

2. Reconstructable Memory ("Memory Time Travel")

RVM explicitly rejects demand paging. Dormant memory is stored as witness checkpoint + delta compression, not raw bytes. The system can deterministically reconstruct any historical state from the witness log.

3. Proof-Gated Infrastructure

Every state mutation requires a valid proof token verified through a three-tier system: P1 capability (<1µs), P2 policy (<100µs), P3 deep derivation chain verification (walks tree to root, validates ancestor integrity + epoch monotonicity).

4. Witness-Native OS

Every privileged action emits a fixed 64-byte, SHA-256 hash-chained record with HMAC-SHA256 signatures. Tamper-evident by construction. Full deterministic replay from any checkpoint.

5. Live Partition Split/Merge

Partitions split along graph-theoretic cut boundaries and merge when coherence rises. Capabilities follow ownership (DC-8), regions use weighted scoring (DC-9), merges require 7 preconditions (DC-11).

6. Edge Security on 64KB RAM

Capability-based isolation, proof-gated execution, and witness attestation on microcontroller-class hardware (Cortex-M/R, 64KB RAM).

🎯 Success Criteria (v1)

#	Criterion	Target
1	All 13 crates compile with #![no_std] and #![forbid(unsafe_code)]	Enforced
2	Cold boot to first witness	< 250ms on Appliance hardware
3	Hot partition switch	< 10 microseconds
4	Witness record is exactly 64 bytes, cache-line aligned	Compile-time asserted
5	Capability derivation depth bounded at 8 levels	Enforced
6	EMA coherence filter operates without floating-point	Implemented
7	Boot sequence is deterministic and witness-gated	Implemented
8	Remote memory traffic reduction ≥ 20% vs naive placement	Target
9	Fault recovery without global reboot (F1–F3)	Target

🏗️ Implementation Phases

Phase 1: Foundation (M0-M1) — "Can it boot and isolate?"

• M0: Bare-metal Rust boot on QEMU AArch64 virt. Reset → EL2 → serial → MMU → first witness.
• M1: Partition + capability model. Create, destroy, switch. Simple deadline scheduler.

Phase 2: Differentiation (M2-M3) — "Can it prove and witness?"

• M2: Witness logging (64-byte chained records) + P1/P2 proof verifier.
• M3: 2-signal scheduler (deadline + cut_pressure). Flow + Reflex modes. Zero-copy IPC.

Phase 3: Innovation (M4-M5) — "Can it think about coherence?"

• M4: Dynamic mincut integration (DC-2 budget). Live coherence graph. Migration triggers.
• M5: Memory tier management. Reconstruction from dormant state.

Phase 4: Expansion (M6-M7) — "Can agents run on it?"

• M6: WASM agent runtime adapter. Agent lifecycle.
• M7: Seed/Appliance hardware bring-up. All success criteria.

🔐 Security Model

Capability-Based Authority. All access controlled through unforgeable kernel-resident tokens. No ambient authority. Seven rights with monotonic attenuation.

Proof-Gated Mutation. No memory remap, device mapping, migration, or partition merge without a valid proof token. Three tiers with strict latency budgets.

Witness-Native Audit. 64-byte records for every mutating operation. Hash-chained for tamper evidence. Deterministic replay from checkpoint + witness log.

Failure Classification. F1 (agent restart) → F2 (partition reconstruct) → F3 (memory rollback) → F4 (kernel reboot). Each escalation witnessed.

🖥️ Target Platforms

Platform	Profile	RAM	Coherence Engine	WASM
Seed	Tiny, persistent, event-driven	64KB–1MB	No (DC-1)	Optional
Appliance	Edge hub, deterministic orchestration	1–32GB	Yes (full)	Yes
Chip	Future Cognitum silicon	Tile-local	Hardware-assisted	Yes

📚 ADR References

ADR	Topic
ADR-132	RVM top-level architecture and 15 design constraints
ADR-133	Partition object model and split/merge semantics
ADR-134	Witness schema and log format (64-byte records)
ADR-135	Three-tier proof system (P1/P2/P3)
ADR-136	Memory hierarchy and reconstruction
ADR-137	Bare-metal boot sequence
ADR-138	Seed hardware bring-up
ADR-139	Appliance deployment model
ADR-140	Agent runtime adapter
ADR-141	Coherence engine kernel integration and runtime pipeline
ADR-142	TEE-backed cryptographic verification (SHA-256, Ed25519, HMAC-SHA256, TEE pipeline)

🔧 Development

Prerequisites

• Rust 1.77+ with aarch64-unknown-none target
• QEMU 8.0+ (for AArch64 virt machine emulation)

rustup target add aarch64-unknown-none
brew install qemu  # macOS

Project Conventions

• #![no_std] everywhere — the kernel runs on bare metal
• #![forbid(unsafe_code)] where possible; unsafe blocks audited and commented
• #![deny(missing_docs)] — every public API documented
• Move semantics for memory ownership (OwnedRegion<P> is non-copyable)
• Const generics for fixed-size structures (no heap allocation in kernel paths)
• Every state mutation emits a witness record

---

RuVector Integration

Crate	Role in RVM
ruvector-mincut	Partition placement and isolation decisions
ruvector-sparsifier	Compressed shadow graph for Laplacian operations
ruvector-solver	Effective resistance → coherence scores
ruvector-coherence	Spectral coherence tracking
ruvix-*	Kernel primitives (Task, Capability, Region, Queue, Timer, Proof)
rvf	Package format for boot images, checkpoints, and cold storage

---

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

---

_{EPIC · Research Gist · pi.ruv.io Brain}