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

Tasks — network-plugin-failover

Blocked on: network-core, network-plugin-governance.

1. Scaffold

• 1.1 packages/network/network-plugin-failover/ with package.json (@suaveplan/network-plugin-failover@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/rate-limiter, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/health.types.ts — HealthState, HealthConfig, PeerHealth.
• 2.2 src/types/heartbeat.types.ts — HeartbeatFrame, HeartbeatConfig.
• 2.3 src/types/failover.types.ts — FailoverConfig, FailoverEvent.
• 2.4 src/error-codes.ts — defineCodes("NET_FO", [...]).

3. Heartbeat manager

• 3.1 src/heartbeat/heartbeat-manager.ts — sends periodic heartbeats to all peers.
• 3.2 Configurable interval and timeout.
• 3.3 Correlates echo with sequence numbers.
• 3.4 Uses @suaveplan/rate-limiter to throttle burst sends.

4. Health monitor

• 4.1 src/health/health-monitor.ts — per-peer health state machine.
• 4.2 States: alive → suspect → dead → recovering.
• 4.3 Transitions on missed heartbeats (configurable thresholds).
• 4.4 Emits health:state-change on NetworkBus.

5. Promoter manager

• 5.1 src/promoter/promoter-manager.ts — triggers emergency election.
• 5.2 On dead state, emits failover:emergency-election on bus.
• 5.3 Debounces to prevent duplicate triggers.

6. Failover coordinator

• 6.1 src/failover/failover-coordinator.ts — orchestrates heartbeat, health, promoter.
• 6.2 Consumes peer:connected, peer:disconnected, health:state-change from bus.
• 6.3 Publishes failover:emergency-election, health:state-change.

7. Plugin wrapper

• 7.1 src/plugin/failover-plugin.ts — FailoverPlugin implements NetworkPlugin.
• 7.2 Installs heartbeat, health, promoter, coordinator on install().

8. Spec

• 8.1 Update openspec/specs/network/spec.md with NET-10, NET-11.

9. Conformance tests

• 9.1 src/failover/failover.spec-conformance.test.ts — state transitions, timeout, election trigger.
• 9.2 src/heartbeat/heartbeat.spec-conformance.test.ts — interval, response, timeout.
• 9.3 src/health/health.spec-conformance.test.ts — alive→suspect→dead→recovering.
• 9.4 src/promoter/promoter.spec-conformance.test.ts — emergency election emission, debounce.
• 9.5 src/error-codes.spec-conformance.test.ts — frozen registry.

10. Verify

• 10.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-failover green.
• 10.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-failover 100/100/100/100.
• 10.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-failover PASS.