mirror of https://github.com/ruvnet/RuVector.git synced 2026-05-24 13:54:31 +00:00

feat(ruvix): implement CLI, kernel shell, and PBFT consensus (#261 )

* feat(ruvix): implement ADR-087 RuVix Cognition Kernel Phase A

Implements the complete Phase A (Linux-hosted) RuVix Cognition Kernel
with 9 crates, 760 tests, and comprehensive documentation.

## Core Crates (9)
- ruvix-types: 6 kernel primitives (Task, Capability, Region, Queue, Timer, Proof)
- ruvix-cap: seL4-inspired capability management with derivation trees
- ruvix-region: Memory regions (Immutable, AppendOnly, Slab policies)
- ruvix-queue: io_uring-style lock-free IPC with zero-copy semantics
- ruvix-proof: 3-tier proof engine (Reflex <100ns, Standard <100us, Deep <10ms)
- ruvix-sched: Coherence-aware scheduler with priority computation
- ruvix-boot: 5-stage RVF boot loader with ML-DSA-65 signatures
- ruvix-vecgraph: Kernel-resident vector/graph stores with HNSW
- ruvix-nucleus: Unified kernel entry point with 12 syscalls

## Security (SEC-001, SEC-002)
- Boot signature failure: PANIC immediately, no fallback path
- Proof cache: 100ms TTL, single-use nonces, max 64 entries
- Capability delegation depth: max 8 levels with audit warnings

## Architecture
- no_std compatible for Phase B bare metal port
- Proof-gated mutation: every state change requires cryptographic proof
- Capability-based access control: no syscall without valid capability
- Zero-copy IPC via region descriptors (TOCTOU protected)

## Documentation
- Main README with architecture diagrams
- Individual crate READMEs with usage examples
- Architecture decision records

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs: update ADR-087 status and add RuVix to root README

- Update ADR-087 status from Proposed to Accepted (Phase A Implemented)
- Add implementation status table with all 9 crates and 760 tests
- Document security invariants implemented (SEC-001 through SEC-004)
- Add collapsed RuVix section to root README with architecture diagram

Co-Authored-By: claude-flow <ruv@ruv.net>

* chore: update ruvector-coherence dependency to 2.0.4 for crates.io publish

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(ruvix): implement ADR-087 Phase B bare metal AArch64 support

Phase B adds bare metal AArch64 support for the RuVix Cognition Kernel:

New crates:
- ruvix-hal: Hardware Abstraction Layer traits (~500 lines)
  - Console, InterruptController, Timer, Mmu, PowerManagement traits
  - Platform-agnostic design for ARM64/RISC-V/x86_64
  - 15 unit tests passing

- ruvix-aarch64: AArch64 boot and MMU support (~2,000 lines)
  - _start assembly entry, exception vectors
  - 4-level page tables with capability metadata
  - System register accessors (SCTLR_EL1, TCR_EL1, TTBR0/1)
  - Implements ruvix_hal::Mmu trait

- ruvix-drivers: Device drivers for QEMU virt (~1,500 lines)
  - PL011 UART driver (115200 8N1, FIFO, interrupts)
  - GIC-400 interrupt controller (256 IRQs, 16 priorities)
  - ARM Generic Timer (deadline scheduling)
  - Volatile MMIO with memory barriers (DMB, DSB, ISB)

Build infrastructure:
- aarch64-boot/ with linker script and custom Rust target
- QEMU virt runner integration (Cortex-A72, 128MB RAM)
- Makefile with build/run/debug targets

ADR-087 updated with:
- Phase B objectives and new crate specifications
- QEMU virt memory map (128MB RAM at 0x40000000)
- 5-stage boot sequence documentation
- Security enhancements and testing strategy
- Raspberry Pi 4/5 platform differences

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(ruvix): implement Phases C/D/E and QEMU swarm simulation

This adds full bare metal OS capabilities to the RuVix Cognition Kernel:

## Phase C: Multi-Core & DMA Support
- ruvix-smp: Symmetric multi-processing (256 cores, spinlocks, IPIs)
- ruvix-dma: DMA controller with scatter-gather
- ruvix-dtb: Device tree blob parser
- ruvix-physmem: Buddy allocator for physical memory

## Phase D: Raspberry Pi 4/5 Support
- ruvix-bcm2711: BCM2711/2712 SoC drivers (GPIO, mailbox, UART)
- ruvix-rpi-boot: RPi boot support (spin table, early UART)

## Phase E: Networking & Filesystem
- ruvix-net: Full network stack (Ethernet/ARP/IPv4/UDP/ICMP)
- ruvix-fs: Filesystem layer (VFS, FAT32, RamFS)

## QEMU Swarm Simulation
- qemu-swarm: Multi-QEMU cluster for distributed testing
- Network topologies: mesh, ring, star, tree
- Fault injection and chaos testing scenarios

## Summary
- 10 new crates, ~27,000 lines of code
- 400+ new tests passing
- ADR-087 updated with Phases C/D/E documentation
- Main README updated with all phases

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ruvix): address critical security vulnerabilities CVE-001 through CVE-005

