Phase 19b: Governance & BFT

Overview

Phase 19b implements the Governance Plane — a lightweight PBFT (Practical Byzantine Fault Tolerance) consensus protocol for federation governance decisions. This is the third consensus plane, providing strong consistency (one truth, no forks) for operations that require federation-wide agreement.

Three Planes of Consensus

PBFT Protocol

The consensus follows a simplified PBFT flow:

1. PRE-PREPARE: Leader proposes a batch of governance transactions
                with a monotonically increasing sequence number.

2. PREPARE:     Each replica validates the proposal and broadcasts
                a Prepare vote. When quorum (2f+1) prepares are
                received, transition to Commit phase.

3. COMMIT:      Each replica broadcasts a Commit vote. When quorum
                (2f+1) commits are received, the batch is sealed.

4. EXECUTE:     The sealed batch is applied to governance state.
                Transactions are executed in sequence order.

Quorum Requirements

Leader Election

The leader for each view is determined by view_number % cluster_size. View advancement (leader rotation) happens via advance_view().

Governance Transactions

Four types of transactions can be proposed and agreed upon via PBFT:

Admit

{
  "type": "admit",
  "server_id": "server-xyz",
  "verifying_key_hex": "abc123...",
  "kex_public_hex": "def456..."
}

Formally admits a server as a member through consensus. Unlike the 19a join protocol (which is request/response between two servers), governance admission is a federation-wide decision.

Expel

{
  "type": "expel",
  "server_id": "server-bad",
  "reason": "Byzantine behavior detected"
}

Removes a member from the federation by consensus. No single server can expel another — it requires quorum agreement.

KeyRegister

{
  "type": "key_register",
  "server_id": "server-xyz",
  "key_id": 42,
  "verifying_key_hex": "newkey...",
  "kex_public_hex": "newkex..."
}

Registers or rotates a server's cryptographic keys through consensus. Ensures all servers agree on the current key state.

RoyaltyRecord

{
  "type": "royalty_record",
  "origin_server_id": "server-a",
  "target_server_id": "server-b",
  "content_fingerprint_hex": "abcdef...",
  "royalty_type": "transclusion",
  "amount": 100
}

Records a transclusion royalty obligation. This is recording, not settlement — payment is a separate concern.

Wire Operations (0x1Bxx range)

Server-to-Server Federation Frames

Server Methods

• governance_propose(transactions) — Propose a batch of governance transactions
• governance_receive_prepare(vote) — Process a Prepare vote
• governance_receive_commit(vote) — Process a Commit vote
• governance_seal_round() — Seal the current round and execute transactions
• governance_execute_tx(tx) — Apply a single governance transaction to state
• governance_log() — View the governance log
• governance_current_view() / governance_current_sequence() — Consensus state
• governance_is_leader() / governance_leader_id() — Leader queries
• governance_cluster_size() / governance_quorum_size() — Cluster parameters
• governance_pending_round() — View the current in-progress round

Key Types

• GovernanceTx — A governance transaction (Admit, Expel, KeyRegister, RoyaltyRecord)
• GovernanceProposal — A proposed batch with view, sequence, and timestamp
• PbftVote — A Prepare or Commit vote for a specific (view, sequence) pair
• PbftPhase — Prepare or Commit
• SealedBatch — A fully committed batch in the governance log
• ConsensusRound — An in-progress consensus round with vote tracking
• RoundPhase — PrePrepare, Prepare, Commit, or Sealed
• GovernanceState — The complete PBFT state machine

Test Coverage

Unit Tests (21 new)

• GovernanceState construction and cluster sizing
• Quorum calculations for 1/3/4/7/10 node clusters
• Leader rotation through view advancement
• Proposal creation and pending round tracking
• Full consensus flow (4 nodes: propose → prepare → commit → seal)
• Seal rejection when round is not ready
• Wrong view/sequence rejection
• View advancement clearing pending rounds
• Transaction type names
• Serialization roundtrips for proposals, sealed batches, and votes
• Multiple sequential batches
• Dynamic cluster resizing

Server Method Tests (6 new)

• Bootstrap → propose (single server)
• Full consensus on single server
• Execute Admit/Expel/Royalty transactions
• Governance status queries

Integration Tests (7 new)

• Governance status via wire op
• Propose via wire op (admin auth required)
• Log query (empty and populated)
• Full consensus via server methods (propose → prepare → commit → seal)
• Royalty recording through consensus
• Propose requires admin auth
• Seal + log roundtrip via wire ops

Design Decisions

1. Lightweight PBFT: Designed for 3-10 nodes, not thousands. Simplified phases without checkpointing or view-change (to be added if needed).

2. Leader-based proposal: Only the current leader (by view rotation) can propose. This prevents conflicting proposals for the same sequence number.

3. Transaction execution on seal: Transactions are only applied to state after a batch is sealed (quorum commits received). This ensures all nodes execute in the same order.

4. Governance log is append-only: Once a batch is sealed, it's in the log forever. No rollback mechanism — if an expel was wrong, the server can be re-admitted through a new Admit transaction.

5. Tag counter initialized with timestamp: Prevents cross-server tag collisions in the OrSet that underlies the membership state.

6. Governance state is NOT CRDT-merged: Unlike membership and reconciliation, governance state is consensus-driven. Only sealed batches from PBFT are applied, ensuring one truth.