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.

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

@@ -0,0 +1,75 @@
+# Tasks — network-plugin-governance
+
+> Blocked on: `network-core`.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-governance/` with `package.json` (`@suaveplan/network-plugin-governance@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/election.types.ts` — `ElectionMode`, `ElectionConfig`, `ElectionResult`.
+- [x] 2.2 `src/types/candidate.types.ts` — `Candidate`, `CandidateScore`, `ScoringWeights`.
+- [x] 2.3 `src/types/transition.types.ts` — `TransitionState`, `TransitionConfig`.
+- [x] 2.4 `src/types/reputation.types.ts` — `ReputationScore`, `ReputationEvent`.
+- [x] 2.5 `src/error-codes.ts` — `defineCodes("NET_GOV", [...])`.
+
+## 3. Candidate scorer
+
+- [x] 3.1 `src/scoring/candidate-scorer.ts` — `CandidateScorer` with weighted criteria.
+- [x] 3.2 Formula: `score = Σ(weightᵢ × normalize(metricᵢ))`.
+- [x] 3.3 Metrics: latency (inverse), uptime, bandwidth, reputation.
+- [x] 3.4 Tiebreaking: deterministic by peerId hash.
+
+## 4. Reputation tracker
+
+- [x] 4.1 `src/reputation/reputation-tracker.ts` — `ReputationTracker`.
+- [x] 4.2 Events: `success`, `failure`, `violation`.
+- [x] 4.3 Exponential decay: `scoreₜ = scoreₜ₋₁ × α` where α configurable.
+
+## 5. Voting manager
+
+- [x] 5.1 `src/voting/voting-manager.ts` — collects votes over `NetworkBus`.
+- [x] 5.2 Deduplication by `peerId`.
+- [x] 5.3 Quorum detection: configurable fraction of known peers.
+
+## 6. Election engine
+
+- [x] 6.1 `src/election/election-engine.ts` — `ElectionEngine`.
+- [x] 6.2 Modes: `metric` (score only), `direct` (vote tally), `hybrid` (score × vote weight).
+- [x] 6.3 Emits `election:result` on `NetworkBus` with `winnerId`, `mode`, `score`.
+
+## 7. Transition manager
+
+- [x] 7.1 `src/transition/transition-manager.ts` — host handover FSM using `@suaveplan/fsm`.
+- [x] 7.2 States: `idle → preparing → transferring → confirming → completed | failed`.
+- [x] 7.3 Emits `transition:state-change` on bus.
+- [x] 7.4 On `failed`, rolls back to `idle` and emits `transition:failed`.
+
+## 8. Plugin wrapper
+
+- [x] 8.1 `src/plugin/governance-plugin.ts` — `GovernancePlugin` implements `NetworkPlugin`.
+- [x] 8.2 Subscribes to `peer:latency`, `peer:disconnected` on bus.
+- [x] 8.3 Installs election, scorer, voting, transition, and reputation managers.
+
+## 9. Spec
+
+- [x] 9.1 Update `openspec/specs/network/spec.md` with `NET-08`, `NET-09`.
+
+## 10. Conformance tests
+
+- [x] 10.1 `src/election/election.spec-conformance.test.ts` — all three modes, quorum, tiebreaking.
+- [x] 10.2 `src/scoring/scoring.spec-conformance.test.ts` — weighted criteria, reputation decay.
+- [x] 10.3 `src/transition/transition.spec-conformance.test.ts` — FSM states, rollback on failure.
+- [x] 10.4 `src/voting/voting.spec-conformance.test.ts` — vote collection, tally, duplicate rejection.
+- [x] 10.5 `src/reputation/reputation.spec-conformance.test.ts` — success/failure/violation, decay.
+- [x] 10.6 `src/backpressure/backpressure.spec-conformance.test.ts` — not applicable (N/A).
+- [x] 10.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 11. Verify
+
+- [x] 11.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-governance` green.
+- [x] 11.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-governance` 100/100/100/100.
+- [x] 11.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-governance` PASS.