feat(alertrouter): B.3b — system-alert-router implementation (15/15 ACs, 100%) (#424)

Continues Slice B.3 (orchestration plumbing). The alert router is the
bridge between OpenWatch's event bus (B.3a) and external notification
channels — Slack, email, webhook, PagerDuty. It subscribes to bus
events at boot, translates each into a typed Alert, applies a dedup
gate per (alert_type, host_id, rule_id) tuple, and dispatches matching
alerts to registered Channels.

Concrete channel implementations live in subpackages so the core
router has no external SDK dependencies. This PR ships the interface +
a test fake; Slack, email, webhook implementations land in follow-ups.

Spec
  New: app/specs/system/alert-router.spec.yaml (status: approved).
  15 ACs across 9 constraints.

internal/alertrouter package
  doc.go      Architectural choices: bus subscription on Start, closed
              AlertType + Severity enums, in-memory dedup with TTL,
              channel registration with tag-filter routing, per-
              channel goroutine with failure isolation, Stop drains
              with 10s timeout.

  types.go    AlertType closed enum (HostUnreachable, HostRecovered,
                DriftMajor, DriftMinor, DriftImprovement).
              Severity closed enum (Critical, High, Medium, Low,
                Info) + SeverityOrder rank map.
              Alert struct with Type, Severity, HostID, RuleID, Tags.
              Channel interface (Name + Send).
              ChannelRegistration with Tags filter; empty Tags =
                wildcard.
              ValidateDedupTTL enforces [60s, 24h] range with typed
              ErrDedupTTLOutOfRange.

  dedup.go    DedupGate keyed by Alert.DedupKey(); in-memory map with
              opportunistic reap on every ShouldSkip call to keep
              size bounded under churn. Injectable now() for testing.

  router.go   Router with Start (subscribe to HeartbeatPulse +
                DriftDetected) / Stop (unsubscribe + drain
                in-flight Channel.Send with 10s timeout).
              Per-channel goroutine dispatch; one channel's error or
                panic does NOT block delivery to other channels.
              Event translation: HeartbeatPulse{Reachable=false}
                → host_unreachable (High); recovery → host_recovered
                (Info); DriftDetected{major} → drift_major (High);
                minor → drift_minor (Medium); improvement → Info.

  metrics.go  ReceivedCount + RoutedCount + DedupedCount +
                ChannelFailureCount with JSON-friendly Snapshot.

Tests (15/15 ACs, all under -race)
  types_test.go    AC-01 enum closure (5 alert types).
                   AC-02 severity enum + SeverityOrder ranking.
                   AC-15 ValidateDedupTTL range check (boundary
                     cases + typed error sentinel).

  router_test.go   AC-03/04/05 event-to-alert translation.
                   AC-06 dedup skip within TTL (Channel.Send NOT
                     called for the skipped alert).
                   AC-07 dedup pass after TTL (fake clock on gate).
                   AC-08 tag-filter rejects non-match.
                   AC-09 wildcard channel (empty Tags) receives
                     every alert.
                   AC-10 channel error doesn't block other channels
                     (per-channel + aggregate failure counters).
                   AC-11 Start subscribes to BOTH event kinds.
                   AC-12 Stop drains slow sends + post-Stop publishes
                     ignored.
                   AC-14 all four metric counters increment under
                     compound scenarios.

  source_test.go   AC-13 internal/alertrouter (core, not subpackages)
                     imports no external notification SDKs
                     (slack-go, sendgrid, mailgun, twilio,
                     PagerDuty SDK, opsgenie, gomail, etc.).
                     AST-based import scan.

Verification
  go vet ./...            clean
  golangci-lint           clean
  govulncheck             clean
  go test -race -count=1  PASS (1.10s)
  specter parse           PASS (system-alert-router@1.0.0)
  specter check           PASS (32 specs)
  specter coverage        system-alert-router 15/15 (100%)

Spec: app/specs/system/alert-router.spec.yaml

Author: remyluslosius

app/internal/alertrouter/dedup.go

@@ -0,0 +1,70 @@
+package alertrouter
+
+import (
+	"sync"
+	"time"
+)
+
+// DedupGate filters out repeat alerts with the same dedup key seen
+// within the configured TTL. Per Spec C-03 / C-04 / AC-06 / AC-07.
+//
+// Implementation: in-memory map keyed by Alert.DedupKey(). Each entry
+// holds the last-seen timestamp; ShouldSkip compares now() against
+// that timestamp + TTL. Stale entries are reaped opportunistically on
+// every ShouldSkip call to keep the map from growing unbounded under
+// churn.
+type DedupGate struct {
+	ttl  time.Duration
+	now  func() time.Time
+	mu   sync.Mutex
+	seen map[string]time.Time
+}
+
+// NewDedupGate constructs a DedupGate with the given TTL. Caller is
+// expected to have validated the TTL via ValidateDedupTTL.
+func NewDedupGate(ttl time.Duration) *DedupGate {
+	return &DedupGate{
+		ttl:  ttl,
+		now:  time.Now,
+		seen: make(map[string]time.Time),
+	}
+}
+
+// ShouldSkip reports whether the alert should be skipped because it
+// matches a recently-seen dedup key. As a side effect, on a non-skip
+// outcome it records the alert's timestamp so the next call within
+// TTL will skip.
+//
+// Spec AC-06: a repeat within TTL is skipped.
+// Spec AC-07: a repeat after TTL passes through.
+func (g *DedupGate) ShouldSkip(alert Alert) bool {
+	key := alert.DedupKey()
+	now := g.now()
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	// Opportunistic reap: drop entries past TTL. Cheap because the map
+	// is small (one entry per active alert tuple). Avoids unbounded
+	// growth under high churn.
+	for k, ts := range g.seen {
+		if now.Sub(ts) > g.ttl {
+			delete(g.seen, k)
+		}
+	}
+
+	if last, ok := g.seen[key]; ok {
+		if now.Sub(last) <= g.ttl {
+			return true
+		}
+	}
+	g.seen[key] = now
+	return false
+}
+
+// Size returns the number of tracked dedup keys. Test helper.
+func (g *DedupGate) Size() int {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return len(g.seen)
+}

app/internal/alertrouter/doc.go

@@ -0,0 +1,50 @@
+// Package alertrouter is the bridge between OpenWatch's in-process
+// event bus (internal/eventbus) and external notification channels
+// (Slack, email, webhook, PagerDuty).
+//
+// Spec: specs/system/alert-router.spec.yaml (status: approved)
+//
+// Architectural choices:
+//
+//   - Subscribes to EventKindHeartbeatPulse + EventKindDriftDetected on
+//     the bus at Start. A single dispatch goroutine reads from the
+//     subscription channels and translates each event to a typed Alert
+//     before fan-out. Spec C-08 / AC-11.
+//
+//   - Closed enums for AlertType and Severity. Each AlertType has a
+//     default Severity that the router applies before channel routing.
+//     Spec C-01 / C-02.
+//
+//   - In-memory dedup gate keyed by (alert_type, host_id, rule_id) with
+//     configurable TTL (default 60 min, range 60s..24h). Dedup state
+//     does NOT survive process restart — for v1, single-instance
+//     dedup is correct; multi-instance deploys can slot a Postgres
+//     store behind the same interface. Spec C-03 / C-04.
+//
+//   - Channel registration with tag-filter routing. Each channel
+//     declares a Tags map of required key/value pairs; an empty Tags
+//     map is a wildcard (channel receives every alert). Alert.Tags
+//     always carries at minimum severity + alert_type + host_id.
+//     Spec C-05 / C-06.
+//
+//   - Per-channel goroutine for Channel.Send. A Send returning an error
+//     increments that channel's FailureCount but does NOT halt delivery
+//     to other channels for the same alert. The router never panics on
+//     a channel-side error. Spec C-07 / AC-10.
+//
+//   - Router.Stop unsubscribes from the bus AND waits up to 10s for
+//     in-flight Channel.Send calls to complete (drain timeout). After
+//     Stop, new events arriving on the bus subscription are ignored.
+//     Spec C-08 / AC-12.
+//
+// Distinction from internal/audit: the audit log is the persistent
+// forensic record of who/what/when; the alert router is real-time
+// delivery to notification surfaces. Most alert-worthy events emit
+// to both — e.g., a major drift writes compliance.drift.detected to
+// the audit log AND fires through the alert router to Slack.
+//
+// Concrete Channel implementations (Slack, email, webhook) live in
+// subpackages so the core router has no external SDK dependencies.
+// This PR ships the interface + a fake (for tests) + stdout (for
+// dev/test scenarios). Spec C-09 / AC-13.
+package alertrouter

app/internal/alertrouter/metrics.go

@@ -0,0 +1,45 @@
+package alertrouter
+
+import "sync/atomic"
+
+// Metrics holds the router's runtime counters. Spec AC-14.
+type Metrics struct {
+	// ReceivedCount is the count of bus events the router translated
+	// into Alert values (pre-dedup).
+	ReceivedCount atomic.Int64
+
+	// RoutedCount is the count of (alert, channel) pairs where the
+	// channel's tag filter matched and Send was invoked. Counts each
+	// channel delivery for a fan-out alert.
+	RoutedCount atomic.Int64
+
+	// DedupedCount is the count of alerts skipped by the dedup gate.
+	// Per Spec C-03, these never reach Channel.Send.
+	DedupedCount atomic.Int64
+
+	// ChannelFailureCount is the aggregate count of Channel.Send calls
+	// that returned an error. Per-channel counters are tracked on
+	// channelEntry.failureCount.
+	ChannelFailureCount atomic.Int64
+}
+
+// NewMetrics returns a fresh Metrics.
+func NewMetrics() *Metrics { return &Metrics{} }
+
+// MetricsSnapshot is a JSON-friendly point-in-time snapshot.
+type MetricsSnapshot struct {
+	ReceivedCount       int64 `json:"received_count"`
+	RoutedCount         int64 `json:"routed_count"`
+	DedupedCount        int64 `json:"deduped_count"`
+	ChannelFailureCount int64 `json:"channel_failure_count"`
+}
+
+// Snapshot returns a point-in-time copy of all counters.
+func (m *Metrics) Snapshot() MetricsSnapshot {
+	return MetricsSnapshot{
+		ReceivedCount:       m.ReceivedCount.Load(),
+		RoutedCount:         m.RoutedCount.Load(),
+		DedupedCount:        m.DedupedCount.Load(),
+		ChannelFailureCount: m.ChannelFailureCount.Load(),
+	}
+}