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/USAGE.md
+++ b/examples/edge-net/sim/USAGE.md
@@ -0,0 +1,426 @@
+# Edge-Net Lifecycle Simulation - Usage Guide
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd /workspaces/ruvector/examples/edge-net/sim
+npm install
+```
+
+### 2. Run Full Simulation
+
+```bash
+# Standard simulation (120K nodes, ~2-5 minutes)
+npm run simulate
+
+# Fast mode (faster node spawning, ~1-2 minutes)
+npm run simulate:fast
+
+# Verbose mode (detailed tick-by-tick output)
+npm run simulate:verbose
+```
+
+### 3. View Results
+
+Results are saved to `simulation-report.json` in the sim directory.
+
+## Command Line Options
+
+```bash
+# Custom output file
+node --loader ts-node/esm src/simulator.ts --output=custom-report.json
+
+# Combine options
+node --loader ts-node/esm src/simulator.ts --fast --output=fast-run.json
+```
+
+Available options:
+- `--fast` / `-f`: Faster node spawning (100 nodes/tick vs 10)
+- `--verbose` / `-v`: Detailed tick-by-tick progress
+- `--output=FILE`: Custom output file path
+
+## Understanding the Output
+
+### Console Output
+
+```
+╔════════════════════════════════════════════════════════════╗
+║    EDGE-NET LIFECYCLE SIMULATION - Starting...            ║
+╚════════════════════════════════════════════════════════════╝
+
+⚙️  Configuration:
+   Genesis Nodes: 100
+   Target Nodes: 120,000
+   Nodes/Tick: 10
+   Mode: NORMAL
+
+🌱 Genesis nodes deployed. Starting simulation...
+
+[Progress Bar]
+
+🔄 PHASE TRANSITION: genesis → growth (10,000 nodes)
+  → Genesis nodes reducing 10x multiplier...
+
+🔄 PHASE TRANSITION: growth → maturation (50,000 nodes)
+  → Genesis nodes entering READ-ONLY mode...
+
+🔄 PHASE TRANSITION: maturation → independence (100,000 nodes)
+  → Genesis nodes RETIRED. Network is independent!
+
+✨ Simulation complete!
+
+   Total Ticks: 12,500
+   Duration: 45.23s
+   Final Nodes: 120,000
+   Final Phase: INDEPENDENCE
+```
+
+### Summary Report
+
+After simulation, you'll see:
+
+1. **Overall Summary**
+   - Duration and tick count
+   - Final node count and phase
+   - Pass/fail status for each phase
+
+2. **Phase Results**
+   - Node growth (start → end)
+   - Energy economics (sustainability ratio)
+   - Task completion and success rates
+
+3. **Top Performers**
+   - Highest earning nodes
+   - Task completion leaders
+   - Success rate champions
+
+4. **Validation Results**
+   - Critical issues (failures)
+   - Warnings (potential issues)
+   - Successes (passed validations)
+
+### JSON Report Structure
+
+```json
+{
+  "metadata": {
+    "timestamp": "2025-12-31T...",
+    "simulationVersion": "1.0.0",
+    "duration": 45234,
+    "totalTicks": 12500
+  },
+  "summary": {
+    "phasesCompleted": 4,
+    "totalPassed": true,
+    "phasesPassed": 4,
+    "phasesTotal": 4,
+    "finalNodeCount": 120000,
+    "finalPhase": "independence"
+  },
+  "phases": {
+    "genesis": {
+      "phase": "genesis",
+      "startTick": 0,
+      "endTick": 1000,
+      "duration": 1000,
+      "nodeCount": {
+        "start": 100,
+        "end": 10000,
+        "peak": 10000
+      },
+      "energy": {
+        "totalEarned": 15234.50,
+        "totalSpent": 6234.20,
+        "netEnergy": 9000.30,
+        "avgPerNode": 1.52,
+        "sustainability": 2.44
+      },
+      "genesis": {
+        "avgMultiplier": 10.0,
+        "activeCount": 100,
+        "readOnlyCount": 0,
+        "retiredCount": 0
+      },
+      "network": {
+        "avgConnections": 15.2,
+        "avgSuccessRate": 0.853,
+        "taskThroughput": 45.678,
+        "tasksCompleted": 45678
+      },
+      "validation": {
+        "passed": true,
+        "reasons": [
+          "✓ Genesis multiplier active: 10.00x",
+          "✓ Energy accumulated: 15234.50 rUv",
+          "✓ Network connected: 15.20 avg connections"
+        ]
+      }
+    },
+    // ... other phases
+  },
+  "validation": {
+    "overallPassed": true,
+    "criticalIssues": [],
+    "warnings": [],
+    "successes": [...]
+  }
+}
+```
+
+## Phase Details
+
+### Phase 1: Genesis (0 - 10K nodes)
+
+**What happens:**
+- 100 genesis nodes form initial network
+- Genesis nodes have 10x energy multiplier
+- Network establishes basic topology
+- Nodes connect via preferential attachment
+
+**Validation criteria:**
+- ✅ Genesis multiplier ≈ 10.0x
+- ✅ Energy accumulation > 1000 rUv
+- ✅ Network connectivity (avg connections > 5)
+
+**Typical duration:** ~1,000 ticks
+
+### Phase 2: Growth (10K - 50K nodes)
+
+**What happens:**
+- Genesis multiplier decays from 10x → 1x
+- Genesis nodes stop accepting new connections
+- Network self-organizes around regular nodes
+- Task routing optimizes based on node fitness
+
+**Validation criteria:**
+- ✅ Genesis activity reduction
+- ✅ Multiplier decay (< 5.0x by end)
+- ✅ Task success rate > 70%
+
+**Typical duration:** ~4,000 ticks
+
+### Phase 3: Maturation (50K - 100K nodes)
+
+**What happens:**
+- Genesis nodes enter READ-ONLY mode
+- Network operates independently
+- Economic sustainability achieved
+- Adaptive security learning
+
+**Validation criteria:**
+- ✅ Genesis nodes > 80% read-only
+- ✅ Economic sustainability (earned/spent > 1.0)
+- ✅ Network connectivity > 10 avg connections
+
+**Typical duration:** ~5,000 ticks
+
+### Phase 4: Independence (100K+ nodes)
+
+**What happens:**
+- Genesis nodes fully RETIRED
+- Pure P2P operation
+- Long-term stability verification
+- Economic equilibrium
+
+**Validation criteria:**
+- ✅ Genesis nodes > 90% retired
+- ✅ Pure P2P (multiplier ≈ 1.0)
+- ✅ Network stability (positive net energy)
+
+**Typical duration:** ~2,500 ticks
+
+## Customizing the Simulation
+
+### Modify Network Parameters
+
+Edit `src/simulator.ts`:
+
+```typescript
+this.network = new Network({
+  genesisNodeCount: 100,        // Initial genesis count
+  targetNodeCount: 120000,      // Total nodes to spawn
+  nodesPerTick: 10,             // Growth rate
+  taskGenerationRate: 5,        // Tasks per node
+  baseTaskReward: 1.0,          // Energy reward
+  connectionCost: 0.5,          // Connection energy cost
+  maxConnectionsPerNode: 50,    // Max connections
+});
+```
+
+### Test Smaller Networks
+
+For faster testing:
+
+```typescript
+const network = new Network({
+  genesisNodeCount: 50,
+  targetNodeCount: 20000,
+  nodesPerTick: 100,
+});
+```
+
+### Adjust Phase Thresholds
+
+Edit `src/phases.ts`:
+
+```typescript
+[NetworkPhase.GROWTH, {
+  minNodes: 10000,  // Phase starts at 10K
+  maxNodes: 50000,  // Phase ends at 50K
+  customCheck: (net: Network) => {
+    // Custom validation logic
+  },
+}]
+```
+
+## Interpreting Results
+
+### Success Indicators
+
+✅ **All phases passed validation**
+- Genesis multiplier worked as expected
+- Economic sustainability achieved
+- Network remained connected
+- Genesis sunset completed successfully
+
+✅ **High success rates (> 70%)**
+- Task routing is effective
+- Node capabilities are well-matched
+- Network is healthy
+
+✅ **Positive net energy**
+- More energy earned than spent
+- Network is economically viable
+- Sustainable long-term
+
+### Warning Signs
+
+⚠️ **Low success rates (< 70%)**
+- Task routing may need optimization
+- Node capabilities mismatch
+- Network congestion
+
+⚠️ **Economic sustainability < 1.0**
+- Network losing energy
+- Not sustainable long-term
+- May need reward adjustments
+
+⚠️ **Low connectivity (< 5 avg connections)**
+- Network fragmentation risk
+- Poor resilience
+- Communication bottlenecks
+
+### Critical Issues
+
+❌ **Phase validation failures**
+- Genesis multiplier not working
+- Phase transitions not triggering
+- Network instability
+
+❌ **Negative net energy**
+- Network is losing resources
+- Economic model broken
+- Unsustainable
+
+❌ **Genesis retirement failed**
+- Genesis nodes not retiring
+- Network dependent on genesis
+- Independence not achieved
+
+## Performance Tips
+
+### Faster Simulations
+
+1. **Use fast mode:**
+   ```bash
+   npm run simulate:fast
+   ```
+
+2. **Reduce target node count:**
+   ```typescript
+   targetNodeCount: 50000  // Instead of 120000
+   ```
+
+3. **Increase nodes per tick:**
+   ```typescript
+   nodesPerTick: 100  // Instead of 10
+   ```
+
+### More Detailed Analysis
+
+1. **Use verbose mode:**
+   ```bash
+   npm run simulate:verbose
+   ```
+
+2. **Lower progress interval:**
+   ```typescript
+   this.progressInterval = 10;  // Update every 10 ticks
+   ```
+
+3. **Add custom logging:**
+   ```typescript
+   // In simulator.ts
+   if (this.network.currentTick % 100 === 0) {
+     console.log('Custom metrics:', ...);
+   }
+   ```
+
+## Troubleshooting
+
+### Simulation hangs
+
+- Check timeout (max 50,000 ticks)
+- Reduce target node count
+- Increase nodes per tick
+
+### Out of memory
+
+- Reduce target node count
+- Increase node spawn rate (fewer total ticks)
+- Run in fast mode
+
+### TypeScript errors
+
+```bash
+npm run build
+```
+
+### Module errors
+
+```bash
+npm install
+```
+
+## Integration with Edge-Net
+
+This simulation validates the edge-net architecture:
+
+1. **Genesis Phase** - Corresponds to initial E2B swarm deployment
+2. **Growth Phase** - Network expansion with guided self-organization
+3. **Maturation** - Full autonomy with genesis oversight reduction
+4. **Independence** - Pure P2P operation, genesis retired
+
+Use simulation results to:
+- Validate economic parameters
+- Test phase transition logic
+- Verify sustainability thresholds
+- Optimize network topology
+- Tune genesis sunset timing
+
+## Next Steps
+
+1. Run the simulation
+2. Analyze the JSON report
+3. Adjust parameters if needed
+4. Test different scenarios
+5. Integrate findings into edge-net design
+
+## Support
+
+For issues or questions about the simulation, refer to:
+- `/workspaces/ruvector/examples/edge-net/sim/README.md`
+- Edge-net architecture documentation
+- RuVector project documentation