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

package/src/consensus/federation-transport.ts

@@ -0,0 +1,185 @@
+/**
+ * ADR-095 G2 — FederationTransport: a ConsensusTransport backed by the
+ * federation plugin's ADR-104 WS wire (agentic-flow/transport/loader).
+ *
+ * @claude-flow/swarm has zero runtime dependencies and shouldn't take a
+ * hard dep on @claude-flow/plugin-agent-federation (the wiring would also
+ * be circular-ish). So this adapter takes its WS primitives by injection:
+ * pass an object that satisfies `AgenticFlowTransportLike` (which the
+ * federation plugin's `loadQuicTransport` result does) plus a small amount
+ * of consensus-level metadata (this node's id, how to address peers, who
+ * the peers are).
+ *
+ * The agentic-flow transport is fire-and-forget message delivery; this
+ * adapter layers request-response on top via per-message correlation ids
+ * (`corr`) + a pending-replies map + per-call timeout. Stream multiplexing
+ * (ADR-104 stream-mux) is used for the `streamId` so consensus traffic
+ * doesn't interleave with application traffic on the same connection.
+ *
+ * Optional Ed25519 signing: when a keypair is supplied, outbound messages
+ * are signed and inbound are verified against the sender's published
+ * public key (resolved via `resolvePeerPublicKey`) before reaching the
+ * handler. Fail-closed — an unverifiable inbound message is dropped.
+ */
+
+import { randomBytes } from 'node:crypto';
+import type {
+  ConsensusTransport,
+  ConsensusMessage,
+  ConsensusReply,
+  ConsensusMessageHandler,
+  NodeKeyPair,
+} from './transport.js';
+import { signMessage, verifyMessage } from './transport.js';
+
+/**
+ * Minimal shape of the agentic-flow transport (the `loadQuicTransport`
+ * result). We only need send + onMessage + (optional) close. Keeping this
+ * structural means swarm doesn't import agentic-flow.
+ */
+export interface AgenticFlowTransportLike {
+  send(address: string, message: { type?: string; payload: unknown; streamId?: string }): Promise<void>;
+  onMessage(handler: (msg: { from?: string; address?: string; type?: string; payload: unknown }) => void | Promise<void>): void;
+  close?(): Promise<void> | void;
+}
+
+/** What we put on the wire — a ConsensusMessage plus correlation metadata. */
+interface WireEnvelope {
+  /** Correlation id — present on requests; the reply echoes it. */
+  readonly corr?: string;
+  /** True if this envelope is a reply to a `corr` request. */
+  readonly isReply?: boolean;
+  /** The consensus message. `from` is filled by us. */
+  readonly msg: ConsensusMessage;
+}
+
+export interface FederationTransportOptions {
+  /** This node's consensus id (the `from` on outbound messages). */
+  readonly nodeId: string;
+  /** Map a consensus nodeId → the WS address agentic-flow uses to reach it. Return undefined for unknown peers. */
+  readonly addressOf: (nodeId: string) => string | undefined;
+  /** Currently-known peer consensus node ids (excludes self — or includes; we filter). */
+  readonly peerIds: () => readonly string[];
+  /** Stream id for consensus traffic (ADR-104 stream-mux). Defaults to 'ruflo-consensus'. */
+  readonly streamId?: string;
+  /** Default per-`send` timeout in ms. Defaults to 5000. */
+  readonly defaultTimeoutMs?: number;
+  /** Optional Ed25519 keypair — signs outbound, verifies inbound. */
+  readonly keyPair?: NodeKeyPair;
+  /** Resolve a peer consensus nodeId → its Ed25519 public key PEM. Required if `keyPair` is set and you want verification. */
+  readonly resolvePeerPublicKey?: (nodeId: string) => string | undefined;
+}
+
+export class FederationTransport implements ConsensusTransport {
+  readonly nodeId: string;
+  private readonly wire: AgenticFlowTransportLike;
+  private readonly addressOf: (nodeId: string) => string | undefined;
+  private readonly peerIdsFn: () => readonly string[];
+  private readonly streamId: string;
+  private readonly defaultTimeoutMs: number;
+  private readonly keyPair?: NodeKeyPair;
+  private readonly resolvePeerPublicKey?: (nodeId: string) => string | undefined;
+  private handler: ConsensusMessageHandler | null = null;
+  private closed = false;
+  private seqCounter = 0;
+  private readonly pending = new Map<string, { resolve: (r: ConsensusReply) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private readonly lastSeenSeq = new Map<string, number>();
+
+  constructor(wire: AgenticFlowTransportLike, opts: FederationTransportOptions) {
+    this.wire = wire;
+    this.nodeId = opts.nodeId;
+    this.addressOf = opts.addressOf;
+    this.peerIdsFn = opts.peerIds;
+    this.streamId = opts.streamId ?? 'ruflo-consensus';
+    this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 5_000;
+    this.keyPair = opts.keyPair;
+    this.resolvePeerPublicKey = opts.resolvePeerPublicKey;
+
+    this.wire.onMessage(async (raw) => {
+      if (this.closed) return;
+      const env = raw.payload as WireEnvelope | undefined;
+      if (!env || !env.msg) return;
+      const msg = env.msg;
+
+      // Signature verification (if this node expects signed messages).
+      if (this.keyPair && this.resolvePeerPublicKey) {
+        const pub = this.resolvePeerPublicKey(msg.from);
+        if (!pub || !verifyMessage(msg, pub)) return; // fail-closed: drop
+        if (typeof msg.seq === 'number') {
+          const last = this.lastSeenSeq.get(msg.from) ?? 0;
+          if (msg.seq <= last) return; // replayed / out of order: drop
+          this.lastSeenSeq.set(msg.from, msg.seq);
+        }
+      }
+
+      // Reply to a pending `send`?
+      if (env.isReply && env.corr) {
+        const p = this.pending.get(env.corr);
+        if (p) { clearTimeout(p.timer); this.pending.delete(env.corr); p.resolve(msg); }
+        return;
+      }
+
+      // Inbound request → run the handler; if it returns a reply, send it back.
+      if (this.handler) {
+        const reply = await this.handler(msg);
+        if (reply && env.corr) {
+          const addr = this.addressOf(msg.from);
+          if (addr) {
+            const replyMsg = this.stamp({ ...reply, to: msg.from });
+            await this.wire.send(addr, { type: 'consensus', payload: { corr: env.corr, isReply: true, msg: replyMsg } as WireEnvelope, streamId: this.streamId }).catch(() => {});
+          }
+        }
+      }
+    });
+  }
+
+  onMessage(handler: ConsensusMessageHandler): void {
+    this.handler = handler;
+  }
+
+  peers(): readonly string[] {
+    return this.peerIdsFn().filter(id => id !== this.nodeId);
+  }
+
+  private stamp(msg: Omit<ConsensusMessage, 'from'>): ConsensusMessage {
+    const base: Omit<ConsensusMessage, 'signature'> = {
+      ...msg,
+      from: this.nodeId,
+      seq: this.keyPair ? ++this.seqCounter : msg.seq,
+    };
+    return this.keyPair ? { ...base, signature: signMessage(base, this.keyPair.privateKeyPem) } : base;
+  }
+
+  async send(to: string, msg: Omit<ConsensusMessage, 'from'>, timeoutMs?: number): Promise<ConsensusReply> {
+    if (this.closed) throw new Error('FederationTransport: closed');
+    const addr = this.addressOf(to);
+    if (!addr) throw new Error(`FederationTransport: no address for peer ${to}`);
+    const corr = randomBytes(8).toString('hex');
+    const stamped = this.stamp({ ...msg, to });
+    const t = timeoutMs ?? this.defaultTimeoutMs;
+    return new Promise<ConsensusReply>((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(corr); reject(new Error(`FederationTransport: send to ${to} timed out (${t}ms)`)); }, t);
+      this.pending.set(corr, { resolve, reject, timer });
+      this.wire.send(addr, { type: 'consensus', payload: { corr, msg: stamped } as WireEnvelope, streamId: this.streamId })
+        .catch((e) => { clearTimeout(timer); this.pending.delete(corr); reject(e instanceof Error ? e : new Error(String(e))); });
+    });
+  }
+
+  async broadcast(msg: Omit<ConsensusMessage, 'from'>): Promise<void> {
+    if (this.closed) throw new Error('FederationTransport: closed');
+    const stamped = this.stamp(msg);
+    await Promise.allSettled(this.peers().map(async (to) => {
+      const addr = this.addressOf(to);
+      if (!addr) return;
+      await this.wire.send(addr, { type: 'consensus', payload: { msg: stamped } as WireEnvelope, streamId: this.streamId }).catch(() => {});
+    }));
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    this.handler = null;
+    for (const [, p] of this.pending) { clearTimeout(p.timer); p.reject(new Error('FederationTransport: closed')); }
+    this.pending.clear();
+    if (this.wire.close) await this.wire.close();
+  }
+}

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

