{"id":48305792,"url":"https://github.com/ruvnet/rvm","last_synced_at":"2026-04-11T06:01:11.561Z","repository":{"id":349177291,"uuid":"1201348589","full_name":"ruvnet/rvm","owner":"ruvnet","description":"RVM — The Virtual Machine Built for the Agentic Age, in Rust.","archived":false,"fork":false,"pushed_at":"2026-04-06T01:51:17.000Z","size":991,"stargazers_count":78,"open_issues_count":0,"forks_count":13,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T03:03:05.594Z","etag":null,"topics":["bare-metal","capability","coherence","edge-computing","hypervisor","microhypervisor","no-std","rust","rvm","witness"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruvnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T14:59:42.000Z","updated_at":"2026-04-07T12:20:09.000Z","dependencies_parsed_at":"2026-04-08T03:01:31.682Z","dependency_job_id":null,"html_url":"https://github.com/ruvnet/rvm","commit_stats":null,"previous_names":["ruvnet/rvm"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ruvnet/rvm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Frvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Frvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Frvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Frvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruvnet","download_url":"https://codeload.github.com/ruvnet/rvm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Frvm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","capability","coherence","edge-computing","hypervisor","microhypervisor","no-std","rust","rvm","witness"],"created_at":"2026-04-05T00:02:10.876Z","updated_at":"2026-04-09T04:00:57.741Z","avatar_url":"https://github.com/ruvnet.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RVM — The Virtual Machine Built for the Agentic Age\n\n[![Rust](https://img.shields.io/badge/Rust-1.77+-orange.svg)](https://www.rust-lang.org)\n[![no_std](https://img.shields.io/badge/no__std-compatible-green.svg)](https://doc.rust-lang.org/reference/names/preludes.html)\n[![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)\n[![ADR](https://img.shields.io/badge/ADRs-132--144-purple.svg)](docs/adr/)\n[![Tests](https://img.shields.io/badge/tests-945_passing-brightgreen.svg)](https://github.com/ruvnet/rvm)\n[![GPU](https://img.shields.io/badge/GPU-CUDA%20%7C%20Metal%20%7C%20WebGPU-blue.svg)](docs/adr/ADR-144-gpu-compute-support.md)\n[![Nightly](https://img.shields.io/badge/Nightly-Verified%20Releases-brightgreen.svg)](https://github.com/ruvnet/rvm/releases)\n[![EPIC](https://img.shields.io/badge/EPIC-ruvnet%2FRuVector%23328-brightgreen.svg)](https://github.com/ruvnet/RuVector/issues/328)\n\n### **Agents don't fit in VMs. They need something that understands how they think.**\n\n\u003e **945 tests. 14 crates. 6 GPU backends. Zero regressions.** RVM automatically detects new [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) releases, runs full verification with AI-powered discovery analysis, and publishes verified nightly builds. See [Releases](https://github.com/ruvnet/rvm/releases) | [User Guide](userguide/) | [pi.ruv.io](https://pi.ruv.io)\n\n\u003e Part of the [RuVector](https://github.com/ruvnet/RuVector) ecosystem. Uses [RuVix](../../crates/ruvix/) kernel primitives and [RVF](../../crates/rvf/) package format. Designed for [Cognitum](https://cognitum.one) Seed, Appliance, and future chip targets.\n\nTraditional hypervisors were built for an era of static server workloads —\nlong-running VMs with predictable resource needs. AI agents are different.\nThey spawn in milliseconds, communicate in dense, shifting graphs, share\ncontext across trust boundaries, and die without warning. VMs are the wrong\nabstraction.\n\nRVM replaces VMs with **coherence domains** — lightweight, graph-structured\npartitions whose isolation, scheduling, and memory placement are driven by how\nagents actually communicate. When two agents start talking more, RVM moves\nthem closer. When trust drops, RVM splits them apart. Every mutation is\nproof-gated. Every action is witnessed. The system *understands* its own\nstructure.\n\n```\nAgent swarm → [RVM Coherence Engine] → Optimal Placement → Witness Proof\n                    ↑                                            │\n                    └──── Agent Communication Graph ─────────────┘\n                          (\u003c 50µs adaptive re-partitioning)\n```\n\n**No KVM. No Linux. No VMs. Bare-metal Rust. Built for agents.**\n\n```\nTraditional VM:     VM₁  VM₂  VM₃  VM₄    (static, opaque boxes — agents don't fit)\n                    ─────────────────────\nRVM:                ┌─A──B─┐  ┌─C─┐  D    (dynamic, agent-driven domains)\n                    │  ↔   │──│ ↔ │──↔    (edges = agent communication weight)\n                    └──────┘  └───┘        (auto-split when trust or coupling changes)\n```\n\n### What Agents Need vs What They Get\n\n| What Agents Need | VMs / Containers | RVM |\n|-----------------|-----------------|-----|\n| Sub-millisecond spawn | Seconds to boot | \u003c 10µs partition switch |\n| Dense, shifting comms graph | Static NIC-to-NIC | Graph-weighted CommEdges, auto-rebalanced |\n| Shared context with isolation | All or nothing | Capability-gated shared memory, proof-checked |\n| Per-agent fault containment | Whole-VM crash | F1–F4 graduated rollback, no reboot needed |\n| Auditable every action | External log bolted on | 64-byte witness on every syscall, hash-chained |\n| Hibernate and reconstruct | Kill and restart | Dormant tier → rebuilt from witness log |\n| Run on 64KB MCUs | Needs gigabytes | Seed profile: 64KB–1MB, capability-enforced |\n\n---\n\n## Why RVM?\n\n**Dynamic Re-isolation and Self-Healing Boundaries.** Because RVM uses\ngraph-theoretic mincut algorithms, it can dynamically restructure its isolation\nboundaries to match how workloads actually communicate. If an agent in one\npartition begins communicating heavily with an agent in another, RVM\nautomatically triggers a partition split and migrates the agent to optimise\nplacement — no manual configuration. No existing hypervisor can split or merge\nlive partitions along a graph-theoretic cut boundary.\n\n**Memory Time Travel and Deep Forensics.** Traditional virtual memory\npermanently overwrites state or blindly swaps it to disk. RVM stores dormant\nmemory as a checkpoint combined with a delta-compressed witness trail. Any\nhistorical state can be perfectly rebuilt on demand — days or weeks later —\nbecause every privileged action is recorded in a tamper-evident, hash-chained\nwitness log. External forensic tools can reconstruct past states to answer\nprecise questions such as \"which task mutated this vector store between 14:00\nand 14:05 on Tuesday?\"\n\n**Targeted Fault Rollback Without Global Reboots.** When the kernel detects a\ncoherence violation or memory corruption it does not crash. Instead it finds\nthe last known-good checkpoint, replays the witness log, explicitly skips the\nmutation that caused the failure, and resumes from a corrected state (DC-14,\nfailure classes F1–F3).\n\n**Deterministic Multi-Tenant Edge Orchestration.** Existing edge orchestrators\nrely on Linux-based VMs or containers, inheriting scheduling unpredictability\nand no guarantee of bounded latency with provable isolation. RVM enables\nscenarios such as an autonomous vehicle where safety-critical sensor-fusion\nagents (Reflex mode, \u003c 10 µs switch) are strictly isolated from low-priority\ninfotainment agents, or a smart factory floor running hard real-time PLC\ncontrol loops safely alongside ML inference agents.\n\n**High-Assurance Security on Extreme Microcontrollers.** Through its Seed\nhardware profile (ADR-138), RVM brings capability-enforced isolation,\nproof-gated execution, and witness attestation to deeply constrained IoT\ndevices with as little as 64 KB of RAM. Delivering this level of zero-trust,\nauditable security on microcontroller-class hardware is a novel capability not\nprovided by any existing embedded operating system.\n\n---\n\n## Architecture\n\n```\n+----------------------------------------------------------+\n|                       rvm-kernel                         |\n|                                                          |\n|  +-----------+  +-----------+  +------------+            |\n|  | rvm-boot  |  | rvm-sched |  | rvm-memory |            |\n|  +-----+-----+  +-----+-----+  +------+-----+            |\n|        |              |               |                   |\n|  +-----+--------------+---------------+------+            |\n|  |               rvm-partition               |            |\n|  +-----+---------+-----------+----------+----+            |\n|        |         |           |          |                 |\n|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |\n|  | rvm-cap| |rvm-witness| |rvm-proof| |rvm-security|     |\n|  +-----+--+ +---+------+ +--+-----+ +--+--------+        |\n|        |         |           |          |                 |\n|  +-----+---------+-----------+----------+----+            |\n|  |               rvm-types                   |            |\n|  +-----+-------------------------------------+            |\n|        |                                                  |\n|  +-----+--+  +----------+  +-------------+               |\n|  | rvm-hal|  | rvm-wasm |  |rvm-coherence|               |\n|  +--------+  +----------+  +-------------+               |\n+----------------------------------------------------------+\n```\n\n```\nLayer 4: Persistent State\n         witness log │ compressed dormant memory │ RVF checkpoints\n         ─────────────────────────────────────────────────────────\nLayer 3: Execution Adapters\n         bare partition │ WASM partition │ service adapter\n         ─────────────────────────────────────────────────────────\nLayer 2: Coherence Engine (OPTIONAL — DC-1)\n         graph state │ mincut │ pressure scoring │ migration\n         ─────────────────────────────────────────────────────────\nLayer 1: RVM Core (Rust, no_std)\n         partitions │ capabilities │ scheduler │ witnesses\n         ─────────────────────────────────────────────────────────\nLayer 0: Machine Entry (assembly, \u003c500 LoC)\n         reset vector │ trap handlers │ context switch\n```\n\n### First-Class Kernel Objects\n\n| Object | Purpose |\n|--------|---------|\n| **Partition** | Coherence domain container — unit of scheduling, isolation, and migration |\n| **Capability** | Unforgeable authority token with 7 rights (READ, WRITE, GRANT, REVOKE, EXECUTE, PROVE, GRANT_ONCE) |\n| **Witness** | 64-byte hash-chained audit record emitted by every privileged action |\n| **MemoryRegion** | Typed, tiered, owned memory (Hot/Warm/Dormant/Cold) with move semantics |\n| **CommEdge** | Inter-partition communication channel — weighted edge in the coherence graph |\n| **DeviceLease** | Time-bounded, revocable hardware device access |\n| **CoherenceScore** | Graph-derived locality and coupling metric |\n| **CutPressure** | Isolation signal — high pressure triggers migration or split |\n| **RecoveryCheckpoint** | State snapshot for rollback and reconstruction |\n\n---\n\n## Crate Structure\n\n| Crate | Purpose |\n|-------|---------|\n| `rvm-types` | Foundation types: addresses, IDs, capabilities, witness records, coherence scores |\n| `rvm-hal` | Platform-agnostic hardware abstraction traits (MMU, timer, interrupts) |\n| `rvm-cap` | Capability-based access control with derivation trees and three-tier proof |\n| `rvm-witness` | Append-only witness trail with hash-chain integrity |\n| `rvm-proof` | Proof-gated state transitions (P1/P2/P3 tiers), TEE pipeline, cryptographic signers (Ed25519, HMAC-SHA256) |\n| `rvm-partition` | Partition lifecycle, split/merge, capability tables, communication edges |\n| `rvm-sched` | Coherence-weighted 2-signal scheduler (deadline urgency + cut pressure) |\n| `rvm-memory` | Guest physical address space management with tiered placement |\n| `rvm-coherence` | Unified coherence engine: graph, mincut, scoring, pressure, adaptive, pluggable backends, edge decay |\n| `rvm-boot` | Deterministic 7-phase boot sequence with witness gating |\n| `rvm-wasm` | Optional WebAssembly guest runtime |\n| `rvm-security` | Unified security gate: capability check + proof verification + witness log |\n| `rvm-kernel` | Full integration: coherence engine, IPC→graph feeding, scheduler, split/merge, security gates, tier management |\n| `rvm-gpu` | GPU compute subsystem: device, context, kernel, buffer, queue, budget (optional, feature-gated) |\n\n### Dependency Graph\n\n```\nrvm-types (foundation, no deps)\n    ├── rvm-hal\n    ├── rvm-cap\n    ├── rvm-witness\n    ├── rvm-proof ← rvm-cap + rvm-witness\n    ├── rvm-partition ← rvm-hal + rvm-cap + rvm-witness\n    ├── rvm-sched ← rvm-partition + rvm-witness\n    ├── rvm-memory ← rvm-hal + rvm-partition + rvm-witness\n    ├── rvm-coherence ← rvm-partition + rvm-sched [OPTIONAL]\n    ├── rvm-boot ← rvm-hal + rvm-partition + rvm-witness + rvm-sched + rvm-memory\n    ├── rvm-wasm ← rvm-partition + rvm-cap + rvm-witness [OPTIONAL]\n    ├── rvm-security ← rvm-cap + rvm-proof + rvm-witness\n    └── rvm-kernel ← ALL\n```\n\n---\n\n## Build\n\n```bash\n# Check (no_std by default)\ncargo check\n\n# Run all 945 tests\ncargo test --workspace --lib\n\n# Run 21 criterion benchmarks\ncargo bench\n\n# Build with std support\ncargo check --features std\n\n# Cross-compile for AArch64 bare-metal\nrustup target add aarch64-unknown-none\nmake build    # or: cargo build --target aarch64-unknown-none -p rvm-kernel --release\n\n# Boot on QEMU (requires qemu-system-aarch64)\nmake run      # boots at 0x4000_0000, PL011 UART output\n```\n\n---\n\n## Design Constraints (ADR-132 through ADR-140)\n\n| ID | Constraint | Status |\n|----|-----------|--------|\n| DC-1 | Coherence engine is optional; system degrades gracefully | **Implemented** — adaptive engine, static fallback |\n| DC-2 | MinCut budget: 50 µs per epoch | **Implemented** — Stoer-Wagner with iteration budget, ~331ns measured |\n| DC-3 | Capabilities are unforgeable, monotonically attenuated | **Implemented** — constant-time P1, 4096-nonce ring |\n| DC-4 | 2-signal priority: `deadline_urgency + cut_pressure_boost` | **Implemented** |\n| DC-5 | Three systems cleanly separated (kernel + coherence + agents) | **Enforced** — feature-gated |\n| DC-6 | Degraded mode when coherence unavailable | **Implemented** — enter/exit with witnesses, scheduler zeroes CutPressure |\n| DC-7 | Migration timeout enforcement (100 ms) | **Implemented** — MigrationTracker with auto-abort |\n| DC-8 | Capabilities follow objects during partition split | **Implemented** — scored region assignment |\n| DC-9 | Coherence score range [0.0, 1.0] as fixed-point | **Implemented** — u16 basis points |\n| DC-10 | Epoch-based witness batching (no per-switch records) | **Implemented** |\n| DC-11 | Merge requires coherence above threshold + adjacency + resources | **Implemented** — 3-check validation |\n| DC-12 | Max 256 physical VMIDs, multiplexed for \u003e256 partitions | **Implemented** |\n| DC-13 | WASM is optional; native bare partitions are first class | **Enforced** |\n| DC-14 | Failure classes: transient, recoverable, permanent, catastrophic | **Implemented** — F1-F4 with escalation |\n| DC-15 | All types are `no_std`, `forbid(unsafe_code)`, `deny(missing_docs)` | **Enforced** |\n\n---\n\n## Benchmarks (All ADR Targets Exceeded)\n\n| Operation | ADR Target | Measured | Ratio |\n|-----------|-----------|---------|-------|\n| Witness emit | \u003c 500 ns | **~17 ns** | 29x faster |\n| P1 capability verify | \u003c 1 µs | **\u003c 1 ns** | \u003e1000x faster |\n| P2 proof pipeline | \u003c 100 µs | **~996 ns** | 100x faster |\n| Partition switch (stub) | \u003c 10 µs | **~6 ns** | 1600x faster |\n| MinCut 16-node | \u003c 50 µs | **~331 ns** | 150x faster |\n| Coherence score (16-node) | budgeted | **~84 ns** | — |\n| Buddy alloc/free cycle | fast | **~184 ns** | — |\n| FNV-1a hash (64 bytes) | fast | **~28 ns** | — |\n| Security gate P1 | fast | **~17 ns** | — |\n| Witness chain verify (64 records) | fast | **~892 ns** | — |\n| GPU context create | \u003c 20 ns | **~2.2 ns** | 9x faster |\n| GPU launch config validate | \u003c 10 ns | **~0.26 ns** | 38x faster |\n| GPU queue enqueue | \u003c 30 ns | **~0.26 ns** | 115x faster |\n| GPU budget reset | \u003c 10 ns | **~1.0 ns** | 10x faster |\n\nRun `cargo bench` for full criterion results with HTML reports.\n\n## Implementation Status\n\n| Crate | Tests | Key Features |\n|-------|-------|-------------|\n| `rvm-types` | ~40 types | 64-byte `WitnessRecord` (compile-time asserted), ~40 `ActionKind` variants, 34 error variants |\n| `rvm-hal` | 16 | AArch64 EL2: stage-2 page tables, PL011 UART, GICv2, ARM generic timer |\n| `rvm-cap` | 40 | Constant-time P1, nonce ring (4096 + watermark), P3 derivation chain verification, epoch revocation |\n| `rvm-witness` | 29 | SHA-256 hash chain (FNV-1a fallback), HMAC-SHA256 signing, 16MB ring buffer, `StrictSigner`, RLE-compressed replay |\n| `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 |\n| `rvm-partition` | 86 | Lifecycle state machine, IPC message queues, device leases, scored split/merge, `remove()` |\n| `rvm-sched` | 49 | 2-signal priority, SMP coordinator, VMID-aware switch, `SwitchContext::init()`, degraded fallback |\n| `rvm-memory` | 110 | Buddy allocator with coalescing, 4-tier management, LZ4-style RLE compression, reconstruction |\n| `rvm-coherence` | 59 | Unified coherence engine, pluggable MinCut/Coherence backends, edge decay, bridge to ruvector |\n| `rvm-boot` | 26 | 7-phase measured boot, attestation digest, HAL init, entry point |\n| `rvm-wasm` | 33 | 7-state agent lifecycle, `HostContext` trait, section parser (13 section types), migration |\n| `rvm-security` | 45 | Unified security gate (P1/P2/P3), `SignedSecurityGate` with per-link signature verification, input validation, attestation chain, DMA budget |\n| `rvm-kernel` | 62 | Full integration: IPC→coherence, scheduler, split/merge, security gates, degraded mode, device leases, tier mgmt |\n| `rvm-gpu` | 65 | Device/context/kernel/buffer/queue management, 4-dimensional budget, coherence acceleration configs |\n| **Integration** | 48 | 17 e2e scenarios: agent lifecycle, split pressure, memory tiers, cap chain, boot timing |\n| **Benchmarks** | 21 | Criterion benchmarks for all performance-critical paths |\n| **Total** | **945** | **0 failures, 0 clippy warnings** |\n\n### Security Audit Results\n\n11 findings from formal security review, 8 fixed in code:\n\n| Severity | Finding | Status |\n|----------|---------|--------|\n| Critical | P1 timing side channel | **Fixed** — constant-time bitmask |\n| High | Revocation didn't invalidate descendants | **Fixed** — iterative subtree sync |\n| High | Cross-partition host memory overlap | **Fixed** — global overlap check |\n| Medium | Generation counter wrap aliasing | **Fixed** — skip gen 0 |\n| Medium | next_id overflow | **Fixed** — checked_add |\n| Medium | Recursive revoke stack overflow | **Fixed** — iterative stack |\n| Medium | Incomplete merge preconditions | **Fixed** — full validation |\n| Low | Terminated agent slots never freed | **Fixed** — set None |\n| Medium | Nonce ring too small (64) | **Fixed** — upgraded to 4096 + watermark |\n| Medium | TOCTOU in quota check | **Fixed** — atomic check_and_record |\n| Low | NullSigner always-true | **Fixed** — StrictSigner + deprecation |\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔍 RVM vs State of the Art (12 differences)\u003c/b\u003e\u003c/summary\u003e\n\n| | RVM | KVM/Firecracker | seL4 | Theseus OS |\n|---|---|---|---|---|\n| **Primary abstraction** | Coherence domains (graph-partitioned) | Virtual machines | Processes + capabilities | Cells (intralingual) |\n| **Isolation driver** | Dynamic mincut + cut pressure | Hardware EPT/NPT | Formal verification + caps | Rust type system |\n| **Scheduling signal** | Structural coherence (graph metrics) | CPU time / fairness | Priority / round-robin | Cooperative |\n| **Memory model** | 4-tier reconstructable (Hot/Warm/Dormant/Cold) | Demand paging | Untyped memory + retype | Single address space |\n| **Audit trail** | Witness-native (64B hash-chained records) | External logging | Not built-in | Not built-in |\n| **Mutation control** | Proof-gated (3-layer: P1/P2/P3) | Unix permissions | Capability tokens | Rust ownership |\n| **Partition operations** | Live split/merge along graph cuts | Not supported | Not supported | Not supported |\n| **Linux dependency** | None — bare-metal | Yes (KVM is a kernel module) | None | None |\n| **Language** | 95-99% Rust, \u003c500 LoC assembly | C | C + Isabelle/HOL proofs | Rust |\n| **Target** | Edge, IoT, agents | Cloud servers | Safety-critical | Research |\n| **Boot time** | \u003c 250ms to first witness | ~125ms (Firecracker) | Varies | N/A |\n| **Partition switch** | \u003c 10µs | ~2-5µs (VM exit) | ~0.5-1µs (IPC) | N/A (no isolation) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e✨ 6 Novel Capabilities (No Prior Art)\u003c/b\u003e\u003c/summary\u003e\n\n### 1. Kernel-Level Graph Control Loop\nNo 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.\n\n### 2. Reconstructable Memory (\"Memory Time Travel\")\nRVM 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.\n\n### 3. Proof-Gated Infrastructure\nEvery state mutation requires a valid proof token verified through a three-tier system: P1 capability (\u003c1µs), P2 policy (\u003c100µs), P3 deep derivation chain verification (walks tree to root, validates ancestor integrity + epoch monotonicity).\n\n### 4. Witness-Native OS\nEvery 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.\n\n### 5. Live Partition Split/Merge\nPartitions 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).\n\n### 6. Edge Security on 64KB RAM\nCapability-based isolation, proof-gated execution, and witness attestation on microcontroller-class hardware (Cortex-M/R, 64KB RAM).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🎯 Success Criteria (v1)\u003c/b\u003e\u003c/summary\u003e\n\n| # | Criterion | Target |\n|---|-----------|--------|\n| 1 | All 13 crates compile with `#![no_std]` and `#![forbid(unsafe_code)]` | Enforced |\n| 2 | Cold boot to first witness | \u003c 250ms on Appliance hardware |\n| 3 | Hot partition switch | \u003c 10 microseconds |\n| 4 | Witness record is exactly 64 bytes, cache-line aligned | Compile-time asserted |\n| 5 | Capability derivation depth bounded at 8 levels | Enforced |\n| 6 | EMA coherence filter operates without floating-point | Implemented |\n| 7 | Boot sequence is deterministic and witness-gated | Implemented |\n| 8 | Remote memory traffic reduction ≥ 20% vs naive placement | Target |\n| 9 | Fault recovery without global reboot (F1–F3) | Target |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏗️ Implementation Phases\u003c/b\u003e\u003c/summary\u003e\n\n### Phase 1: Foundation (M0-M1) — \"Can it boot and isolate?\"\n- **M0**: Bare-metal Rust boot on QEMU AArch64 virt. Reset → EL2 → serial → MMU → first witness.\n- **M1**: Partition + capability model. Create, destroy, switch. Simple deadline scheduler.\n\n### Phase 2: Differentiation (M2-M3) — \"Can it prove and witness?\"\n- **M2**: Witness logging (64-byte chained records) + P1/P2 proof verifier.\n- **M3**: 2-signal scheduler (deadline + cut_pressure). Flow + Reflex modes. Zero-copy IPC.\n\n### Phase 3: Innovation (M4-M5) — \"Can it think about coherence?\"\n- **M4**: Dynamic mincut integration (DC-2 budget). Live coherence graph. Migration triggers.\n- **M5**: Memory tier management. Reconstruction from dormant state.\n\n### Phase 4: Expansion (M6-M7) — \"Can agents run on it?\"\n- **M6**: WASM agent runtime adapter. Agent lifecycle.\n- **M7**: Seed/Appliance hardware bring-up. All success criteria.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔐 Security Model\u003c/b\u003e\u003c/summary\u003e\n\n**Capability-Based Authority.** All access controlled through unforgeable kernel-resident tokens. No ambient authority. Seven rights with monotonic attenuation.\n\n**Proof-Gated Mutation.** No memory remap, device mapping, migration, or partition merge without a valid proof token. Three tiers with strict latency budgets.\n\n**Witness-Native Audit.** 64-byte records for every mutating operation. Hash-chained for tamper evidence. Deterministic replay from checkpoint + witness log.\n\n**Failure Classification.** F1 (agent restart) → F2 (partition reconstruct) → F3 (memory rollback) → F4 (kernel reboot). Each escalation witnessed.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGPU Compute Support (ADR-144)\u003c/b\u003e\u003c/summary\u003e\n\n### Overview\n\nRVM provides capability-gated, proof-verified, witness-logged GPU compute access for partitions. GPU support is **feature-gated** — zero cost when disabled.\n\n### Quick Start\n\n```rust\n// Enable in Cargo.toml\n// rvm-kernel = { features = [\"gpu\"] }\n\nuse rvm_kernel::gpu::{\n    context::GpuContext,\n    kernel::LaunchConfig,\n    budget::GpuBudget,\n    queue::{GpuQueue, QueueCommand},\n    buffer::{GpuBuffer, BufferUsage},\n    GpuTier, GpuStatus,\n};\nuse rvm_types::PartitionId;\n\n// Create a GPU context for a partition\nlet budget = GpuBudget::new(\n    1_000_000_000,  // 1 second compute budget\n    512 * 1024 * 1024,  // 512 MB memory\n    1_000_000_000,  // 1 GB transfer budget\n    1000,  // max 1000 kernel launches per epoch\n);\nlet ctx = GpuContext::new(PartitionId::new(1), 0, budget);\n\n// Configure a kernel launch (3D workgroups)\nlet config = LaunchConfig {\n    workgroups: [64, 64, 1],      // 64x64 workgroups\n    workgroup_size: [256, 1, 1],  // 256 threads each\n    shared_memory_bytes: 16384,    // 16 KB shared memory\n    timeout_ns: 100_000_000,       // 100ms timeout\n};\nassert!(config.validate().is_ok());\nprintln!(\"Total threads: {}\", config.total_threads()); // 1,048,576\n\n// Create and manage GPU buffers\nlet buffer = GpuBuffer {\n    id: BufferId::new(1),\n    partition_id: PartitionId::new(1),\n    size_bytes: 1024 * 1024,  // 1 MB\n    usage: BufferUsage::Storage,\n    host_mapped: false,\n};\n```\n\n### Backends\n\n| Backend | Feature Flag | Platform | Use Case |\n|---------|-------------|----------|----------|\n| CUDA | `cuda` | NVIDIA GPUs | ML inference, HPC |\n| WebGPU | `webgpu` | Cross-platform | Portable compute |\n| Metal | `metal` | Apple Silicon | macOS/iOS acceleration |\n| OpenCL | `opencl` | Any GPU | Legacy hardware |\n| Vulkan | `vulkan` | Any GPU | Low-level compute |\n| WASM SIMD | `wasm-simd` | CPU only | Seed profile fallback |\n\n### Architecture\n\n```\nWASM Agent ──→ HostFunction::GpuLaunch ──→ SecurityGate ──→ GpuContext ──→ GPU\n                                              │\n                              CapRights::EXECUTE + WRITE\n                              DmaBudget check\n                              WitnessRecord emission\n```\n\n### Security Model\n\n- **Capability-gated**: requires `EXECUTE | WRITE` rights on device\n- **IOMMU isolated**: per-partition GPU page tables\n- **DMA budgeted**: bytes transferred per epoch\n- **Witnessed**: every kernel launch, transfer, and allocation logged\n- **Timeout enforced**: kernel execution deadline (100ms default)\n- **Budget enforcement**: 4 dimensions — compute time, memory, transfers, launches\n\n### Coherence Engine Acceleration\n\nMinCut and scoring algorithms can be offloaded to GPU:\n\n```rust\nuse rvm_gpu::accel::{GpuMinCutConfig, GpuScoringConfig};\n\nlet mincut_cfg = GpuMinCutConfig {\n    max_nodes: 32,\n    budget_iterations: 31,\n    use_gpu: true,\n};\n\nlet scoring_cfg = GpuScoringConfig {\n    max_partitions: 256,\n    use_gpu: true,\n};\n```\n\n### Source\n\nGPU compute is powered by [cuda-rust-wasm](https://crates.io/crates/cuda-rust-wasm) ([source](https://github.com/ruvnet/ruv-FANN)), providing CUDA→Rust transpilation with WebGPU/Metal/Vulkan backends. Full source available in the `cuda-wasm/` submodule.\n\nSee [ADR-144](docs/adr/ADR-144-gpu-compute-support.md) for the complete architecture decision record.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🖥️ Target Platforms\u003c/b\u003e\u003c/summary\u003e\n\n| Platform | Profile | RAM | Coherence Engine | WASM |\n|----------|---------|-----|-----------------|------|\n| **Seed** | Tiny, persistent, event-driven | 64KB–1MB | No (DC-1) | Optional |\n| **Appliance** | Edge hub, deterministic orchestration | 1–32GB | Yes (full) | Yes |\n| **Chip** | Future Cognitum silicon | Tile-local | Hardware-assisted | Yes |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📚 ADR References\u003c/b\u003e\u003c/summary\u003e\n\n| ADR | Topic |\n|-----|-------|\n| ADR-132 | RVM top-level architecture and 15 design constraints |\n| ADR-133 | Partition object model and split/merge semantics |\n| ADR-134 | Witness schema and log format (64-byte records) |\n| ADR-135 | Three-tier proof system (P1/P2/P3) |\n| ADR-136 | Memory hierarchy and reconstruction |\n| ADR-137 | Bare-metal boot sequence |\n| ADR-138 | Seed hardware bring-up |\n| ADR-139 | Appliance deployment model |\n| ADR-140 | Agent runtime adapter |\n| ADR-141 | Coherence engine kernel integration and runtime pipeline |\n| ADR-142 | TEE-backed cryptographic verification (SHA-256, Ed25519, HMAC-SHA256, TEE pipeline) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Development\u003c/b\u003e\u003c/summary\u003e\n\n### Prerequisites\n\n- Rust 1.77+ with `aarch64-unknown-none` target\n- QEMU 8.0+ (for AArch64 virt machine emulation)\n\n```bash\nrustup target add aarch64-unknown-none\nbrew install qemu  # macOS\n```\n\n### Project Conventions\n\n- `#![no_std]` everywhere — the kernel runs on bare metal\n- `#![forbid(unsafe_code)]` where possible; `unsafe` blocks audited and commented\n- `#![deny(missing_docs)]` — every public API documented\n- Move semantics for memory ownership (`OwnedRegion\u003cP\u003e` is non-copyable)\n- Const generics for fixed-size structures (no heap allocation in kernel paths)\n- Every state mutation emits a witness record\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📖 User Guide \u0026amp; Tutorial\u003c/b\u003e\u003c/summary\u003e\n\n### Quick Start (5 Minutes)\n\n```bash\n# 1. Clone and verify (--recurse-submodules pulls ruvector + rudevolution)\ngit clone --recurse-submodules https://github.com/ruvnet/rvm.git \u0026\u0026 cd rvm\ncargo test --workspace --lib    # 945 tests, 0 failures\n\n# 2. Run benchmarks\ncargo bench -p rvm-benches      # 11 criterion benchmarks\n\n# 3. Build for bare metal\nrustup target add aarch64-unknown-none\ncargo install cargo-binutils \u0026\u0026 rustup component add llvm-tools\nmake build                      # AArch64 release binary\n\n# 4. Boot in QEMU\nbrew install qemu               # macOS (or apt install qemu-system-aarch64)\nmake run                        # Boots at 0x4000_0000, PL011 UART output\n\n# 5. Use as a library\n# Add to Cargo.toml: rvm-kernel = { path = \"crates/rvm-kernel\" }\n```\n\n```rust\nuse rvm_kernel::{\n    types, hal, cap, witness, proof, partition,\n    sched, memory, coherence, boot, wasm, security,\n};\n```\n\n### Full User Guide\n\nThe [`userguide/`](userguide/) directory contains 17 chapters covering every subsystem:\n\n| Chapter | Topic |\n|---------|-------|\n| [01 Quick Start](userguide/01-quickstart.md) | Build, test, and boot in 5 minutes |\n| [02 Core Concepts](userguide/02-core-concepts.md) | Partitions, capabilities, witnesses, proofs, coherence |\n| [03 Architecture](userguide/03-architecture.md) | Layer diagram, data flow, boot sequence, feature flags |\n| [04 Crate Reference](userguide/04-crate-reference.md) | All 13 crates with types, APIs, and dependencies |\n| [05 Capabilities \u0026 Proofs](userguide/05-capabilities-proofs.md) | 7 rights, delegation trees, 3 proof tiers, TEE |\n| [06 Witness \u0026 Audit](userguide/06-witness-audit.md) | 64-byte records, hash chains, signing, querying |\n| [07 Partitions \u0026 Scheduling](userguide/07-partitions-scheduling.md) | Lifecycle, IPC, split/merge, 2-signal scheduler |\n| [08 Memory Model](userguide/08-memory-model.md) | 4 tiers, buddy allocator, reconstruction |\n| [09 WASM Agents](userguide/09-wasm-agents.md) | Module validation, 7-state lifecycle, migration |\n| [10 Security](userguide/10-security.md) | 3-stage gate, attestation, audit results |\n| [11 Performance](userguide/11-performance.md) | 11 benchmarks, build profiles, tuning |\n| [12 Bare Metal](userguide/12-bare-metal.md) | Linker script, QEMU, measured boot, Seed/Appliance |\n| [13 Advanced \u0026 Exotic](userguide/13-advanced-exotic.md) | 6 novel capabilities, fault rollback, RuVector |\n| [14 Troubleshooting](userguide/14-troubleshooting.md) | 12 categories of common issues |\n| [15 Glossary](userguide/15-glossary.md) | 60+ terms with cross-references |\n| [Cross-Reference](userguide/cross-reference.md) | Concept index, API finder, \"I want to...\" tasks |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔌 MCP Documentation Tools\u003c/b\u003e\u003c/summary\u003e\n\nRVM ships with an MCP (Model Context Protocol) server and CLI for AI-assisted documentation search and navigation.\n\n### Installation\n\n```bash\ncd userguide/mcp\nnpm install \u0026\u0026 npm run build\n```\n\n### Register with Claude Code\n\n```bash\nclaude mcp add rvm-docs -- node /path/to/rvm/userguide/mcp/dist/index.js\n```\n\n### MCP Tools (6 tools)\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `docs_search` | Full-text keyword search across all docs | `{ \"query\": \"witness chain\" }` |\n| `docs_navigate` | Browse table of contents or read a chapter | `{ \"chapter\": \"05\" }` |\n| `docs_xref` | Find all cross-references for a concept | `{ \"concept\": \"coherence\" }` |\n| `docs_glossary` | Look up a term definition | `{ \"term\": \"partition\" }` |\n| `docs_api` | Find documentation for an RVM type/function | `{ \"symbol\": \"SecurityGate\" }` |\n| `docs_howto` | Task-oriented \"I want to...\" search | `{ \"task\": \"build rvm\" }` |\n\n### CLI Usage\n\n```bash\ncd userguide/mcp\nnode dist/cli.js search \"capability\"      # Full-text search\nnode dist/cli.js nav                       # Table of contents\nnode dist/cli.js nav 05                    # Read chapter 05\nnode dist/cli.js xref \"witness\"            # Cross-references\nnode dist/cli.js glossary \"partition\"       # Term lookup\nnode dist/cli.js api \"CapToken\"            # API documentation\nnode dist/cli.js howto \"build rvm\"         # Task-oriented guide\n```\n\n### Shorthand Aliases\n\n```bash\nnode dist/cli.js s \"proof\"    # search\nnode dist/cli.js n 03         # navigate\nnode dist/cli.js x \"memory\"   # xref\nnode dist/cli.js g \"EMA\"      # glossary\nnode dist/cli.js a \"verify\"   # api\nnode dist/cli.js h \"deploy\"   # howto\n```\n\n\u003c/details\u003e\n\n---\n\n## RuVector Integration\n\nThe full [RuVector](https://github.com/ruvnet/RuVector) ecosystem is available via the `ruvector/` submodule. See [Integration Map](docs/RUVECTOR-INTEGRATION.md) for detailed path references.\n\n| Crate | Submodule Path | Role in RVM |\n|-------|----------------|-------------|\n| [`ruvector-mincut`](ruvector/crates/ruvector-mincut/) | `ruvector/crates/ruvector-mincut/` | Partition placement and isolation decisions |\n| [`ruvector-sparsifier`](ruvector/crates/ruvector-sparsifier/) | `ruvector/crates/ruvector-sparsifier/` | Compressed shadow graph for Laplacian operations |\n| [`ruvector-solver`](ruvector/crates/ruvector-solver/) | `ruvector/crates/ruvector-solver/` | Effective resistance → coherence scores |\n| [`ruvector-coherence`](ruvector/crates/ruvector-coherence/) | `ruvector/crates/ruvector-coherence/` | Spectral coherence tracking |\n| [`ruvix`](ruvector/crates/ruvix/) | `ruvector/crates/ruvix/` | Kernel primitives (Task, Capability, Region, Queue, Timer, Proof) |\n| [`rvf`](ruvector/crates/rvf/) | `ruvector/crates/rvf/` | Package format for boot images, checkpoints, and cold storage |\n\n### RVF Package Ecosystem (22 crates)\n\n| Crate | Path | Purpose |\n|-------|------|---------|\n| `rvf-types` | [`ruvector/crates/rvf/rvf-types/`](ruvector/crates/rvf/rvf-types/) | Core types, manifest, vectors |\n| `rvf-crypto` | [`ruvector/crates/rvf/rvf-crypto/`](ruvector/crates/rvf/rvf-crypto/) | Cryptographic signing/verification |\n| `rvf-index` | [`ruvector/crates/rvf/rvf-index/`](ruvector/crates/rvf/rvf-index/) | HNSW vector indexing |\n| `rvf-kernel` | [`ruvector/crates/rvf/rvf-kernel/`](ruvector/crates/rvf/rvf-kernel/) | Kernel-level RVF integration |\n| `rvf-runtime` | [`ruvector/crates/rvf/rvf-runtime/`](ruvector/crates/rvf/rvf-runtime/) | Runtime execution environment |\n| `rvf-wasm` | [`ruvector/crates/rvf/rvf-wasm/`](ruvector/crates/rvf/rvf-wasm/) | WASM runtime for RVF containers |\n| `rvf-quant` | [`ruvector/crates/rvf/rvf-quant/`](ruvector/crates/rvf/rvf-quant/) | Quantization for memory reduction |\n| `rvf-federation` | [`ruvector/crates/rvf/rvf-federation/`](ruvector/crates/rvf/rvf-federation/) | Federated distribution |\n\n### Related ADRs \u0026 Research\n\n| Resource | Path |\n|----------|------|\n| Core architecture | [`ruvector/docs/adr/ADR-001-ruvector-core-architecture.md`](ruvector/docs/adr/ADR-001-ruvector-core-architecture.md) |\n| Coherence engine | [`ruvector/docs/adr/ADR-014-coherence-engine.md`](ruvector/docs/adr/ADR-014-coherence-engine.md) |\n| Memory management | [`ruvector/docs/adr/ADR-006-memory-management.md`](ruvector/docs/adr/ADR-006-memory-management.md) |\n| Security review | [`ruvector/docs/adr/ADR-007-security-review-technical-debt.md`](ruvector/docs/adr/ADR-007-security-review-technical-debt.md) |\n| Architecture docs | [`ruvector/docs/architecture/`](ruvector/docs/architecture/) |\n| Benchmarks | [`ruvector/docs/benchmarks/`](ruvector/docs/benchmarks/) |\n\n---\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT License ([LICENSE-MIT](LICENSE-MIT) or \u003chttp://opensource.org/licenses/MIT\u003e)\n\nat your option.\n\n---\n\n\u003csub\u003e[EPIC](https://github.com/ruvnet/RuVector/issues/328) · [Research Gist](https://gist.github.com/ruvnet/8082d0b339f05e73cf48b491de5b8ee6) · [pi.ruv.io Brain](https://pi.ruv.io)\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Frvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruvnet%2Frvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Frvm/lists"}