@claude-flow/swarm 3.0.0-alpha.1 → 3.0.0-alpha.7

package/src/consensus/gossip.ts

@@ -4,6 +4,7 @@
  */
 
 import { EventEmitter } from 'events';
+import type { ConsensusTransport, ConsensusMessage } from './transport.js';
 import {
   ConsensusProposal,
   ConsensusVote,
@@ -24,12 +25,50 @@ export interface GossipMessage {
   path: string[];
 }
 
+/**
+ * Bounded set that evicts oldest entries when capacity is reached.
+ * Uses Map insertion-order for O(1) FIFO eviction. (PERF-01)
+ */
+export class BoundedSet<T> {
+  private map = new Map<T, true>();
+  private readonly maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  has(value: T): boolean {
+    return this.map.has(value);
+  }
+
+  add(value: T): void {
+    if (this.map.has(value)) return;
+
+    if (this.map.size >= this.maxSize) {
+      // Evict oldest (first inserted)
+      const oldest = this.map.keys().next().value;
+      if (oldest !== undefined) {
+        this.map.delete(oldest);
+      }
+    }
+    this.map.set(value, true);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+}
+
 export interface GossipNode {
   id: string;
   state: Map<string, unknown>;
   version: number;
   neighbors: Set<string>;
-  seenMessages: Set<string>;
+  seenMessages: BoundedSet<string>;
   lastSync: Date;
 }
 
@@ -38,6 +77,14 @@ export interface GossipConfig extends Partial<ConsensusConfig> {
   gossipIntervalMs?: number;
   maxHops?: number;
   convergenceThreshold?: number;
+  /**
+   * ADR-095 G2 — optional pluggable transport. When set, gossip messages
+   * to neighbors actually go over it (signed if the transport has a
+   * keypair) and inbound gossip is routed back into the merge logic.
+   * When unset, behavior is unchanged: the legacy in-process path mutates
+   * the local `nodes` map directly (single-process).
+   */
+  transport?: ConsensusTransport;
 }
 
 export class GossipConsensus extends EventEmitter {
@@ -48,6 +95,7 @@ export class GossipConsensus extends EventEmitter {
   private messageQueue: GossipMessage[] = [];
   private gossipInterval?: NodeJS.Timeout;
   private proposalCounter: number = 0;
+  private readonly transport?: ConsensusTransport;
 
   constructor(nodeId: string, config: GossipConfig = {}) {
     super();
@@ -60,16 +108,46 @@ export class GossipConsensus extends EventEmitter {
       gossipIntervalMs: config.gossipIntervalMs ?? 100,
       maxHops: config.maxHops ?? 10,
       convergenceThreshold: config.convergenceThreshold ?? 0.9,
+      transport: config.transport,
     };
+    this.transport = config.transport;
 
     this.node = {
       id: nodeId,
       state: new Map(),
       version: 0,
       neighbors: new Set(),
-      seenMessages: new Set(),
+      seenMessages: new BoundedSet(100_000), // PERF-01: ~4MB cap (100K × ~40B IDs)
       lastSync: new Date(),
     };
+
+    if (this.transport) {
+      this.transport.onMessage(async (msg: ConsensusMessage) => this.handleInboundGossipMessage(msg));
+    }
+  }
+
+  /**
+   * ADR-095 G2 — route an inbound transport message into the gossip merge
+   * logic. The transport handles signature verification (if enabled). We
+   * dedupe by message id (the BoundedSet `seenMessages`) and process it as
+   * though it arrived from a neighbor.
+   */
+  private async handleInboundGossipMessage(msg: ConsensusMessage): Promise<void> {
+    if (msg.type !== 'gossip') return;
+    const gm = msg.payload as GossipMessage | undefined;
+    if (!gm || typeof gm.id !== 'string') return;
+    if (this.node.seenMessages.has(gm.id)) return;
+    // Ensure the sender is known as a neighbor so processReceivedMessage works.
+    if (!this.nodes.has(msg.from)) {
+      this.nodes.set(msg.from, { id: msg.from, state: new Map(), version: 0, neighbors: new Set(), seenMessages: new BoundedSet(100_000), lastSync: new Date() });
+    }
+    this.node.neighbors.add(msg.from);
+    // Process against THIS node's state (the message reached us).
+    await this.processReceivedMessage(this.node, {
+      ...gm,
+      timestamp: gm.timestamp ? new Date(gm.timestamp as unknown as string) : new Date(),
+      path: Array.isArray(gm.path) ? gm.path : [],
+    });
   }
 
   async initialize(): Promise<void> {
@@ -90,7 +168,7 @@ export class GossipConsensus extends EventEmitter {
       state: new Map(),
       version: 0,
       neighbors: new Set(),
-      seenMessages: new Set(),
+      seenMessages: new BoundedSet(100_000), // PERF-01: bounded to prevent memory leak (~4MB cap)
       lastSync: new Date(),
     });
 
@@ -276,26 +354,34 @@ export class GossipConsensus extends EventEmitter {
   }
 
   private async sendToNeighbor(neighborId: string, message: GossipMessage): Promise<void> {
-    const neighbor = this.nodes.get(neighborId);
-    if (!neighbor) {
-      return;
-    }
-
-    // Check if already seen
-    if (neighbor.seenMessages.has(message.id)) {
-      return;
-    }
-
-    // Simulate network delivery
     const deliveredMessage: GossipMessage = {
       ...message,
       hops: message.hops + 1,
       path: [...message.path, neighborId],
     };
 
-    // Process at neighbor
-    await this.processReceivedMessage(neighbor, deliveredMessage);
+    // ADR-095 G2 — over the transport when wired: actually send the gossip
+    // message to the neighbor (signed by the transport if signing is on).
+    // The emit stays for observability.
+    if (this.transport) {
+      this.emit('message.sent', { to: neighborId, message: deliveredMessage });
+      try {
+        await this.transport.send(neighborId, {
+          type: 'gossip',
+          payload: { ...deliveredMessage, timestamp: deliveredMessage.timestamp.toISOString() },
+        });
+      } catch {
+        // Unreachable neighbor — gossip tolerates this; it'll converge via
+        // other paths or the next gossip round.
+      }
+      return;
+    }
 
+    // Legacy in-process path — deliver to the fake neighbor state.
+    const neighbor = this.nodes.get(neighborId);
+    if (!neighbor) return;
+    if (neighbor.seenMessages.has(message.id)) return;
+    await this.processReceivedMessage(neighbor, deliveredMessage);
     this.emit('message.sent', { to: neighborId, message: deliveredMessage });
   }
 

package/src/consensus/index.ts

@@ -20,6 +20,35 @@ import { GossipConsensus, createGossipConsensus, GossipConfig } from './gossip.j
 export { RaftConsensus, ByzantineConsensus, GossipConsensus };
 export type { RaftConfig, ByzantineConfig, GossipConfig };
 
+// ADR-095 G2 — pluggable consensus transport. Replaces the implicit
+// single-process EventEmitter messaging in the consensus protocols.
+// LocalTransport is the default (matches current behavior); FederationTransport
+// (separate file, ADR-104 wire) is the multi-host one.
+export {
+  LocalTransport,
+  LocalTransportRegistry,
+  defaultLocalRegistry,
+  generateNodeKeyPair,
+  signMessage,
+  verifyMessage,
+  canonicalizeForSigning,
+  messageDigest,
+} from './transport.js';
+export type {
+  ConsensusTransport,
+  ConsensusMessage,
+  ConsensusReply,
+  ConsensusMessageHandler,
+  NodeKeyPair,
+  LocalTransportOptions,
+} from './transport.js';
+
+// ADR-095 G2 — FederationTransport: ConsensusTransport over the federation
+// plugin's ADR-104 WS wire (agentic-flow/transport/loader). Structural —
+// swarm doesn't import agentic-flow; the caller passes a transport instance.
+export { FederationTransport } from './federation-transport.js';
+export type { AgenticFlowTransportLike, FederationTransportOptions } from './federation-transport.js';
+
 type ConsensusImplementation = RaftConsensus | ByzantineConsensus | GossipConsensus;
 
 export class ConsensusEngine extends EventEmitter implements IConsensusEngine {

package/src/consensus/raft.ts

@@ -4,6 +4,7 @@
  */
 
 import { EventEmitter } from 'events';
+import type { ConsensusTransport, ConsensusMessage } from './transport.js';
 import {
   ConsensusProposal,
   ConsensusVote,
@@ -35,6 +36,15 @@ export interface RaftConfig extends Partial<ConsensusConfig> {
   electionTimeoutMinMs?: number;
   electionTimeoutMaxMs?: number;
   heartbeatIntervalMs?: number;
+  /**
+   * ADR-095 G2 — optional pluggable transport. When set, RequestVote and
+   * AppendEntries RPCs go over it (request-response) and this node also
+   * answers inbound RequestVote / AppendEntries from peers using proper
+   * Raft receiver rules (term comparison, vote-once-per-term, log-up-to-date
+   * check). When unset, behavior is unchanged: the legacy in-process path
+   * mutates the local `peers` map directly (single-process).
+   */
+  transport?: ConsensusTransport;
 }
 
 export class RaftConsensus extends EventEmitter {
@@ -45,6 +55,7 @@ export class RaftConsensus extends EventEmitter {
   private electionTimeout?: NodeJS.Timeout;
   private heartbeatInterval?: NodeJS.Timeout;
   private proposalCounter: number = 0;
+  private readonly transport?: ConsensusTransport;
 
   constructor(nodeId: string, config: RaftConfig = {}) {
     super();
@@ -56,7 +67,9 @@ export class RaftConsensus extends EventEmitter {
       electionTimeoutMinMs: config.electionTimeoutMinMs ?? 150,
       electionTimeoutMaxMs: config.electionTimeoutMaxMs ?? 300,
       heartbeatIntervalMs: config.heartbeatIntervalMs ?? 50,
+      transport: config.transport,
     };
+    this.transport = config.transport;
 
     this.node = {
       id: nodeId,
@@ -66,6 +79,71 @@ export class RaftConsensus extends EventEmitter {
       commitIndex: 0,
       lastApplied: 0,
     };
+
+    if (this.transport) {
+      this.transport.onMessage(async (msg: ConsensusMessage) => this.handleInboundRaftMessage(msg));
+    }
+  }
+
+  /** Index/term of the last entry in this node's log (Raft "up-to-date" comparison). */
+  private lastLogInfo(): { index: number; term: number } {
+    const last = this.node.log[this.node.log.length - 1];
+    return last ? { index: last.index, term: last.term } : { index: 0, term: 0 };
+  }
+
+  /**
+   * ADR-095 G2 — Raft receiver. Answers inbound RequestVote / AppendEntries
+   * with proper Raft rules. Returns the RPC response the transport relays
+   * back to the caller (the transport's `send` resolves with it).
+   */
+  private async handleInboundRaftMessage(msg: ConsensusMessage): Promise<ConsensusMessage | void> {
+    const p = (msg.payload ?? {}) as Record<string, unknown>;
+    const term = typeof p.term === 'number' ? p.term : 0;
+
+    // §5.1 — any RPC with a higher term makes us a follower and adopts it.
+    if (term > this.node.currentTerm) {
+      this.node.currentTerm = term;
+      this.node.votedFor = undefined;
+      this.node.state = 'follower';
+    }
+
+    if (msg.type === 'request-vote') {
+      const candidateId = String(p.candidateId ?? msg.from);
+      const candLastIndex = typeof p.lastLogIndex === 'number' ? p.lastLogIndex : 0;
+      const candLastTerm = typeof p.lastLogTerm === 'number' ? p.lastLogTerm : 0;
+      const my = this.lastLogInfo();
+      const logOk = candLastTerm > my.term || (candLastTerm === my.term && candLastIndex >= my.index);
+      const termOk = term >= this.node.currentTerm;
+      const notVotedOrSame = this.node.votedFor === undefined || this.node.votedFor === candidateId;
+      const granted = termOk && notVotedOrSame && logOk;
+      if (granted) {
+        this.node.votedFor = candidateId;
+        this.resetElectionTimeout();
+      }
+      return { type: 'vote-response', from: this.node.id, to: msg.from, payload: { term: this.node.currentTerm, granted }, term: this.node.currentTerm };
+    }
+
+    if (msg.type === 'append-entries') {
+      // §5.2/5.3 — reject if leader's term is stale.
+      if (term < this.node.currentTerm) {
+        return { type: 'append-entries-response', from: this.node.id, to: msg.from, payload: { term: this.node.currentTerm, success: false }, term: this.node.currentTerm };
+      }
+      // Valid leader heartbeat/append → become/stay follower, reset election timer.
+      this.node.state = 'follower';
+      this.resetElectionTimeout();
+      const entries = Array.isArray(p.entries) ? (p.entries as RaftLogEntry[]) : [];
+      // (Simplified log matching: append entries not already present by index.
+      // Full prevLogIndex/prevLogTerm conflict resolution is the next refinement.)
+      for (const e of entries) {
+        if (!this.node.log.some(x => x.index === e.index)) this.node.log.push(e);
+      }
+      const leaderCommit = typeof p.leaderCommit === 'number' ? p.leaderCommit : this.node.commitIndex;
+      if (leaderCommit > this.node.commitIndex) {
+        this.node.commitIndex = Math.min(leaderCommit, this.lastLogInfo().index);
+      }
+      return { type: 'append-entries-response', from: this.node.id, to: msg.from, payload: { term: this.node.currentTerm, success: true }, term: this.node.currentTerm };
+    }
+    return;
   }
 
   async initialize(): Promise<void> {
@@ -255,17 +333,37 @@ export class RaftConsensus extends EventEmitter {
   }
 
   private async requestVote(peerId: string): Promise<boolean> {
+    // ADR-095 G2 — over the transport when wired: real RequestVote RPC.
+    if (this.transport) {
+      const my = this.lastLogInfo();
+      try {
+        const reply = await this.transport.send(peerId, {
+          type: 'request-vote',
+          payload: { term: this.node.currentTerm, candidateId: this.node.id, lastLogIndex: my.index, lastLogTerm: my.term },
+          term: this.node.currentTerm,
+        });
+        const rp = (reply?.payload ?? {}) as Record<string, unknown>;
+        // §5.1 — if the responder's term is higher, step down.
+        if (typeof rp.term === 'number' && rp.term > this.node.currentTerm) {
+          this.node.currentTerm = rp.term;
+          this.node.votedFor = undefined;
+          this.node.state = 'follower';
+          return false;
+        }
+        return rp.granted === true;
+      } catch {
+        return false; // unreachable peer / timeout — counts as no vote.
+      }
+    }
+
+    // Legacy in-process path — mutates the local fake peer state.
     const peer = this.peers.get(peerId);
     if (!peer) return false;
-
-    // Simulate vote request (in real implementation, this would be RPC)
-    // For now, grant vote if candidate's term is higher
     if (this.node.currentTerm > peer.currentTerm) {
       peer.votedFor = this.node.id;
       peer.currentTerm = this.node.currentTerm;
       return true;
     }
-
     return false;
   }
 
@@ -294,17 +392,37 @@ export class RaftConsensus extends EventEmitter {
   }
 
   private async appendEntries(peerId: string, entries: RaftLogEntry[]): Promise<boolean> {
+    // ADR-095 G2 — over the transport when wired: real AppendEntries RPC.
+    if (this.transport) {
+      try {
+        const reply = await this.transport.send(peerId, {
+          type: 'append-entries',
+          payload: { term: this.node.currentTerm, leaderId: this.node.id, entries, leaderCommit: this.node.commitIndex },
+          term: this.node.currentTerm,
+        });
+        const rp = (reply?.payload ?? {}) as Record<string, unknown>;
+        if (typeof rp.term === 'number' && rp.term > this.node.currentTerm) {
+          this.node.currentTerm = rp.term;
+          this.node.votedFor = undefined;
+          this.node.state = 'follower';
+          if (this.heartbeatInterval) { clearInterval(this.heartbeatInterval); this.heartbeatInterval = undefined; }
+          return false;
+        }
+        return rp.success === true;
+      } catch {
+        return false; // unreachable peer / timeout.
+      }
+    }
+
+    // Legacy in-process path.
     const peer = this.peers.get(peerId);
     if (!peer) return false;
-
-    // Simulate AppendEntries RPC
     if (this.node.currentTerm >= peer.currentTerm) {
       peer.currentTerm = this.node.currentTerm;
       peer.state = 'follower';
       peer.log.push(...entries);
       return true;
     }
-
     return false;
   }