Initial Commit

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

@@ -0,0 +1,56 @@
+# 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.

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

@@ -0,0 +1,65 @@
+# 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.