mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-27 08:45:07 +00:00
c88039734a
* 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>
115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# Architecture Decision Records
|
|
|
|
This directory contains Architecture Decision Records (ADRs) for ruvector's core technical decisions.
|
|
|
|
## Decision Index
|
|
|
|
| ADR | Title | Status | Summary |
|
|
|-----|-------|--------|---------|
|
|
| [ADR-001](ADR-001-core-simd-strategy.md) | Core SIMD Optimization Strategy | Accepted | AVX-512/AVX2/NEON with runtime detection for 2.5x-18x speedup |
|
|
| [ADR-002](ADR-002-hyperbolic-embeddings.md) | Hyperbolic Embeddings for Hierarchical Data | Accepted | Poincare ball model for low-distortion tree embeddings |
|
|
| [ADR-003](ADR-003-mcp-protocol.md) | MCP Server Architecture and Transport | Accepted | JSON-RPC 2.0 over stdio/SSE/WebSocket for AI agent integration |
|
|
| [ADR-004](ADR-004-rvf-format.md) | RVF Cognitive Container Format | Accepted | Self-describing vector format with WASM kernels |
|
|
| [ADR-005](ADR-005-cross-platform-bindings.md) | Cross-Platform Bindings (WASM + NAPI-RS) | Accepted | WASM-first with native acceleration via NAPI-RS |
|
|
| [ADR-006](ADR-006-sona-adaptation.md) | SONA Self-Optimizing Architecture | Accepted | Online learning for automatic parameter tuning |
|
|
| [ADR-007](ADR-007-differential-privacy.md) | Differential Privacy and Epsilon-Budget | Accepted | Privacy budget management for collective learning |
|
|
| [ADR-008](ADR-008-flash-attention.md) | Flash Attention Implementation | Accepted | Memory-efficient O(N) attention with block-sparse patterns |
|
|
|
|
## ADR Template
|
|
|
|
When creating new ADRs, use this structure:
|
|
|
|
```markdown
|
|
# 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 |
|
|
|
|
## Related Documentation
|
|
|
|
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 |
|