@@ -16,10 +16,40 @@ import {
 import { RaftConsensus, createRaftConsensus, RaftConfig } from './raft.js';
 import { ByzantineConsensus, createByzantineConsensus, ByzantineConfig } from './byzantine.js';
 import { GossipConsensus, createGossipConsensus, GossipConfig } from './gossip.js';
+import type { ConsensusTransport } from './transport.js';
 
 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 {
@@ -45,6 +75,14 @@ export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
       this.config = { ...this.config, ...config };
     }
 
+    // ADR-095 G2.2 — narrow the typed-as-unknown `transport` from
+    // ConsensusConfig into the real ConsensusTransport so Raft / Byzantine /
+    // Gossip get a working inter-node wire. Structural check, not
+    // instanceof, so test mocks satisfy it without importing transport.ts.
+    const transport = isConsensusTransport(this.config.transport)
+      ? this.config.transport
+      : undefined;
+
     // Create implementation based on algorithm
     switch (this.config.algorithm) {
       case 'raft':
@@ -53,6 +91,7 @@ export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
           timeoutMs: this.config.timeoutMs,
           maxRounds: this.config.maxRounds,
           requireQuorum: this.config.requireQuorum,
+          transport,
         });
         break;
 
@@ -62,6 +101,7 @@ export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
           timeoutMs: this.config.timeoutMs,
           maxRounds: this.config.maxRounds,
           requireQuorum: this.config.requireQuorum,
