# 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.