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

Tasks — network-plugin-governance

Blocked on: network-core.

1. Scaffold

• 1.1 packages/network/network-plugin-governance/ with package.json (@suaveplan/network-plugin-governance@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/fsm, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/election.types.ts — ElectionMode, ElectionConfig, ElectionResult.
• 2.2 src/types/candidate.types.ts — Candidate, CandidateScore, ScoringWeights.
• 2.3 src/types/transition.types.ts — TransitionState, TransitionConfig.
• 2.4 src/types/reputation.types.ts — ReputationScore, ReputationEvent.
• 2.5 src/error-codes.ts — defineCodes("NET_GOV", [...]).

3. Candidate scorer

• 3.1 src/scoring/candidate-scorer.ts — CandidateScorer with weighted criteria.
• 3.2 Formula: score = Σ(weightᵢ × normalize(metricᵢ)).
• 3.3 Metrics: latency (inverse), uptime, bandwidth, reputation.
• 3.4 Tiebreaking: deterministic by peerId hash.

4. Reputation tracker

• 4.1 src/reputation/reputation-tracker.ts — ReputationTracker.
• 4.2 Events: success, failure, violation.
• 4.3 Exponential decay: scoreₜ = scoreₜ₋₁ × α where α configurable.

5. Voting manager

• 5.1 src/voting/voting-manager.ts — collects votes over NetworkBus.
• 5.2 Deduplication by peerId.
• 5.3 Quorum detection: configurable fraction of known peers.

6. Election engine

• 6.1 src/election/election-engine.ts — ElectionEngine.
• 6.2 Modes: metric (score only), direct (vote tally), hybrid (score × vote weight).
• 6.3 Emits election:result on NetworkBus with winnerId, mode, score.

7. Transition manager

• 7.1 src/transition/transition-manager.ts — host handover FSM using @suaveplan/fsm.
• 7.2 States: idle → preparing → transferring → confirming → completed | failed.
• 7.3 Emits transition:state-change on bus.
• 7.4 On failed, rolls back to idle and emits transition:failed.

8. Plugin wrapper

• 8.1 src/plugin/governance-plugin.ts — GovernancePlugin implements NetworkPlugin.
• 8.2 Subscribes to peer:latency, peer:disconnected on bus.
• 8.3 Installs election, scorer, voting, transition, and reputation managers.

9. Spec

• 9.1 Update openspec/specs/network/spec.md with NET-08, NET-09.

10. Conformance tests

• 10.1 src/election/election.spec-conformance.test.ts — all three modes, quorum, tiebreaking.
• 10.2 src/scoring/scoring.spec-conformance.test.ts — weighted criteria, reputation decay.
• 10.3 src/transition/transition.spec-conformance.test.ts — FSM states, rollback on failure.
• 10.4 src/voting/voting.spec-conformance.test.ts — vote collection, tally, duplicate rejection.
• 10.5 src/reputation/reputation.spec-conformance.test.ts — success/failure/violation, decay.
• 10.6 src/backpressure/backpressure.spec-conformance.test.ts — not applicable (N/A).
• 10.7 src/error-codes.spec-conformance.test.ts — frozen registry.

11. Verify

• 11.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-governance green.
• 11.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-governance 100/100/100/100.
• 11.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-governance PASS.