Initial Commit

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.