feat: usage anomaly detector for 5-minute per-developer traffic spikes (#476)

[ironhood]

Summary

Closes #476

Adds a background worker that detects per-developer usage anomalies by comparing the most recently completed 5-minute traffic window against a rolling baseline (mean of the trailing 12 windows). When call volume exceeds baseline × multiplier, the worker emits a usage.anomaly.detected domain event, which fans out to matching developer webhook subscriptions.

• src/services/anomalyService.ts — pure detection logic, PostgreSQL window aggregation, deduplication, and event emission
• src/workers/anomalyDetector.ts — interval job with overlap guard and graceful shutdown hooks
• docs/usage-anomaly-detector.md — configuration, event payload, and metrics reference

Design

• Baseline: arithmetic mean of the 12 completed 5-minute windows immediately preceding the window under test
• Threshold: currentCalls > baselineMean × USAGE_ANOMALY_MULTIPLIER (default 5×)
• Scope: each developer is evaluated independently against their own history
• Missing windows: treated as zero calls so quiet periods do not inflate the baseline
• Dedup: in-memory per (developerId, windowStart) to avoid duplicate alerts within a window
• Logging: structured logs include a correlation ID via getOrCreateRequestId

Configuration

Variable	Default	Description
USAGE_ANOMALY_DETECTOR_ENABLED	true	Enable/disable the worker
USAGE_ANOMALY_MULTIPLIER	5	Spike threshold multiplier
USAGE_ANOMALY_POLL_INTERVAL_MS	300000	Scan interval (5 min)
USAGE_ANOMALY_WINDOW_MS	300000	Window size (5 min)
USAGE_ANOMALY_BASELINE_WINDOWS	12	Trailing windows for baseline

Event payload (usage.anomaly.detected)

{
  "windowStart": "2026-06-01T12:00:00.000Z",
  "windowEnd": "2026-06-01T12:05:00.000Z",
  "currentCalls": 100,
  "baselineMean": 10,
  "multiplier": 5,
  "ratio": 10,
  "windowMs": 300000
}

[drips-wave]

@ironhood Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits