saorsa-core Cursor Rules

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 🤖 MANDATORY SUBAGENT USAGE

**ALWAYS USE SUBAGENTS. THIS IS NOT OPTIONAL.**

Subagents (via the `Task` tool) MUST be used whenever possible. They provide:
- **Fresh context** - Each subagent starts clean, preventing context pollution
- **Parallel execution** - Multiple agents can work simultaneously
- **Specialization** - Purpose-built agents for specific tasks
- **Unbounded execution** - No context limits when chaining agents

### When to Spawn Subagents

| Task Type | Action |
|-----------|--------|
| Code exploration/search | Spawn `Explore` agent |
| Code review | Spawn review agents in parallel |
| Bug fixes | Spawn `code-fixer` agent |
| Test execution | Spawn `test-runner` agent |
| Build validation | Spawn `build-validator` agent |
| Security scanning | Spawn `security-scanner` agent |
| Documentation audit | Spawn `documentation-auditor` agent |
| Multi-step tasks | Spawn `dev-agent` or `general-purpose` agent |
| Complex research | Spawn `Explore` or `general-purpose` agent |

### Subagent Rules

1. **PREFER subagents over doing work directly** - Even for "simple" tasks
2. **PARALLELIZE when possible** - Spawn multiple agents in a single message
3. **Use background agents** for long-running tasks (`run_in_background: true`)
4. **Chain agents** for complex workflows - Output of one feeds the next
5. **Never accumulate context** - Delegate to fresh agents instead

**IF YOU CAN USE A SUBAGENT, YOU MUST USE A SUBAGENT.**

## Build and Development Commands

### Core Commands
```bash
# Build
cargo build                         # Debug build
cargo build --release               # Release build
cargo build --all-features          # Build with all features

# Tests - MUST ALL PASS before committing
cargo test                          # Run all tests
cargo test --lib                    # Unit tests only
cargo test --test '<test_name>'     # Specific integration test
cargo test test_function_name       # Run specific test by name
cargo test -- --nocapture           # Show println! output
RUST_LOG=debug cargo test           # With debug logging

# Code Quality - MUST PASS before committing
cargo fmt                           # Format code
cargo clippy -- -D warnings -D clippy::unwrap_used -D clippy::expect_used  # Strict linting
cargo audit                         # Security vulnerability check

# Benchmarks
cargo bench                         # Run all benchmarks
cargo bench --bench dht_benchmark  # Run specific benchmark

# Documentation
cargo doc --open                    # Build and open documentation

# Local CI Pipeline (safe, read-only checks)
./scripts/local_ci.sh               # Run full CI pipeline locally
./scripts/check_no_panic_unwrap.sh  # Check for forbidden patterns
```

### Trust System Tests
```bash
# Trust engine unit tests (in src/adaptive/)
cargo test --lib trust
cargo test --lib adaptive::dht
```

## Critical Code Standards

### NO PANICS IN PRODUCTION CODE - ZERO TOLERANCE
Production code **MUST NOT** contain:
- `.unwrap()` - Use `?` operator or `.ok_or()`
- `.expect()` - Use `.context()` from `anyhow` instead  
- `panic!()` - Return `Result` instead
- `unimplemented!()` or `todo!()` - Complete all implementations
- `println!()` - Use `tracing` for logging

**Exception**: Test code (`#[cfg(test)]`) may use `.unwrap()` and `.expect()` for assertions.

### Error Handling Pattern
```rust
// ✅ CORRECT
let value = some_option.ok_or(P2PError::MissingValue)?;
let result = some_result.context("operation failed")?;

// ❌ WRONG - Will fail CI/CD
let value = some_option.unwrap();
let result = some_result.expect("failed");
```

## Architecture Overview

### DHT Phonebook + Trust Signals

The current direction is to use **saorsa-core** for peer discovery and trust, and keep
all application data and business logic in **saorsa-node**. In practice:

- **DHT is a peer phonebook only** (peer records, routing, discovery).
- **Chunk storage/retrieval is done via `send_message`** in saorsa-node.
- **Trust updates remain in saorsa-core**: saorsa-node reports data availability
  outcomes so the TrustEngine can downscore nodes that fail to serve expected data.
  All trust signals flow through `AdaptiveDHT`.

Example trust signal hook:
```rust
use saorsa_core::TrustEvent;

// Core only records penalties — rewards are the consumer's responsibility
node.report_trust_event(&peer_id, TrustEvent::ApplicationSuccess(1.0)).await;
node.report_trust_event(&peer_id, TrustEvent::ApplicationFailure(1.0)).await;
```

### Multi-Layer P2P Architecture