Security fixes applied from deep review audit:

- CVE-001 (CRITICAL): Add compile-time protection preventing
  `disable-boot-verify` feature in release builds. This closes
  a boot signature bypass vulnerability.

- CVE-002 (HIGH): Add MMIO address validation to GIC driver.
  `Gic::new()` now returns `Result<Self, GicError>` and validates
  addresses against known platform ranges. Added `new_unchecked()`
  for trusted callers.

- CVE-003 (HIGH): Add integer overflow protection in DTB parser.
  All offset calculations now use `checked_add()` to prevent
  buffer overflow via crafted DTB files.

- CVE-005 (HIGH): Add IPv4 header validation ensuring
  `total_length >= header_len` per RFC 791.

Also includes test fixes:
- Mark hardware-dependent tests as `#[ignore]` (MMIO, ARM timer)
- Fix swap32 test assertion in rpi-boot
- Update doctests for new GIC API

All 259 tests pass across affected crates.

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(ruvix): implement CLI, kernel shell, and PBFT consensus

Implements Phase F features for the RuVix Cognition Kernel:

CLI (ruvix-cli):
- build: Cross-compile kernel for AArch64 targets
- config: Manage kernel configuration files
- dtb: Device tree blob operations (validate, dump, compile, compare, search)
- flash: UART/serial flash operations with progress reporting
- keys: Ed25519 key management with secure storage
- monitor: Real-time kernel metrics dashboard
- security: Security audit and vulnerability scanning

Kernel Shell (ruvix-shell):
- Interactive command parser with history support
- Commands: help, info, mem, tasks, caps, vectors, witness, proofs,
  queues, perf, cpu, trace, reboot
- Configurable prompt with trace mode indication
- Shell backend integration with nucleus kernel

PBFT Consensus (qemu-swarm):
- Full PBFT implementation (pre-prepare, prepare, commit phases)
- View change protocol for leader recovery
- Checkpoint mechanism for state synchronization
- Custom serde wrappers for fixed-size byte arrays (Signature, HashDigest)
- Byzantine fault tolerance (f < n/3)

Additional:
- Example RVF swarm consensus demo
- Nucleus shell backend for kernel introspection
- Fixed chrono DateTime type annotation in keys.rs

Co-Authored-By: claude-flow <ruv@ruv.net>

* chore(ruvix): add version specs for crates.io publishing

- Add version = "0.1.0" to ruvix-dtb dependency in CLI
- Add README.md for ruvix-shell crate

Co-Authored-By: claude-flow <ruv@ruv.net>

---------

Co-authored-by: Reuven <cohen@ruv-mac-mini.local>

2026-03-14 16:25:03 -04:00

4.3 KiB

Raw Permalink Blame History

Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for ruvector's core technical decisions.

Decision Index

