palaryn 0.1.0 → 0.3.2

package/src/anomaly/detector.ts

@@ -0,0 +1,730 @@
+import { randomUUID } from 'crypto';
+import { ToolCall } from '../types/tool-call';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AnomalyConfig {
+  enabled: boolean;
+  /** Window size for rolling baseline in milliseconds (default: 3600000 = 1 hour) */
+  window_ms?: number;
+  /** Number of standard deviations before flagging anomaly (default: 3) */
+  z_score_threshold?: number;
+  /** Minimum number of data points before anomaly detection activates (default: 10) */
+  min_samples?: number;
+  /** Action on anomaly: 'log' just records, 'flag' adds to result metadata, 'block' denies the call */
+  action?: 'log' | 'flag' | 'block';
+  /** Per-actor tracking (default: true) */
+  track_actors?: boolean;
+  /** Per-tool tracking (default: true) */
+  track_tools?: boolean;
+  /** Per-workspace tracking (default: true) */
+  track_workspaces?: boolean;
+}
+
+export interface AnomalyAlert {
+  alert_id: string;
+  timestamp: string;
+  anomaly_type: AnomalyType;
+  entity_type: 'actor' | 'tool' | 'workspace';
+  entity_id: string;
+  /** The workspace that generated this alert (used for per-workspace filtering) */
+  workspace_id?: string;
+  metric: string;
+  current_value: number;
+  baseline_mean: number;
+  baseline_stddev: number;
+  z_score: number;
+  severity: 'low' | 'medium' | 'high';
+}
+
+export type AnomalyType =
+  | 'request_rate_spike'
+  | 'error_rate_spike'
+  | 'latency_spike'
+  | 'new_tool_usage'
+  | 'off_hours_activity'
+  | 'capability_escalation'
+  | 'unusual_payload_size';
+
+export interface AnomalyState {
+  windows: Record<string, { timestamps: number[]; values: number[] }>;
+  actorTools: Record<string, string[]>;
+  actorCaps: Record<string, string[]>;
+  alerts: AnomalyAlert[];
+}
+
+// ---------------------------------------------------------------------------
+// RollingWindow — rolling statistics tracker for a single metric
+// ---------------------------------------------------------------------------
+
+export class RollingWindow {
+  private timestamps: number[] = [];
+  private values: number[] = [];
+  private windowMs: number;
+
+  constructor(windowMs: number) {
+    this.windowMs = windowMs;
+  }
+
+  /** Add a data point */
+  record(value: number, timestamp?: number): void {
+    const now = timestamp || Date.now();
+    this.timestamps.push(now);
+    this.values.push(value);
+    this.prune(now);
+  }
+
+  /** Remove data points outside the window */
+  private prune(now: number): void {
+    const cutoff = now - this.windowMs;
+    while (this.timestamps.length > 0 && this.timestamps[0] < cutoff) {
+      this.timestamps.shift();
+      this.values.shift();
+    }
+  }
+
+  /** Get count of data points in window */
+  count(): number {
+    return this.values.length;
+  }
+
+  /** Get mean of values in window */
+  mean(): number {
+    if (this.values.length === 0) return 0;
+    return this.values.reduce((a, b) => a + b, 0) / this.values.length;
+  }
+
+  /** Get standard deviation (sample stddev) */
+  stddev(): number {
+    if (this.values.length < 2) return 0;
+    const m = this.mean();
+    const variance = this.values.reduce((sum, v) => sum + Math.pow(v - m, 2), 0) / (this.values.length - 1);
+    return Math.sqrt(variance);
+  }
+
+  /** Calculate z-score for a new value */
+  zScore(value: number): number {
+    const sd = this.stddev();
+    if (sd === 0) return 0;
+    return Math.abs((value - this.mean()) / sd);
+  }
+
+  /** Get rate (count / window duration in seconds) */
+  rate(): number {
+    this.prune(Date.now());
+    return this.values.length / (this.windowMs / 1000);
+  }
+
+  /** Reset window */
+  reset(): void {
+    this.timestamps = [];
+    this.values = [];
+  }
+
+  /** Serialize window state for persistence */
+  serialize(): { timestamps: number[]; values: number[] } {
+    return { timestamps: [...this.timestamps], values: [...this.values] };
+  }
+
+  /** Restore window state from serialized data */
+  static deserialize(data: { timestamps: number[]; values: number[] }, windowMs: number): RollingWindow {
+    const w = new RollingWindow(windowMs);
+    w.timestamps = [...data.timestamps];
+    w.values = [...data.values];
+    return w;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AnomalyDetector
+// ---------------------------------------------------------------------------
+
+export class AnomalyDetector {
+  private config: AnomalyConfig;
+
+  // Rolling windows keyed by "{entity_type}:{entity_id}:{metric}"
+  private windows: Map<string, RollingWindow> = new Map();
+
+  // Track which tools each actor has used (for new_tool_usage detection)
+  private actorToolHistory: Map<string, Set<string>> = new Map();
+
+  // Track capability levels per actor (for capability_escalation)
+  private actorCapabilityHistory: Map<string, Set<string>> = new Map();
+
+  // Track off-hours alerts to avoid flooding (key: "entity_id:hour")
+  private offHoursAlertedThisHour: Set<string> = new Set();
+
+  // Alert history
+  private alerts: AnomalyAlert[] = [];
+  private maxAlerts: number = 1000;
+
+  // Entity limits to prevent unbounded growth
+  private maxEntities: number;
+
+  // Track last update time per entity for eviction
+  private windowLastUpdated: Map<string, number> = new Map();
+  private actorToolLastUpdated: Map<string, number> = new Map();
+  private actorCapLastUpdated: Map<string, number> = new Map();
+
+  // Periodic cleanup interval
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: AnomalyConfig, options?: { maxEntities?: number }) {
+    this.config = config;
+    this.maxEntities = options?.maxEntities ?? 10000;
+
+    // Start periodic cleanup every 5 minutes
+    if (config.enabled) {
+      this.cleanupInterval = setInterval(() => this.cleanupStaleEntries(), 5 * 60 * 1000);
+      this.cleanupInterval.unref();
+    }
+  }
+
+  /** Stop the periodic cleanup interval. Call in tests or on shutdown. */
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /** Remove entries that haven't been updated within the window duration. */
+  private cleanupStaleEntries(): void {
+    const windowMs = this.config.window_ms || 3600000;
+    const cutoff = Date.now() - windowMs;
+
+    for (const [key, lastUpdate] of this.windowLastUpdated) {
+      if (lastUpdate < cutoff) {
+        this.windows.delete(key);
+        this.windowLastUpdated.delete(key);
+      }
+    }
+
+    for (const [key, lastUpdate] of this.actorToolLastUpdated) {
+      if (lastUpdate < cutoff) {
+        this.actorToolHistory.delete(key);
+        this.actorToolLastUpdated.delete(key);
+      }
+    }
+
+    for (const [key, lastUpdate] of this.actorCapLastUpdated) {
+      if (lastUpdate < cutoff) {
+        this.actorCapabilityHistory.delete(key);
+        this.actorCapLastUpdated.delete(key);
+      }
+    }
+
+    // Clean up stale off-hours throttle keys
+    this.offHoursAlertedThisHour.clear();
+  }
+
+  /** Evict the oldest entry from a map+timestamps pair when over limit. */
+  private evictOldest(timestamps: Map<string, number>, dataMap: Map<string, any>): void {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+    for (const [key, time] of timestamps) {
+      if (time < oldestTime) {
+        oldestTime = time;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey) {
+      timestamps.delete(oldestKey);
+      dataMap.delete(oldestKey);
+    }
+  }
+
+  /**
+   * Analyze a tool call for anomalies. Called in the gateway pipeline.
+   * Returns an array of anomaly alerts (empty if no anomalies detected).
+   */
+  analyze(toolCall: ToolCall): AnomalyAlert[] {
+    if (!this.config.enabled) return [];
+
+    const alerts: AnomalyAlert[] = [];
+    const now = Date.now();
+
+    // 1. Request rate tracking (per actor, per tool, per workspace)
+    if (this.config.track_actors !== false) {
+      alerts.push(...this.checkRequestRate('actor', toolCall.actor.id, now));
+    }
+    if (this.config.track_tools !== false) {
+      alerts.push(...this.checkRequestRate('tool', toolCall.tool.name, now));
+    }
+    if (this.config.track_workspaces !== false) {
+      alerts.push(...this.checkRequestRate('workspace', toolCall.workspace_id, now));
+    }
+
+    // 2. New tool usage detection
+    if (this.config.track_actors !== false) {
+      const newToolAlert = this.checkNewToolUsage(toolCall.actor.id, toolCall.tool.name);
+      if (newToolAlert) alerts.push(newToolAlert);
+    }
+
+    // 3. Capability escalation detection
+    if (this.config.track_actors !== false) {
+      const capAlert = this.checkCapabilityEscalation(toolCall.actor.id, toolCall.tool.capability);
+      if (capAlert) alerts.push(capAlert);
+    }
+
+    // 4. Off-hours activity (weekends or 22:00-06:00 UTC)
+    const offHoursAlert = this.checkOffHours(toolCall.actor.id, now);
+    if (offHoursAlert) alerts.push(offHoursAlert);
+
+    // Stamp workspace_id and store alerts
+    for (const alert of alerts) {
+      alert.workspace_id = toolCall.workspace_id;
+      this.alerts.push(alert);
+      if (this.alerts.length > this.maxAlerts) {
+        this.alerts.shift();
+      }
+    }
+
+    return alerts;
+  }
+
+  /**
+   * Record the result of a tool execution for latency/error tracking.
+   * Called after execution completes.
+   */
+  recordResult(toolCall: ToolCall, durationMs: number, isError: boolean): void {
+    if (!this.config.enabled) return;
+
+    // Track latency per tool
+    const latencyKey = `tool:${toolCall.tool.name}:latency`;
+    this.getOrCreateWindow(latencyKey).record(durationMs);
+
+    // Track error rate per actor
+    const errorKey = `actor:${toolCall.actor.id}:error_rate`;
+    this.getOrCreateWindow(errorKey).record(isError ? 1 : 0);
+  }
+
+  /**
+   * Check if a new latency/error reading is anomalous.
+   * Returns alerts for latency spikes and error rate spikes.
+   */
+  analyzeResult(toolCall: ToolCall, durationMs: number, isError: boolean): AnomalyAlert[] {
+    if (!this.config.enabled) return [];
+
+    const alerts: AnomalyAlert[] = [];
+    const threshold = this.config.z_score_threshold || 3;
+    const minSamples = this.config.min_samples || 10;
+
+    // Check latency anomaly
+    const latencyKey = `tool:${toolCall.tool.name}:latency`;
+    const latencyWindow = this.getOrCreateWindow(latencyKey);
+    if (latencyWindow.count() >= minSamples) {
+      const z = latencyWindow.zScore(durationMs);
+      if (z > threshold) {
+        alerts.push(this.createAlert(
+          'latency_spike', 'tool', toolCall.tool.name,
+          'latency_ms', durationMs, latencyWindow.mean(), latencyWindow.stddev(), z
+        ));
+      }
+    }
+
+    // Check error rate anomaly
+    if (isError) {
+      const errorKey = `actor:${toolCall.actor.id}:error_rate`;
+      const errorWindow = this.getOrCreateWindow(errorKey);
+      if (errorWindow.count() >= minSamples) {
+        const errorRate = errorWindow.mean();
+        // If error rate was low (actor mostly succeeds) and now seeing errors
+        if (errorRate < 0.1 && errorWindow.count() > minSamples) {
+          const sd = errorWindow.stddev();
+          const z = sd > 0 ? (1 - errorRate) / sd : threshold + 1;
+          alerts.push(this.createAlert(
+            'error_rate_spike', 'actor', toolCall.actor.id,
+            'error_rate', 1, errorRate, sd, z
+          ));
+        }
+      }
+    }
+
+    // Stamp workspace_id and store alerts
+    for (const alert of alerts) {
+      alert.workspace_id = toolCall.workspace_id;
+      this.alerts.push(alert);
+      if (this.alerts.length > this.maxAlerts) {
+        this.alerts.shift();
+      }
+    }
+
+    return alerts;
+  }
+
+  /** Get recent alerts, optionally filtered by workspace */
+  getAlerts(limit?: number, workspaceId?: string): AnomalyAlert[] {
+    const n = limit || 100;
+    const filtered = workspaceId
+      ? this.alerts.filter(a => a.workspace_id === workspaceId)
+      : this.alerts;
+    return filtered.slice(-n);
+  }
+
+  /** Get alerts for a specific entity */
+  getAlertsForEntity(entityType: string, entityId: string): AnomalyAlert[] {
+    return this.alerts.filter(a => a.entity_type === entityType && a.entity_id === entityId);
+  }
+
+  /** Get baseline stats for an entity+metric */
+  getBaseline(entityType: string, entityId: string, metric: string): { mean: number; stddev: number; count: number } | null {
+    const key = `${entityType}:${entityId}:${metric}`;
+    const window = this.windows.get(key);
+    if (!window || window.count() === 0) return null;
+    return { mean: window.mean(), stddev: window.stddev(), count: window.count() };
+  }
+
+  /** Get a baseline report suitable for the anomaly radar dashboard widget.
+   *  When workspaceId is provided, only alerts from that workspace are included. */
+  getBaselineReport(workspaceId?: string): {
+    current: Record<string, number>;
+    baseline: Record<string, number>;
+    alerts: AnomalyAlert[];
+  } {
+    const current: Record<string, number> = {
+      request_rate: 0,
+      error_rate: 0,
+      latency: 0,
+      new_tools: 0,
+      capability_escalations: 0,
+      off_hours: 0,
+    };
+    const baseline: Record<string, number> = {
+      request_rate: 0,
+      error_rate: 0,
+      latency: 0,
+      new_tools: 0,
+      capability_escalations: 0,
+      off_hours: 0,
+    };
+
+    // Aggregate request_rate from actor request rate windows
+    let rateCount = 0;
+    let rateSum = 0;
+    let rateMeanSum = 0;
+    for (const [key, window] of this.windows) {
+      if (key.endsWith(':request_rate')) {
+        rateSum += window.rate();
+        rateMeanSum += window.mean();
+        rateCount++;
+      }
+    }
+    if (rateCount > 0) {
+      current.request_rate = rateSum / rateCount;
+      baseline.request_rate = rateMeanSum / rateCount;
+    }
+
+    // Aggregate error_rate from actor error rate windows
+    let errorCount = 0;
+    let errorSum = 0;
+    let errorMeanSum = 0;
+    for (const [key, window] of this.windows) {
+      if (key.endsWith(':error_rate')) {
+        errorSum += window.mean(); // current error rate is the mean of recent 0/1 values
+        errorMeanSum += window.mean();
+        errorCount++;
+      }
+    }
+    if (errorCount > 0) {
+      current.error_rate = errorSum / errorCount;
+      baseline.error_rate = errorMeanSum / errorCount;
+    }
+
+    // Aggregate latency from tool latency windows
+    let latCount = 0;
+    let latSum = 0;
+    let latMeanSum = 0;
+    for (const [key, window] of this.windows) {
+      if (key.endsWith(':latency')) {
+        // Current value: use the mean of recent readings as the "current" value
+        latSum += window.mean();
+        latMeanSum += window.mean();
+        latCount++;
+      }
+    }
+    if (latCount > 0) {
+      current.latency = latSum / latCount;
+      baseline.latency = latMeanSum / latCount;
+    }
+
+    // Filter alerts by workspace if specified
+    const wsAlerts = workspaceId
+      ? this.alerts.filter(a => a.workspace_id === workspaceId)
+      : this.alerts;
+
+    // Count alert types from filtered alert history
+    current.new_tools = wsAlerts.filter(a => a.anomaly_type === 'new_tool_usage').length;
+    current.capability_escalations = wsAlerts.filter(a => a.anomaly_type === 'capability_escalation').length;
+    current.off_hours = wsAlerts.filter(a => a.anomaly_type === 'off_hours_activity').length;
+
+    return {
+      current,
+      baseline,
+      alerts: [...wsAlerts],
+    };
+  }
+
+  /** Reset all tracking data */
+  reset(): void {
+    this.windows.clear();
+    this.windowLastUpdated.clear();
+    this.actorToolHistory.clear();
+    this.actorToolLastUpdated.clear();
+    this.actorCapabilityHistory.clear();
+    this.actorCapLastUpdated.clear();
+    this.offHoursAlertedThisHour.clear();
+    this.alerts = [];
+  }
+
+  /** Export all state for persistence. Returns a JSON-serializable object. */
+  exportState(): AnomalyState {
+    const windows: Record<string, { timestamps: number[]; values: number[] }> = {};
+    for (const [key, window] of this.windows) {
+      windows[key] = window.serialize();
+    }
+    const actorTools: Record<string, string[]> = {};
+    for (const [actor, tools] of this.actorToolHistory) {
+      actorTools[actor] = [...tools];
+    }
+    const actorCaps: Record<string, string[]> = {};
+    for (const [actor, caps] of this.actorCapabilityHistory) {
+      actorCaps[actor] = [...caps];
+    }
+    return { windows, actorTools, actorCaps, alerts: [...this.alerts] };
+  }
+
+  /** Import state from a previously exported snapshot. */
+  importState(state: AnomalyState): void {
+    const windowMs = this.config.window_ms || 3600000;
+    this.windows.clear();
+    for (const [key, data] of Object.entries(state.windows)) {
+      this.windows.set(key, RollingWindow.deserialize(data, windowMs));
+    }
+    this.actorToolHistory.clear();
+    for (const [actor, tools] of Object.entries(state.actorTools)) {
+      this.actorToolHistory.set(actor, new Set(tools));
+    }
+    this.actorCapabilityHistory.clear();
+    for (const [actor, caps] of Object.entries(state.actorCaps)) {
+      this.actorCapabilityHistory.set(actor, new Set(caps));
+    }
+    this.alerts = [...state.alerts];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private getOrCreateWindow(key: string): RollingWindow {
+    let window = this.windows.get(key);
+    if (!window) {
+      // Evict oldest if at capacity
+      if (this.windows.size >= this.maxEntities) {
+        this.evictOldest(this.windowLastUpdated, this.windows);
+      }
+      window = new RollingWindow(this.config.window_ms || 3600000);
+      this.windows.set(key, window);
+    }
+    this.windowLastUpdated.set(key, Date.now());
+    return window;
+  }
+
+  private checkRequestRate(entityType: 'actor' | 'tool' | 'workspace', entityId: string, now: number): AnomalyAlert[] {
+    const alerts: AnomalyAlert[] = [];
+    const threshold = this.config.z_score_threshold || 3;
+    const minSamples = this.config.min_samples || 10;
+
+    const rateKey = `${entityType}:${entityId}:request_rate`;
+    const window = this.getOrCreateWindow(rateKey);
+
+    // Before recording this data point, check if the new rate would be anomalous
+    // We use inter-arrival intervals to detect rate spikes:
+    // Record a value of 1 for each request, then check the count-based rate
+    const countBefore = window.count();
+
+    // Record this request
+    window.record(1, now);
+
+    // Only check for anomalies if we have enough samples
+    if (countBefore >= minSamples) {
+      // Use a separate window for interval tracking
+      const intervalKey = `${entityType}:${entityId}:request_interval`;
+      const intervalWindow = this.getOrCreateWindow(intervalKey);
+
+      if (intervalWindow.count() >= minSamples) {
+        // Compute current rate as count in last sub-window
+        const currentRate = window.count();
+        const z = intervalWindow.zScore(currentRate);
+        if (z > threshold) {
+          alerts.push(this.createAlert(
+            'request_rate_spike', entityType, entityId,
+            'request_rate', currentRate, intervalWindow.mean(), intervalWindow.stddev(), z
+          ));
+        }
+      }
+
+      // Record the current count as a data point for interval tracking
+      intervalWindow.record(window.count(), now);
+    } else {
+      // Bootstrap: record the count
+      const intervalKey = `${entityType}:${entityId}:request_interval`;
+      const intervalWindow = this.getOrCreateWindow(intervalKey);
+      intervalWindow.record(window.count(), now);
+    }
+
+    return alerts;
+  }
+
+  private checkNewToolUsage(actorId: string, toolName: string): AnomalyAlert | null {
+    let tools = this.actorToolHistory.get(actorId);
+    if (!tools) {
+      // Evict oldest if at capacity
+      if (this.actorToolHistory.size >= this.maxEntities) {
+        this.evictOldest(this.actorToolLastUpdated, this.actorToolHistory);
+      }
+      tools = new Set<string>();
+      this.actorToolHistory.set(actorId, tools);
+    }
+    this.actorToolLastUpdated.set(actorId, Date.now());
+
+    if (tools.has(toolName)) {
+      return null; // Already used this tool before
+    }
+
+    // This is a new tool for this actor
+    const isFirstEver = tools.size === 0;
+    tools.add(toolName);
+
+    // Don't alert on the very first tool an actor uses (that's normal bootstrapping)
+    if (isFirstEver) {
+      return null;
+    }
+
+    return this.createAlert(
+      'new_tool_usage', 'actor', actorId,
+      'new_tool', 1, 0, 0, 0,
+      'low'
+    );
+  }
+
+  private checkCapabilityEscalation(actorId: string, capability: string): AnomalyAlert | null {
+    let caps = this.actorCapabilityHistory.get(actorId);
+    if (!caps) {
+      // Evict oldest if at capacity
+      if (this.actorCapabilityHistory.size >= this.maxEntities) {
+        this.evictOldest(this.actorCapLastUpdated, this.actorCapabilityHistory);
+      }
+      caps = new Set<string>();
+      this.actorCapabilityHistory.set(actorId, caps);
+    }
+    this.actorCapLastUpdated.set(actorId, Date.now());
+
+    if (caps.has(capability)) {
+      return null; // Already used this capability
+    }
+
+    const isFirstEver = caps.size === 0;
+    caps.add(capability);
+
+    // Don't alert on the first capability
+    if (isFirstEver) {
+      return null;
+    }
+
+    // Determine severity based on escalation level
+    const capOrder: Record<string, number> = { read: 0, write: 1, delete: 2, admin: 3 };
+    const newLevel = capOrder[capability] ?? 0;
+
+    // Find the max level previously used
+    let maxPrevLevel = 0;
+    for (const prevCap of caps) {
+      if (prevCap !== capability) {
+        const level = capOrder[prevCap] ?? 0;
+        if (level > maxPrevLevel) maxPrevLevel = level;
+      }
+    }
+
+    // Only alert if this is an escalation (higher than any previous capability)
+    if (newLevel <= maxPrevLevel) {
+      return null;
+    }
+
+    let severity: 'low' | 'medium' | 'high' = 'low';
+    if (capability === 'admin') {
+      severity = 'high';
+    } else if (capability === 'delete') {
+      severity = 'medium';
+    } else if (capability === 'write' && maxPrevLevel === 0) {
+      severity = 'low';
+    }
+
+    return this.createAlert(
+      'capability_escalation', 'actor', actorId,
+      'capability_level', newLevel, maxPrevLevel, 0, 0,
+      severity
+    );
+  }
+
+  private checkOffHours(actorId: string, now: number): AnomalyAlert | null {
+    const date = new Date(now);
+    const hour = date.getUTCHours();
+    const day = date.getUTCDay(); // 0 = Sunday, 6 = Saturday
+
+    const isOffHours = hour >= 22 || hour < 6;
+    const isWeekend = day === 0 || day === 6;
+
+    if (!isOffHours && !isWeekend) {
+      return null;
+    }
+
+    // Throttle: only alert once per entity per hour
+    const hourKey = `${actorId}:${date.getUTCFullYear()}-${date.getUTCMonth()}-${date.getUTCDate()}-${hour}`;
+    if (this.offHoursAlertedThisHour.has(hourKey)) {
+      return null;
+    }
+    this.offHoursAlertedThisHour.add(hourKey);
+
+    const severity: 'low' | 'medium' | 'high' = isWeekend && isOffHours ? 'medium' : 'low';
+
+    return this.createAlert(
+      'off_hours_activity', 'actor', actorId,
+      'hour_utc', hour, 12, 0, 0,
+      severity
+    );
+  }
+
+  private createAlert(
+    anomalyType: AnomalyType,
+    entityType: 'actor' | 'tool' | 'workspace',
+    entityId: string,
+    metric: string,
+    currentValue: number,
+    baselineMean: number,
+    baselineStddev: number,
+    zScore: number,
+    overrideSeverity?: 'low' | 'medium' | 'high',
+  ): AnomalyAlert {
+    return {
+      alert_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      anomaly_type: anomalyType,
+      entity_type: entityType,
+      entity_id: entityId,
+      metric,
+      current_value: currentValue,
+      baseline_mean: baselineMean,
+      baseline_stddev: baselineStddev,
+      z_score: zScore,
+      severity: overrideSeverity || this.classifySeverity(zScore),
+    };
+  }
+
+  private classifySeverity(zScore: number): 'low' | 'medium' | 'high' {
+    if (zScore >= 6) return 'high';
+    if (zScore >= 4) return 'medium';
+    return 'low';
+  }
+}