mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-06-01 14:39:33 +00:00
6176e8f952
Three coordinated fixes from the rc1 device + CI run:
1. **`src/main.rs` — install + use the USB-Serial/JTAG interrupt-mode driver**
With `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y` alone, ESP-IDF installs a
polling-mode driver. Bootloader logs reach `/dev/ttyACM0` but Rust
`std::io::stdout` / `stderr` / `stdin` do not — TX buffers indefinitely
until reset, RX returns undefined data. Symptom: panic prints work
(panic flushes on reboot) but `eprintln!` during steady state goes
nowhere.
Fix: at the top of main, call `usb_serial_jtag_driver_install` then
`esp_vfs_usb_serial_jtag_use_driver`. After both calls, `eprintln!`
flushes via interrupt-driven TX and `stdin().lock().lines()` blocks
on USB-CDC RX exactly like host stdio.
Also drops the FFI-write helpers (`jtag_write` / `jtag_writeln`) in
favor of std::io. The interactive CLI loop becomes the same shape as
the host-test path: `for line in stdin.lock().lines() { … }`.
2. **`.github/workflows/ruvllm-esp32-firmware.yml` — per-toolchain matrix +
ldproxy install**
rc1 CI matrix failures:
- all Xtensa builds: `error: linker 'ldproxy' not found` —
`cargo install espflash --locked` only installs espflash; ldproxy
was missing.
- both RISC-V builds (esp32c3, esp32c6): `error: toolchain 'esp' is
not installed` — `espup install --targets <riscv-chip>` is a no-op
for the Rust toolchain; the build then ran `cargo +esp build` and
panicked.
Fix:
- Install `ldproxy` and `espflash` together: `cargo install espflash
ldproxy --locked` (always, both toolchains need it).
- Per-matrix `toolchain: esp` (Xtensa) vs `nightly` (RISC-V).
- `if: matrix.toolchain == 'esp'` → espup install path.
- `if: matrix.toolchain == 'nightly'` → `rustup toolchain install
nightly --component rust-src`.
- `cargo +${{ matrix.toolchain }} build …` picks the right channel
per target.
- `unset RUSTFLAGS` in the build step (mold doesn't speak Xtensa or
RISC-V-esp).
3. **`docs/adr/ADR-166-esp32-rust-cross-compile-bringup-ops.md` — full
operations manual**
Companion to ADR-165. ADR-165 says *what* runs; ADR-166 says *how* to
build it. 16 sections, ~14 KB. Captures every failure mode hit during
rc1 (14 distinct ones), with root cause and fix for each, the pinned
crate trio (esp-idf-svc 0.51 / esp-idf-hal 0.45 / esp-idf-sys 0.36),
the per-target toolchain matrix, the build.rs `CARGO_CFG_TARGET_OS`
pattern, the .cargo/config.toml linker contract, the sdkconfig
defaults split, the USB-Serial/JTAG console two-call setup, the stack
budget for TinyAgent, the CI workflow contract, the operational
acceptance gates G1–G6, and a searchable failure → remedy table.
Includes a verification log section with the actual rc1 transcripts
from real ESP32-S3 hardware (`ac:a7:04:e2:66:24`).
Closes:
- rc1 CI failure modes 13 (ldproxy) + 14 (RISC-V toolchain) — workflow fix
- ADR-165 §7 step 5 (USB-CDC console parity) — VFS fix
- Documentation gap so the next contributor doesn't bisect 14 failures
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|---|---|---|
| .. | ||
| adr | ||
| analysis | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| cnn | ||
| code-reviews | ||
| dag | ||
| development | ||
| examples | ||
| gnn | ||
| guides | ||
| hnsw | ||
| hooks | ||
| implementation | ||
| integration | ||
| nervous-system | ||
| optimization | ||
| plans/subpolynomial-time-mincut | ||
| postgres | ||
| project-phases | ||
| publishing | ||
| research | ||
| reviews | ||
| ruvllm | ||
| rvagent | ||
| sdk | ||
| security | ||
| sparse-inference | ||
| sql | ||
| testing | ||
| training | ||
| .gitkeep | ||
| .nojekyll | ||
| agi-container.md | ||
| C2-shell-execution-hardening.md | ||
| C8_RESULT_VALIDATION_IMPLEMENTATION.md | ||
| consciousness-api.md | ||
| IMPLEMENTATION-C5.md | ||
| index.html | ||
| INDEX.md | ||
| moe-routing-optimization-analysis.md | ||
| README.md | ||
| REPO_STRUCTURE.md | ||
| research-openfang.md | ||
RuVector Documentation
Complete documentation for RuVector, the high-performance Rust vector database with global scale capabilities.
📚 Documentation Structure
docs/
├── adr/ # Architecture Decision Records
├── analysis/ # Research & analysis docs
├── api/ # API references (Rust, Node.js, Cypher)
├── architecture/ # System design docs
├── benchmarks/ # Performance benchmarks & results
├── cloud-architecture/ # Cloud deployment guides
├── code-reviews/ # Code review documentation
├── dag/ # DAG implementation
├── development/ # Developer guides
├── examples/ # SQL examples
├── gnn/ # GNN/Graph implementation
├── guides/ # User guides & tutorials
├── hnsw/ # HNSW index documentation
├── hooks/ # Hooks system documentation
├── implementation/ # Implementation details & summaries
├── integration/ # Integration guides
├── nervous-system/ # Nervous system architecture
├── optimization/ # Performance optimization guides
├── plans/ # Implementation plans
├── postgres/ # PostgreSQL extension docs
├── project-phases/ # Development phases
├── publishing/ # NPM publishing guides
├── research/ # Research documentation
├── ruvllm/ # RuVLLM documentation
├── security/ # Security audits & reports
├── sparse-inference/ # Sparse inference docs
├── sql/ # SQL examples
├── testing/ # Testing documentation
└── training/ # Training & LoRA docs
Getting Started
- guides/GETTING_STARTED.md - Getting started guide
- guides/BASIC_TUTORIAL.md - Basic tutorial
- guides/INSTALLATION.md - Installation instructions
- guides/AGENTICDB_QUICKSTART.md - AgenticDB quick start
- guides/wasm-api.md - WebAssembly API documentation
Architecture & Design
- architecture/ - System architecture details
- cloud-architecture/ - Global cloud deployment
- adr/ - Architecture Decision Records
- nervous-system/ - Nervous system architecture
API Reference
- api/RUST_API.md - Rust API reference
- api/NODEJS_API.md - Node.js API reference
- api/CYPHER_REFERENCE.md - Cypher query reference
Performance & Benchmarks
- benchmarks/ - Performance benchmarks & results
- optimization/ - Performance optimization guides
- analysis/ - Research & analysis docs
Security
- security/ - Security audits & reports
Implementation
- implementation/ - Implementation details & summaries
- integration/ - Integration guides
- code-reviews/ - Code review documentation
Specialized Topics
- gnn/ - GNN/Graph implementation
- hnsw/ - HNSW index documentation
- postgres/ - PostgreSQL extension docs
- ruvllm/ - RuVLLM documentation
- training/ - Training & LoRA docs
Development
- development/CONTRIBUTING.md - Contribution guidelines
- development/MIGRATION.md - Migration guide
- testing/ - Testing documentation
- publishing/ - NPM publishing guides
Research
- research/ - Research documentation
- cognitive-frontier/ - Cognitive frontier research
- gnn-v2/ - GNN v2 research
- latent-space/ - HNSW & attention research
- mincut/ - MinCut algorithm research
🚀 Quick Links
For New Users
- Start with Getting Started Guide
- Try the Basic Tutorial
- Review API Documentation
For Cloud Deployment
- Read Architecture Overview
- Follow Deployment Guide
- Apply Performance Optimizations
For Contributors
- Read Contributing Guidelines
- Review Architecture Decisions
- Check Migration Guide
For Performance Tuning
- Review Optimization Guide
- Run Benchmarks
- Check Analysis
📊 Documentation Status
| Category | Directory | Status |
|---|---|---|
| Getting Started | guides/ | ✅ Complete |
| Architecture | architecture/, adr/ | ✅ Complete |
| API Reference | api/ | ✅ Complete |
| Performance | benchmarks/, optimization/, analysis/ | ✅ Complete |
| Security | security/ | ✅ Complete |
| Implementation | implementation/, integration/ | ✅ Complete |
| Development | development/, testing/ | ✅ Complete |
| Research | research/ | 📚 Ongoing |
Total Documentation: 460+ documents across 60+ directories
🔗 External Resources
- GitHub Repository: https://github.com/ruvnet/ruvector
- Main README: ../README.md
- Changelog: ../CHANGELOG.md
- License: ../LICENSE
Last Updated: 2026-02-26 | Version: 2.0.4 (core) / 0.1.100 (npm) | Status: Production Ready