78 lines
5.2 KiB
Markdown
78 lines
5.2 KiB
Markdown
# 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.
|