admin/ruflo

0 Fork 0

mirror of https://github.com/ruvnet/ruflo.git synced 2026-11-02 10:08:19 +09:00

Table of Contents

Hive-Mind Consensus

Topologies

Hierarchical
Mesh
Hierarchical-Mesh (Hybrid)
Ring
Star
Adaptive

Consensus Strategies

Byzantine Fault-Tolerant (BFT)
Raft
Gossip (Epidemic)
CRDT (Conflict-Free Replicated Data Type)
Quorum

Hive-Mind Operations

Initialize
Join the Collective
Spawn Workers Directly
Broadcast Message
Consensus Proposal
Memory (Shared State)
Status & Health
Shutdown Gracefully

Example: Code Review Swarm
Trade-offs
Performance Metrics

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Hive-Mind Consensus

Ruflo supports queen-led Byzantine fault-tolerant consensus across agent swarms.

Topologies

Hierarchical

Queen (central coordinator) assigns tasks and collects results
Workers execute tasks and report back to Queen
Anti-drift control: Queen maintains authoritative state
Best for: Small teams (6–8 agents), tight coordination needed

        Queen
        /  |  \
    W1  W2  W3  W4

npx ruflo@latest hive-mind init --topology hierarchical --queen-id coordinator

Mesh

Fully connected: Every agent talks to every other agent
Peer-to-peer: No central authority
Consensus via gossip: Eventual consistency
Best for: Decentralized teams, high autonomy

    W1 ↔ W2
    ↕   ↕
    W3 ↔ W4

npx ruflo@latest hive-mind init --topology mesh

Hierarchical-Mesh (Hybrid)

Queen coordinates specialist clusters
Clusters are mesh-connected internally
Best for: Large teams (10–15 agents), mixed coordination needs

         Queen
        /      \
    Cluster1  Cluster2
    /  |  \    / |  \
   W1 W2 W3  W4 W5 W6

Ring

Linear chain: W1 → W2 → W3 → W4 → W1
Low latency for sequential operations
Best for: Pipeline-style workflows

Star

Central hub (not a Queen)
All workers connect to hub
Less strict than hierarchical (hub doesn't command)

Adaptive

Topology switches based on load
Hierarchical when coordinating
Mesh when parallelizing
Best for: Unknown workloads

Consensus Strategies

Byzantine Fault-Tolerant (BFT)

Tolerates f < n/3 faulty nodes (traditional Byzantine assumption):

npx ruflo@latest hive-mind init \
  --topology hierarchical-mesh \
  --consensus byzantine \
  --max-agents 9

With 9 agents: tolerates up to 2 malicious/crashed agents.

Algorithm: PBFT (Practical Byzantine Fault Tolerance)

Multiple rounds of voting
Quorum requirement: 2/3 + 1
Latency: O(n) message rounds

Raft

Leader-based consensus, tolerates f < n/2 faulty nodes:

npx ruflo@latest hive-mind init \
  --topology hierarchical \
  --consensus raft \
  --max-agents 5

Algorithm: Raft (Diego Ongaro, Mendus Housley)

Single leader elected via majority vote
Followers replicate leader's state
Re-election on leader failure

Better for: Synchronous, reliable networks

Gossip (Epidemic)

Asynchronous, eventual consistency:

npx ruflo@latest hive-mind init \
  --topology mesh \
  --consensus gossip

Algorithm: Anti-entropy + push/pull

Agents periodically exchange state
State propagates exponentially
No strong consistency guarantee (but fast)

Better for: Unreliable networks, high latency tolerance

CRDT (Conflict-Free Replicated Data Type)

No coordination needed; conflicts resolved by merge semantics:

npx ruflo@latest hive-mind init \
  --consensus crdt

Examples: Last-write-wins, OR-sets, LWW-registers

Every agent has a local copy
Updates are locally visible immediately
Automatic conflict resolution
No quorum required

Better for: Offline-first, high availability

Quorum

Configurable voting threshold (flexible):

npx ruflo@latest hive-mind init \
  --consensus quorum \
  --quorum-preset majority  # 50% + 1

Presets:

unanimous — All agents must agree
majority — > 50% must agree (default)
supermajority — > 66% must agree

Hive-Mind Operations

Initialize

npx ruflo@latest hive-mind init \
  --topology hierarchical-mesh \
  --max-agents 10 \
  --queen-id queen-agent \
  --consensus raft

Join the Collective

npx ruflo@latest hive-mind join \
  --agent-id worker-1 \
  --role worker  # "worker" | "specialist" | "scout"

Spawn Workers Directly

npx ruflo@latest hive-mind spawn \
  --count 4 \
  --role worker \
  --prefix hive-worker

Broadcast Message

Send message to all workers:

npx ruflo@latest hive-mind broadcast \
  --message "Run security audit" \
  --priority critical

Consensus Proposal

Propose a decision for the collective to vote on:

npx ruflo@latest hive-mind consensus propose \
  --type "upgrade-dependency" \
  --value '{"package":"express","version":"4.18.2"}' \
  --strategy raft

Workers vote:

npx ruflo@latest hive-mind consensus vote \
  --proposal-id "prop-123" \
  --voter worker-1 \
  --vote true  # or false

Check status:

npx ruflo@latest hive-mind consensus status --proposal-id "prop-123"

Memory (Shared State)

All agents can read/write shared memory:

# Write to shared state
npx ruflo@latest hive-mind memory set \
  --key "deployment-status" \
  --value "in-progress"

# Read from shared state
npx ruflo@latest hive-mind memory get \
  --key "deployment-status"

# List all shared state
npx ruflo@latest hive-mind memory list

Status & Health

npx ruflo@latest hive-mind status

npx ruflo@latest hive-mind health \
  --swarm-id hive-1

Shutdown Gracefully

npx ruflo@latest hive-mind shutdown \
  --graceful true  # Wait for pending tasks

Example: Code Review Swarm

Spawn a queen + 4 reviewer agents:

// Initialize hive
await hiveMind.init({
  topology: "hierarchical",
  consensus: "raft",
  maxAgents: 5
})

// Spawn queen
Task({
  prompt: "You are the code review queen. Coordinate PRs among reviewers.",
  subagent_type: "pr-manager",
  name: "queen",
  run_in_background: true
})

// Spawn 4 reviewers
for (let i = 0; i < 4; i++) {
  Task({
    prompt: "Review the PR assigned by the queen. SendMessage results to queen when done.",
    subagent_type: "reviewer",
    name: `reviewer-${i}`,
    run_in_background: true
  })
}

// Broadcast PR to review
SendMessage({
  to: "queen",
  summary: "PR #123 ready for review",
  message: "[PR details]"
})

The queen:

Receives PR assignment
Broadcasts to all reviewers (via gossip/mesh)
Collects votes (via consensus proposal)
Reports final decision

Trade-offs

Strategy	Latency	Consistency	Fault Tolerance	Messaging	Best For
BFT	High	Strong	f < n/3	O(n²)	Security-critical
Raft	Medium	Strong	f < n/2	O(n)	Production
Gossip	Low	Eventual	f < n	O(n log n)	Large, unreliable nets
CRDT	Low	Eventual	f = n	O(1)	Offline-first, high-availability

Performance Metrics

Check consensus health:

npx ruflo@latest hive-mind consensus engine-stats

Output:

Consensus Strategy: raft
Total Proposals: 127
Approved: 124 (97.6%)
Rejected: 2
Timed Out: 1

Average Consensus Time: 45ms
P95 Consensus Time: 120ms
P99 Consensus Time: 250ms

Network Messages: 1,847
Replication Lag: 0ms (followers)
Leader Uptime: 99.94%