# Tasks — network-plugin-failover

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

## 1. Scaffold

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

## 2. Types

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

## 3. Heartbeat manager

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

## 4. Health monitor

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

## 5. Promoter manager

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

## 6. Failover coordinator

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

## 7. Plugin wrapper

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

## 8. Spec

- [x] 8.1 Update `openspec/specs/network/spec.md` with `NET-10`, `NET-11`.

## 9. Conformance tests

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

## 10. Verify

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