The system combines a DHT peer phonebook with machine learning for optimal routing:

#### 1. Transport Layer (`src/transport/`)
- **Primary**: `saorsa-transport` (0.8+) for QUIC transport with NAT traversal
- **Security**: Post-quantum cryptography (ML-DSA-65, ML-KEM-768)

#### 2. Adaptive Network Layer (`src/adaptive/`)
Trust boundary and adaptive routing:
- **AdaptiveDHT**: Sole owner of TrustEngine and DhtNetworkManager — all trust signals flow through here
- **TrustEngine**: Response-rate scoring with time decay for decentralized reputation
- **TrustEvent**: Unified enum for all trust-relevant outcomes (reported via `P2PNode::report_trust_event`)
- **Lazy swap-out**: Peers below swap threshold are replaced when better candidates arrive (no immediate blocking)

#### 3. DHT Layer (`src/dht/`)
Peer phonebook with geographic awareness (no data storage):
- **Core Engine**: Kademlia-based routing table and peer discovery
- **Geographic Routing**: Region-aware peer selection
- **Trust-Based Swap-Out**: Peers below swap threshold are replaced by better candidates during admission

## External Crate Dependencies

### Saorsa Ecosystem
- `saorsa-pqc` (0.5): Post-quantum cryptography
- `saorsa-transport` (0.25+): QUIC transport with NAT traversal and PQC

### Feature Flags

No feature flags — all functionality is always enabled.

## Testing Infrastructure

### Test Organization
- **Unit Tests**: In-module `#[cfg(test)]` blocks

### Key Tests
```bash
# All unit tests (includes DHT, trust, transport, security)
cargo test --lib
```

## Important Implementation Details

### DHT Configuration
- **Bucket Size**: 20 nodes per k-bucket
- **Concurrency**: Alpha=3 parallel lookups
- **Geographic Awareness**: Region-aware peer selection
- **Trust Integration**: Response-rate scoring with lazy swap-out (no blocking)

### Performance Optimizations
- **Connection Pooling**: Max 100 connections with LRU eviction
- **Message Batching**: 10ms window, 64KB max batch
- **Caching**: LRU caches throughout with configurable TTL
- **Hashing**: BLAKE3 for speed, SHA2 for compatibility

## Licensing

Dual-licensed:
- **AGPL-3.0**: For open source use
- **Commercial**: Contact [email protected]

All files must include the copyright header with dual-licensing notice.

---

## 🚨 CRITICAL: Saorsa Network Infrastructure & Port Isolation

### Infrastructure Documentation
Full infrastructure documentation is available at: `docs/infrastructure/INFRASTRUCTURE.md`

This includes:
- All 9 VPS nodes across 3 cloud providers (DigitalOcean, Hetzner, Vultr)
- Bootstrap node endpoints and IP addresses
- Firewall configurations and SSH access
- Systemd service templates

### ⚠️ PORT ALLOCATION

saorsa-core is a library used by multiple applications. Each application uses a dedicated port range:

| Service | UDP Port Range | Default | Description |
|---------|----------------|---------|-------------|
| saorsa-transport | 9000-9999 | 9000 | QUIC transport layer |
| **saorsa-node** | **10000-10999** | **10000** | Core P2P network nodes (primary user of saorsa-core) |
| communitas | 11000-11999 | 11000 | Collaboration platform nodes |

### 🛑 DO NOT DISTURB OTHER NETWORKS

When testing saorsa-core functionality:

1. **Use ports 10000-10999** for saorsa-node services
2. **NEVER** kill processes on ports 9000-9999 or 11000-11999
3. **NEVER** restart services outside our port range
4. Each network may be running independent tests - respect port boundaries

```bash
# ✅ CORRECT - saorsa-node operations (within 10000-10999)
cargo run --bin saorsa-node -- --listen 0.0.0.0:10000
cargo run --bin saorsa-node -- --listen 0.0.0.0:10001  # Second instance OK
ssh [email protected] "systemctl restart saorsa-node-bootstrap"

# ❌ WRONG - Would disrupt other networks
ssh [email protected] "pkill -f ':9'"    # NEVER - matches saorsa-transport ports
ssh [email protected] "pkill -f ':11'"   # NEVER - matches communitas ports
```

### Bootstrap Endpoints
```
saorsa-2.saorsalabs.com:10000  (NYC - 142.93.199.50)
saorsa-3.saorsalabs.com:10000  (SFO - 147.182.234.192)
```

### Before Any VPS Operations
1. Verify you're targeting the correct port for your application
2. Double-check service names match your application
3. Never run broad `pkill` commands that could affect other services