suaveplan/openspec/changes/archive/2026-05-04-network-plugin-governance/proposal.md

OpenSpec Change: network-plugin-governance

• Change ID: network-plugin-governance
• Package: @suaveplan/network-plugin-governance (new)
• Status: PROPOSED
• Type: new-package
• Date: 2026-04-29

Why

The tiered network design requires small groups to nominate a host dynamically. The genesis fsm package provides state machines, retry provides backoff, and events provides the bus — but there is no plugin that orchestrates elections, scores candidates, and manages host transitions. This plugin fills that gap. It consumes latency data from network-plugin-webrtc (via bus), runs elections, and publishes the winner so network-plugin-topology can promote the node to Tier 0.

What changes

• ADDED: GovernancePlugin class implementing NetworkPlugin.
• ADDED: ElectionEngine — orchestrates election rounds: initiates, collects votes, computes winner, publishes result.
• ADDED: CandidateScorer — weighted multi-criteria scoring: latency (inverse), uptime, bandwidth, and reputation. Reputation decays over time.
• ADDED: VotingManager — collects votes via NetworkBus, tallies, detects quorum.
• ADDED: VoteSession — encapsulates a single vote round with configurable topics, voting periods, participation thresholds, and consensus requirements. Lifecycle: creation → voting → tallying → result publication.
• ADDED: TransitionManager — host handover lifecycle: idle → preparing → transferring → confirming → completed (or failed).
• ADDED: HostSelector — historical trust-based scoring system. Evaluates candidates using weighted multi-factor evaluation (latency, stability, uptime, capabilities, trust score). Tracks historical hosting performance via HostHistory to improve future selections. Enforces stability thresholds and consensus validation before confirming a host.
• ADDED: HostHistory — append-only record of successful/unsuccessful hosting sessions per peer. Used by HostSelector to compute trust scores.
• ADDED: ReputationTracker — per-peer reputation with success/failure/violation scoring and configurable decay.
• ADDED: Election modes: metric (score-based), direct (vote tally), hybrid (score + votes).
• ADDED: NETWORK_GOV_CODES — frozen error registry.

Out of scope

• Byzantine fault tolerance beyond simple reputation scoring → future hardening change.
• Cryptographic vote signing → future network-plugin-governance-crypto.
• Global consensus across many groups → each group runs its own election; federation is deferred.

Source mapping

This change derives from ../suaveplan/enterprise/network-governance.md and ../suaveplan/packages/universal/network-governance/.

Requirement	Source lines	Notes
Election modes (metric/direct/hybrid)	network-governance/README.md §Election Modes	verbatim
Candidate scoring with weights	network-governance/README.md §Scoring	verbatim
Transition lifecycle FSM	network-governance/README.md §Transition Lifecycle	reworded; uses @suaveplan/fsm
Reputation tracking with decay	network-governance/README.md §Reputation Tracking	verbatim

Requirements with no source line

Requirement	Justification
Consumes peer:latency from bus	Required for metric-mode scoring without direct coupling to webrtc plugin
TransitionManager uses @suaveplan/fsm	Genesis already has a production FSM; no need to hand-roll state transitions
Quorum detection	Defensive — prevents declaring a winner with too few participants

Enhancement: Voting System Details

Source: docs/old-network-planning/PHASE_4.md §Voting System

• VoteSession — configurable topics (host selection, config changes, tier promotions).
• Configurable voting periods and participation thresholds.
• Result determination with configurable consensus requirements (simple majority, supermajority, unanimous).
• VoteSession lifecycle: creation → voting → tallying → result publication.
• Vote validation against session rules (e.g. only Tier 0/1 peers may vote on host selection).
• Tamper-proof tallying — votes are signed by peers; tally is reproducible.
• Secure voting verification — any peer can verify the published tally against individual vote signatures.
• Vote history tracking — append-only log of all votes for audit (consumed by network-plugin-audit-mesh).

Verification approach

• src/election/election.spec-conformance.test.ts — pins all three modes, quorum, tiebreaking.
• src/scoring/scoring.spec-conformance.test.ts — pins weighted criteria, reputation decay.
• src/transition/transition.spec-conformance.test.ts — pins FSM states and rollback on failure.
• src/voting/voting.spec-conformance.test.ts — pins vote collection, tally, duplicate rejection, session lifecycle.
• src/vote-session/vote-session.spec-conformance.test.ts — pins configurable topics, thresholds, consensus requirements, vote validation.
• src/reputation/reputation.spec-conformance.test.ts — pins success/failure/violation scoring and decay.
• tests/dep-graph.test.ts — pins no direct import of webrtc or transport packages.

Migration impact

None — additive only.