Show & Tell: FederatedConsensus — Raft-lite leader election, threshold-signature quorum proofs, and ordered commit log

[web3guru888]

Overview

FederatedConsensus (Phase 9.4) adds binding multi-agent agreement to the ASI-Build federation stack. Without consensus, two agents might independently route the same task or apply conflicting capability-registry updates. With consensus, the cluster as a whole can vote on any payload — and the resulting CommitCertificate is cryptographically signed proof that a quorum agreed.

---

Component Map

┌─────────────────────────────────────────────────────────────────┐
│                  FederatedConsensus (Phase 9.4)                  │
│                                                                   │
│  ConsensusRole FSM              ProposalID                       │
│  FOLLOWER ──elect──► CANDIDATE  (term, seq, origin_peer)         │
│        │  ◄──lost──      │                                       │
│        │      won ──────►│ LEADER                                │
│                           │                                       │
│  propose()                │ broadcast ConsensusProposal          │
│  vote()  ◄────────────────┤ collect ConsensusVotes               │
│  _commit()                │ quorum reached?                       │
│    └──► CommitCertificate │   yes → threshold_sig                │
│             (frozen)      │   no  → TTL expire → abort           │
│                                                                   │
│  commit_stream() ──────────────► async generator                 │
│  abort_stream()  ──────────────► async generator                 │
│                                                                   │
│  FederationGateway (9.1)  ← broadcast + send_message            │
│  FederatedBlackboard (9.2) ← publish committed payload as event │
│  FederatedTaskRouter (9.3) ← use consensus for config changes   │
└─────────────────────────────────────────────────────────────────┘

---

Why Raft-lite + Threshold Signatures?

Option	Strong Points	Weak Points	Chosen?
Raft-lite	Simple, well-understood, async-friendly	Crash-fault tolerant only	✅ Ordering layer
PBFT-lite	BFT (malicious peers)	3-phase, O(n²) messages	❌
Threshold signatures	Compact BFT proof, forward-secret	Needs distributed key setup	✅ Quorum proof
CRDT counters	Convergence without coordination	No strict ordering	❌

Hybrid decision: Raft handles ordering (cheap, low-latency). Threshold signatures handle proof (compact, verifiable). Together they give ordered, authenticated consensus without the quadratic message cost of full PBFT.

---

Raft-lite Leader Election

Term N:  [F][F][F][F][F]   all followers, random timeouts
          ↓  250-450 ms
         [F][F][C][F][F]   node C times out, increments term
                ↓
         broadcasts RequestVote(term=N+1, candidate=C)
                ↓
         [F][F][L][F][F]   receives 3/5 votes → LEADER
                ↓
         heartbeats every 150 ms → followers reset timeout

Key invariants:

• A node votes for at most one candidate per term (voted_for fencing)
• Stale messages from lower terms are silently dropped
• Heartbeat timeout uses asyncio.Event, not busy-wait

---

Proposal Lifecycle

Leader                    Follower A         Follower B
  │                           │                  │
  ├──propose(payload)─────────┤                  │
  │  ProposalID(term=3,seq=1) │                  │
  │                           │                  │
  ├─broadcast(ConsensusProposal)──────────────────┤
  │                           │                  │
  │◄──vote(pid, granted=True)─┤                  │
  │◄──vote(pid, granted=True)─────────────────────┤
  │                           │                  │
  ├─_commit()─────────────────┤                  │
  │  CommitCertificate        │                  │
  │  signers={A,B}            │                  │
  │  threshold_sig=SHA256(…)  │                  │
  │                           │                  │
  └──commit_stream() emits────┘                  │

---

CommitCertificate Data Model

@dataclass(frozen=True)
class CommitCertificate:
    proposal_id:   ProposalID        # (term=3, seq=1, origin="did:key:leader")
    committed_at:  int               # epoch ms
    signers:       FrozenSet[str]    # {"did:key:A", "did:key:B"}
    threshold_sig: bytes             # 32-byte SHA-256 stub → BLS in production

• signers is a frozenset — set membership is the proof, order does not matter
• threshold_sig is bytes — swap SHA-256 stub for BLS aggregate without changing the interface
• Entire dataclass is frozen → safe as dict key, set element, LRU cache key

---

Prometheus Metrics

Metric	Type	Labels
asi_consensus_proposals_total	Counter	outcome (committed/aborted/expired)
asi_consensus_role_transitions_total	Counter	from_role, to_role
asi_consensus_commit_latency_seconds	Histogram	—
asi_consensus_pending_proposals	Gauge	—
asi_consensus_term	Gauge	—

Useful PromQL:

# Commit success rate (5m window)
rate(asi_consensus_proposals_total{outcome="committed"}[5m])
  / rate(asi_consensus_proposals_total[5m])

# Leader election frequency (alert if > 6/hour)
increase(asi_consensus_role_transitions_total{to_role="leader"}[1h]) > 6

# p99 commit latency
histogram_quantile(0.99, rate(asi_consensus_commit_latency_seconds_bucket[5m]))

---

CognitiveCycle Integration

# LEARNING phase hook
async def _learning_phase(self) -> None:
    if cert := await self._blackboard.pop(CONSENSUS_COMMITTED_KEY, timeout_ms=0):
        await self._consensus_module.apply_committed(cert.payload)

---

3 Open Questions

1. Byzantine tolerance: Raft-lite only tolerates crash failures. For adversarial environments, should we optionally layer PBFT on top? Or is threshold signature verification sufficient?

2. Log persistence: Current spec uses an in-memory list with FIFO eviction. Should we add a JsonlConsensusLog backed by aiofiles, similar to JsonlTraceStorage in Phase 8.1?

3. Config consensus scope: Should FederatedTaskRouter use FederatedConsensus for routing strategy switches, or is that overkill? Tradeoff: strong consistency vs. full round-trip latency.

---

See Issue #310 for full spec, 12 test targets, and 14-step implementation order.