Initial Commit

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

@@ -0,0 +1,77 @@
+# 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.