OpenSpec Change: network-plugin-failover

Change ID: network-plugin-failover
Package: @suaveplan/network-plugin-failover (new)
Status: PROPOSED
Type: new-package
Date: 2026-04-29

Why

The tiered network requires automatic recovery when a host (Tier 0) fails. The genesis retry, fsm, and rate-limiter packages provide primitives, but no plugin implements the host-failure detection, state transition, and emergency-election trigger. This plugin fills that gap by consuming peer health events from the bus and coordinating the alive → suspect → dead → recovering lifecycle.

What changes

ADDED: FailoverPlugin class implementing NetworkPlugin.
ADDED: FailoverCoordinator — tracks peer health, manages state transitions, triggers elections.
ADDED: HeartbeatManager — sends periodic heartbeats, collects responses, detects timeout.
ADDED: HealthMonitor — maintains alive | suspect | dead | recovering states with configurable timeouts.
ADDED: PromoterManager — when a host is declared dead, triggers an emergency election via GovernancePlugin events.
ADDED: NETWORK_FO_CODES — frozen error registry.

Out of scope

Persistent state of failover log → future network-plugin-failover-persistence.
Cross-group failover federation → future scope.
Network partition detection (split-brain) → handled by network-plugin-partition. Failover manages single-host death (alive→suspect→dead). Partition manages group isolation (split-brain). The two plugins are complementary: failover emits heartbeat events that partition consumes for connectivity-map analysis.

Source mapping

This change derives from ../suaveplan/enterprise/network-failover.md and ../suaveplan/packages/universal/network-failover/.

Requirement	Source lines	Notes
Host failure detection (alive→suspect→dead)	`network-failover/README.md` §Failure Detection	verbatim
Heartbeat interval and timeout	`network-failover/README.md` §Configuration	verbatim
Automatic election trigger on dead host	`network-failover/README.md` §Automatic Recovery	verbatim

Requirements with no source line

Requirement	Justification
Consumes `peer:connected`/`peer:disconnected` from bus	Decouples failover from transport implementation
Emits `failover:emergency-election` on bus	Loose coupling to governance plugin — no direct import
Uses `@suaveplan/rate-limiter` to throttle heartbeat bursts	Defensive — prevents self-DOS during mass disconnect

Verification approach

src/failover/failover.spec-conformance.test.ts — pins state transitions, timeout, election trigger.
src/heartbeat/heartbeat.spec-conformance.test.ts — pins interval, response, timeout.
src/health/health.spec-conformance.test.ts — pins alive→suspect→dead→recovering.
src/promoter/promoter.spec-conformance.test.ts — pins emergency election emission.
tests/dep-graph.test.ts — pins no direct import of governance or transport packages.

Migration impact

None — additive only.

3.1 KiB Raw Blame History