Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/examples/edge-net/sim/INDEX.md
+++ b/examples/edge-net/sim/INDEX.md
@@ -0,0 +1,247 @@
+# Edge-Net Lifecycle Simulation - Documentation Index
+
+## Quick Navigation
+
+### Getting Started
+1. **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** - Start here! Quick overview and reference
+2. **[USAGE.md](USAGE.md)** - Complete usage guide with examples
+3. **[README.md](README.md)** - Project overview (existing edge-net simulation docs)
+
+### Technical Documentation
+4. **[SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md)** - Deep dive into architecture and design
+
+### Source Code
+5. **[src/](src/)** - All TypeScript source files
+   - `cell.ts` - Node simulation
+   - `network.ts` - Network state management
+   - `metrics.ts` - Performance tracking
+   - `phases.ts` - Phase transition logic
+   - `report.ts` - Report generation
+   - `simulator.ts` - Main orchestrator
+
+## Documentation Hierarchy
+
+```
+Index (you are here)
+├── Quick Start
+│   ├── PROJECT_SUMMARY.md ⭐ Start here
+│   └── USAGE.md
+├── Architecture
+│   └── SIMULATION_OVERVIEW.md
+├── Project Overview
+│   └── README.md
+└── Source Code
+    └── src/*.ts
+```
+
+## By Use Case
+
+### I want to run the simulation
+→ **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** (Quick Reference section)
+→ **[USAGE.md](USAGE.md)** (Quick Start section)
+
+### I want to understand how it works
+→ **[SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md)** (Architecture section)
+→ **[USAGE.md](USAGE.md)** (Understanding Output section)
+
+### I want to modify the simulation
+→ **[SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md)** (Component Details)
+→ **[USAGE.md](USAGE.md)** (Customizing section)
+→ **Source code:** `src/*.ts`
+
+### I want to understand the results
+→ **[USAGE.md](USAGE.md)** (Understanding Output + Interpreting Results)
+→ **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** (Output Example section)
+
+### I want to integrate with Edge-Net
+→ **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** (Integration section)
+→ **[SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md)** (Integration section)
+
+## By Topic
+
+### Architecture
+- **Components:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Component Details
+- **Data Flow:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Execution Flow
+- **Algorithms:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Network Topology
+
+### Economics
+- **Energy Model:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Economic Model
+- **Sustainability:** [USAGE.md](USAGE.md) § Interpreting Results
+- **Parameters:** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Configuration Defaults
+
+### Phases
+- **Phase 1 (Genesis):** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Simulation Phases
+- **Phase 2 (Growth):** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Simulation Phases
+- **Phase 3 (Maturation):** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Simulation Phases
+- **Phase 4 (Independence):** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Simulation Phases
+- **Transitions:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Phases
+
+### Validation
+- **Criteria:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Validation Framework
+- **Interpreting:** [USAGE.md](USAGE.md) § Interpreting Results
+- **Success/Failure:** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Exit Codes
+
+### Performance
+- **Metrics:** [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) § Performance
+- **Optimization:** [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) § Performance Optimization
+- **Benchmarks:** [USAGE.md](USAGE.md) § Performance Tips
+
+## File Reference
+
+### Documentation Files
+
+| File | Size | Lines | Purpose |
+|------|------|-------|---------|
+| INDEX.md | This file | Quick navigation |
+| PROJECT_SUMMARY.md | 15 KB | 540 | Quick reference and overview |
+| USAGE.md | 10 KB | 420 | Complete usage guide |
+| SIMULATION_OVERVIEW.md | 18 KB | 650 | Technical architecture |
+| README.md | 2 KB | 63 | Project overview (existing) |
+
+### Source Files
+
+| File | Size | Lines | Purpose |
+|------|------|-------|---------|
+| src/cell.ts | 5.7 KB | 230 | Node simulation |
+| src/network.ts | 9.6 KB | 310 | Network management |
+| src/metrics.ts | 9.6 KB | 280 | Performance tracking |
+| src/phases.ts | 7.3 KB | 180 | Phase transitions |
+| src/report.ts | 8.4 KB | 270 | Report generation |
+| src/simulator.ts | 6.1 KB | 210 | Main orchestrator |
+
+### Configuration Files
+
+| File | Purpose |
+|------|---------|
+| package.json | NPM dependencies and scripts |
+| tsconfig.json | TypeScript compiler configuration |
+| .gitignore | Git ignore rules |
+
+## Quick Command Reference
+
+```bash
+# Installation
+npm install
+
+# Run simulation
+npm run simulate          # Normal mode
+npm run simulate:fast     # Fast mode
+npm run simulate:verbose  # Verbose mode
+
+# Build
+npm run build            # Compile TypeScript
+npm run clean            # Clean build artifacts
+```
+
+## Reading Order for New Users
+
+### Option 1: Quick Start (10 minutes)
+1. [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Read "Quick Reference" section
+2. Run `npm install && npm run simulate:fast`
+3. Review console output and JSON report
+
+### Option 2: Comprehensive (30 minutes)
+1. [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Full read
+2. [USAGE.md](USAGE.md) - "Understanding Output" section
+3. Run `npm run simulate`
+4. [USAGE.md](USAGE.md) - "Interpreting Results" section
+
+### Option 3: Technical Deep Dive (1-2 hours)
+1. [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Overview
+2. [SIMULATION_OVERVIEW.md](SIMULATION_OVERVIEW.md) - Full read
+3. [USAGE.md](USAGE.md) - "Customizing" section
+4. Source code review: `src/*.ts`
+5. Run multiple scenarios
+
+## Key Concepts
+
+### Must-Know Terms
+- **Cell:** Individual network node (simulated E2B sandbox)
+- **Energy (rUv):** Simulated cryptocurrency for operations
+- **Genesis Node:** Bootstrap node with 10x multiplier
+- **Phase:** Lifecycle stage (Genesis, Growth, Maturation, Independence)
+- **Sustainability:** Earned/spent energy ratio (must be > 1.0)
+- **Preferential Attachment:** New nodes connect to high-fitness nodes
+
+### Phase Milestones
+- **10K nodes:** Genesis → Growth
+- **50K nodes:** Growth → Maturation
+- **100K nodes:** Maturation → Independence
+- **120K nodes:** Simulation complete
+
+### Validation Thresholds
+- **Genesis multiplier:** 10.0x initially
+- **Energy accumulation:** > 1000 rUv in genesis
+- **Success rate:** > 70% task completion
+- **Sustainability:** > 1.0 earned/spent ratio
+- **Connectivity:** > 5 avg connections (genesis), > 10 (maturation)
+
+## Troubleshooting Guide
+
+### Build Errors
+→ [USAGE.md](USAGE.md) § Troubleshooting
+
+### Runtime Errors
+→ [USAGE.md](USAGE.md) § Troubleshooting
+
+### Validation Failures
+→ [USAGE.md](USAGE.md) § Interpreting Results § Critical Issues
+
+### Performance Issues
+→ [USAGE.md](USAGE.md) § Performance Tips
+
+## External References
+
+### Related Edge-Net Documentation
+- `/workspaces/ruvector/examples/edge-net/architecture.md` - Network architecture
+- `/workspaces/ruvector/examples/edge-net/economic-model.md` - Economic details
+- `/workspaces/ruvector/examples/edge-net/deployment.md` - Deployment guide
+
+### RuVector Project
+- `/workspaces/ruvector/README.md` - Main project README
+- `/workspaces/ruvector/docs/` - RuVector documentation
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| Cell | Simulated network node (maps to E2B sandbox) |
+| rUv | Resource Utility Voucher (simulated energy/currency) |
+| Genesis Node | Bootstrap node with 10x earning multiplier |
+| Regular Node | Standard network node with 1x multiplier |
+| Phase | Lifecycle stage of network development |
+| Sustainability | Economic viability (earned/spent > 1.0) |
+| Preferential Attachment | Topology algorithm favoring high-fitness nodes |
+| Fitness Score | Weighted capability score for node selection |
+| Genesis Sunset | Graceful retirement of bootstrap nodes |
+| P2P Independence | Fully decentralized network operation |
+
+## Version History
+
+### v1.0.0 (2025-12-31)
+- ✅ Initial release
+- ✅ Complete 4-phase lifecycle simulation
+- ✅ Economic model with sustainability tracking
+- ✅ Automatic validation framework
+- ✅ JSON report generation
+- ✅ Comprehensive documentation
+
+## Contact & Support
+
+For issues, questions, or contributions:
+1. Check this documentation first
+2. Review source code comments
+3. Consult Edge-Net architecture docs
+4. Refer to RuVector project documentation
+
+---
+
+**Navigation Tips:**
+- Use Ctrl+F to search within documents
+- All links are relative and work in GitHub/VSCode
+- Start with PROJECT_SUMMARY.md for quickest orientation
+- SIMULATION_OVERVIEW.md for technical deep dive
+- USAGE.md for practical how-to guides
+
+**Last Updated:** 2025-12-31
+**Documentation Version:** 1.0.0