ADR	Title	Status	Summary
ADR-001	Core SIMD Optimization Strategy	Accepted	AVX-512/AVX2/NEON with runtime detection for 2.5x-18x speedup
ADR-002	Hyperbolic Embeddings for Hierarchical Data	Accepted	Poincare ball model for low-distortion tree embeddings
ADR-003	MCP Server Architecture and Transport	Accepted	JSON-RPC 2.0 over stdio/SSE/WebSocket for AI agent integration
ADR-004	RVF Cognitive Container Format	Accepted	Self-describing vector format with WASM kernels
ADR-005	Cross-Platform Bindings (WASM + NAPI-RS)	Accepted	WASM-first with native acceleration via NAPI-RS
ADR-006	SONA Self-Optimizing Architecture	Accepted	Online learning for automatic parameter tuning
ADR-007	Differential Privacy and Epsilon-Budget	Accepted	Privacy budget management for collective learning
ADR-008	Flash Attention Implementation	Accepted	Memory-efficient O(N) attention with block-sparse patterns

ADR Template

When creating new ADRs, use this structure:

# ADR-XXX: Title

| Field | Value |
|-------|-------|
| **Status** | Proposed / Accepted / Deprecated / Superseded |
| **Date** | YYYY-MM-DD |
| **Authors** | Names |
| **Reviewers** | Names |
| **Supersedes** | ADR-XXX (if applicable) |
| **Related** | ADR-XXX, ADR-YYY |

## 1. Context
[Problem statement and background]

## 2. Decision
[The decision and its justification]

## 3. Rationale
[Why this decision over alternatives]

## 4. Consequences
[Benefits, costs, and tradeoffs]

## 5. Implementation
[Key implementation details]

## 6. Related Decisions
[Links to related ADRs]

## 7. References
[External references]

## 8. Revision History
[Change log]

Decision Categories

Core Performance

ADR-001: SIMD optimization strategy (AVX-512/AVX2/NEON)
ADR-008: Flash Attention for LLM inference

Data Representation

ADR-002: Hyperbolic embeddings (Poincare ball model)
ADR-004: RVF cognitive container format

System Architecture

ADR-003: MCP protocol and transport choices
ADR-005: Cross-platform bindings (WASM + NAPI-RS)
ADR-006: SONA self-optimization
ADR-007: Differential privacy architecture

Quick Reference

Topic	ADR	Key Decision
Vector distance	ADR-001	Hand-optimized SIMD for 2.5-18x speedup
Hierarchical data	ADR-002	Poincare ball embeddings with c=1.0 default
AI agent protocol	ADR-003	MCP with stdio (local) and SSE (remote)
File format	ADR-004	RVF with 15 segment types, ML-DSA-65 signatures
Node.js bindings	ADR-005	NAPI-RS native with WASM fallback
Self-optimization	ADR-006	Temperature tracking, pattern learning, adaptive ef
Privacy	ADR-007	Gaussian mechanism, epsilon-budget, PII stripping
Long context	ADR-008	Flash Attention with 128K+ support

For more detailed ADRs, see the main /docs/adr/ directory which contains:

ADR-001 through ADR-088+ covering specific implementation decisions
Coherence Engine ADRs in /docs/adr/coherence-engine/
Project-specific ADRs in various crate directories

Status Definitions

Status	Meaning
Proposed	Under discussion, not yet implemented
Accepted	Decision made, implementation in progress or complete
Deprecated	No longer recommended, retained for history
Superseded	Replaced by a newer ADR

Implementation Status

ADR	Crate	Status
ADR-001	`ruvector-core`	Complete
ADR-002	`ruvector-core`, `ruvector-hyperbolic-hnsw`	Complete
ADR-003	`mcp-brain`, `ruvector-cli`	Complete
ADR-004	`rvf`, `rvf-kernel`	Complete
ADR-005	`ruvector-wasm`, `ruvector-node`	Complete
ADR-006	`ruvector-core`	Complete
ADR-007	`pi-brain`	Complete
ADR-008	`ruvllm`	Complete

4.3 KiB Raw Permalink Blame History