SAMUHA समूह
Scalably-Aware Mesh-Unified Heterogeneous Architect
Three-state peer admission with priority scoring, utilization-aware capacity gating, and graceful REDIRECT eviction.
v3.5.10 • Layer 17.5The Assembly That Governs Entry
A samuha is an assembly or group — a collective that decides who may join and under what conditions. In yakmesh, SAMUHA replaces the old binary admit/reject gate with a ternary verdict system: ADMIT, HOLD, or REDIRECT. Instead of hard rejections that waste resources on both sides, peers that cannot be immediately admitted are either held in a waiting queue (during transient overload) or gracefully redirected to neighbor nodes with spare capacity. No legitimate peer is wasted; no overloaded node is overwhelmed.
SAMUHA & KARMA
KARMA tracks peer reputation over time — assigning trust scores based on behavior history. SAMUHA consumes KARMA scores as a major input to the priority formula: peers with higher KARMA get preferential admission. Think of KARMA as the credit score; SAMUHA is the admissions committee.
Ternary Verdicts
Every incoming peer connection receives one of three verdicts:
ADMIT
Capacity available. Peer passes priority threshold. Connection accepted immediately.
HOLD
Temporarily at capacity. Peer queued for 30s. Re-evaluated on next slot opening.
REDIRECT
At hard capacity. Peer given alternative node addresses. Graceful handoff, not rejection.
Priority Formula
SAMUHA calculates a composite priority score for each incoming peer to determine admission order when capacity is constrained:
| Factor | Weight | Description |
|---|---|---|
| karma | 0.3 | KARMA trust score (0.0–1.0) from peer history |
| hw | 0.3 | Hardware capability score — GPU/NPU TOPS normalized |
| returning | 0.2 | 1.0 if previously connected, 0.0 if new — loyalty bonus |
| mani | 0.2 | MANI phase alignment (Kuramoto) — phase-coherent peers preferred |
Utilization Thresholds
SAMUHA gates admission based on the node’s current utilization ratio (active peers / max capacity):
| Utilization | Verdict | Behavior |
|---|---|---|
| < 0.8 | ADMIT | Immediate admission for any peer above minimum priority |
| 0.8 – 1.0 | HOLD | Peer waits in HOLD queue (depth 10, 30s timeout) for the next open slot |
| ≥ 1.0 | REDIRECT | Node at hard limit. A higher-priority incoming peer may bump the lowest-priority peer; otherwise the peer is redirected to a neighbor with capacity |
REDIRECT Eviction Flow
When a node reaches hard capacity, SAMUHA doesn’t simply refuse connections. It performs graceful redirection:
- Capacity check: Active peers ≥ max capacity confirmed
- Neighbor scan: Query mesh neighbors for their current utilization
- Best candidate: Select neighbor with lowest utilization that has capacity
- REDIRECT response: Send peer the alternative node’s address + signed referral token
- Verification: Target node validates referral token (prevents abuse)
- Telemetry: REDIRECT event logged for KARMA scoring — redirected peers that connect successfully boost both nodes’ scores
Safety Limits
Hard safety limits prevent resource exhaustion and abuse:
| Limit | Value | Purpose |
|---|---|---|
| Burst rate | 30 / min | Connection spike that triggers a burst alert — per-IP limits are stricter (10 conn/min, 5 handshakes/min) |
| Max handshakes | 50 | Maximum concurrent handshakes (pending + active) |
| HOLD timeout | 30s | Max time a peer waits in HOLD queue before auto-REDIRECT |
| HOLD queue depth | 10 | Max peers waiting in HOLD — overflow gets immediate REDIRECT |
API Endpoints
| Endpoint | Description |
|---|---|
GET /api/samuha |
SAMUHA status: utilization, active peers, HOLD queue depth, verdicts issued |
GET /api/peers |
Connected peers with admission verdict, priority score, and connection time |
Provenance full version history →
Introduced in v3.3.0 — Initial implementation: ternary ADMIT/HOLD/REDIRECT verdicts, composite priority formula (karma+hw+returning+mani), utilization-based capacity gating, lowest-priority eviction upgrade, burst detection, handshake concurrency limits.
- v3.5.5 — Completed the design: real HOLD queue (depth 10, 30s timeout, promote-on-slot-open with full re-verification), signed referral tokens on REDIRECT with referrer validation,
GET /api/samuhaandGET /api/peerssurfaces, admission verdict + priority recorded per peer