+          transport,
         });
         break;
 
@@ -71,6 +111,7 @@ export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
           timeoutMs: this.config.timeoutMs,
           maxRounds: this.config.maxRounds,
           requireQuorum: this.config.requireQuorum,
+          transport,
         });
         break;
 
@@ -81,6 +122,7 @@ export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
           timeoutMs: this.config.timeoutMs,
           maxRounds: this.config.maxRounds,
           requireQuorum: this.config.requireQuorum,
+          transport,
         });
         break;
 
@@ -233,6 +275,23 @@ export function createConsensusEngine(
   return new ConsensusEngine(nodeId, { ...config, algorithm });
 }
 
+/**
+ * ADR-095 G2.2 — structural check that an opaque value implements the
+ * ConsensusTransport interface. Used by the engine to safely narrow the
+ * `transport` field on `ConsensusConfig` (typed as `unknown` to keep
+ * `types.ts` free of cross-module imports).
+ */
+function isConsensusTransport(value: unknown): value is ConsensusTransport {
+  if (!value || typeof value !== 'object') return false;
+  const t = value as Record<string, unknown>;
+  return typeof t.nodeId === 'string'
+      && typeof t.send === 'function'
+      && typeof t.broadcast === 'function'
+      && typeof t.onMessage === 'function'
+      && typeof t.peers === 'function'
+      && typeof t.close === 'function';
+}
+
 // Helper to select optimal algorithm based on requirements
 export function selectOptimalAlgorithm(requirements: {
   faultTolerance: 'crash' | 'byzantine';

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;
   }