@checkstack/anomaly-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# @checkstack/anomaly-common
+
+## 0.2.0
+
+### Minor Changes
+
+- 8d1ef12: ## Anomaly Detection & UI Improvements
+
+  ### Anomaly Detection Enhancements (Phase 2)
+
+  - **`@checkstack/anomaly-backend`**: Implemented background baseline analyzer jobs and anomaly trend deviation detection mechanics.
+  - **`@checkstack/anomaly-common`**: Added new baseline statistical logic and inference rules.
+  - **`@checkstack/anomaly-frontend`**: Added new Anomaly Widget and refactored system detail rendering to be more human-readable.
+  - **`@checkstack/dashboard-frontend`**: Refined the global anomaly widget and fixed hardcoded access gating to render appropriately.
+  - **`@checkstack/healthcheck-backend`**: Connected executor telemetry to the anomaly pipeline.
+  - **`@checkstack/healthcheck-frontend`**: Reconciled baseline display consistency in Drawer and charts.
+
+  ### Notification Identifiers
+
+  - **`@checkstack/incident-backend`**: Resolved system IDs to human-readable System Names within Incident notifications to eliminate ID-only alert content.
+  - **`@checkstack/maintenance-backend`**: Adopted the same resolution strategy for Maintenance notifications to keep parity.
+
+  ### UI Experience
+
+  - **`@checkstack/incident-frontend`**: Fixed the "Back to X" BackLink to properly use `react-router` hook `useNavigate` instead of doing a full application reload.
+  - **`@checkstack/healthcheck-frontend`**: Implemented `useNavigate` for seamless SPA back-linking.
+  - **`@checkstack/integration-frontend`**: Updated connections and delivery logs links to navigate without hard reloads.
+
+- 8d1ef12: Phase 2 of anomaly detection: trend drift detection.
+
+  The background baseline analyzer now computes a linear regression slope across each field's chronologically-ordered history and runs a `detectDrift` evaluator that catches gradual "creeping degradation" never reaching the 3σ spike threshold. Drifts share the same `anomalies` table as spike anomalies via a new `kind` column (`spike` | `drift`, default `spike`); the existing suspicious → anomaly → recovered lifecycle is reused, ticking at the analyzer's hourly cadence with a default 2-run confirmation window.
+
+  User-facing additions: a Trend Drift toggle and threshold slider on both the template and assignment anomaly settings panels (with per-field overrides), drift rows in the System Anomaly widget, dashed regression-line overlays on the auto-generated line charts, and a new `ANOMALY_TREND_DETECTED` signal for live UI updates. Plugin authors can disable drift per chartable field via `x-anomaly-drift-enabled: false` or tighten/loosen it via `x-anomaly-drift-threshold`.
+
+- 8d1ef12: Added Categorical Anomaly Detection (Dominance Drift) support for non-numeric healthcheck values, and introduced Slider UI components for sensitivity and confirmation window anomaly settings.
+
+### Patch Changes
+
+- Updated dependencies [8d1ef12]
+  - @checkstack/common@0.7.0
+  - @checkstack/signal-common@0.1.10

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@checkstack/anomaly-common",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.5",
+    "@checkstack/signal-common": "0.1.9",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,25 @@
+import { accessPair } from "@checkstack/common";
+
+export const anomalyAccess = {
+  feed: accessPair(
+    "anomaly_feed",
+    {
+      read: {
+        description: "View anomaly feed and status badges",
+        isDefault: true,
+        isPublic: true,
+      },
+      manage: {
+        description: "Manage anomaly configuration and noise floors",
+      },
+    },
+    {
+      idParam: "systemId",
+    }
+  ),
+};
+
+export const anomalyAccessRules = [
+  anomalyAccess.feed.read,
+  anomalyAccess.feed.manage,
+];

package/src/engine/baseline.test.ts

@@ -0,0 +1,94 @@
+import { describe, test, expect } from "bun:test";
+import { computeMean, computeStdDev, computeLinearRegressionSlope, computeDominance } from "./baseline";
+
+describe("Anomaly Engine - Baseline Mathematics", () => {
+  describe("computeMean", () => {
+    test("computes correct mean for standard array", () => {
+      expect(computeMean([2, 4, 6, 8])).toBe(5);
+      expect(computeMean([1, 1, 1, 1])).toBe(1);
+    });
+
+    test("returns 0 for empty array", () => {
+      expect(computeMean([])).toBe(0);
+    });
+
+    test("handles negative numbers and decimals", () => {
+      expect(computeMean([-1.5, 2.5, 0])).toBeCloseTo(0.33333333, 5);
+      expect(computeMean([-10, -20, -30])).toBe(-20);
+    });
+  });
+
+  describe("computeStdDev", () => {
+    test("computes correct population standard deviation", () => {
+      // Variance = 5, StdDev = sqrt(5) ≈ 2.236
+      expect(computeStdDev([2, 4, 4, 4, 5, 5, 7, 9])).toBeCloseTo(2.0, 5);
+      
+      // Simple 0,2,4 -> mean 2 -> sum(sq(diff)) = 4+0+4 = 8 -> var = 8/3 = 2.666
+      // sqrt(2.666) ≈ 1.63299
+      expect(computeStdDev([0, 2, 4])).toBeCloseTo(1.63299, 5);
+    });
+
+    test("returns 0 for single item or empty array", () => {
+      expect(computeStdDev([5])).toBe(0);
+      expect(computeStdDev([])).toBe(0);
+    });
+
+    test("uses provided mean to optimize", () => {
+      // 0, 2, 4, mean = 2
+      expect(computeStdDev([0, 2, 4], 2)).toBeCloseTo(1.63299, 5);
+    });
+  });
+
+  describe("computeLinearRegressionSlope", () => {
+    test("computes correct slope for perfectly linear data", () => {
+      expect(computeLinearRegressionSlope([0, 2, 4, 6, 8])).toBe(2);
+      expect(computeLinearRegressionSlope([10, 8, 6, 4])).toBe(-2);
+      expect(computeLinearRegressionSlope([5, 5, 5, 5])).toBe(0);
+    });
+
+    test("computes correct slope for noisy data", () => {
+      const values = [1, 3, 2, 4, 5];
+      // x: 0,1,2,3,4. mean x: 2. y: 1,3,2,4,5. mean y: 3
+      // cov(x,y)/var(x) -> 0.9
+      expect(computeLinearRegressionSlope(values)).toBeCloseTo(0.9, 5);
+    });
+
+    test("returns 0 for insufficient data", () => {
+      expect(computeLinearRegressionSlope([5])).toBe(0);
+      expect(computeLinearRegressionSlope([])).toBe(0);
+    });
+  });
+
+  describe("computeDominance", () => {
+    test("computes correct dominance ratio and value", () => {
+      const result = computeDominance(["success", "success", "error", "success", "timeout"]);
+      expect(result.dominantValue).toBe("success");
+      expect(result.dominantRatio).toBe(0.6); // 3 / 5
+    });
+
+    test("handles boolean values", () => {
+      const result = computeDominance([true, true, false]);
+      expect(result.dominantValue).toBe(true);
+      expect(result.dominantRatio).toBeCloseTo(0.6667, 4);
+    });
+
+    test("handles numeric values", () => {
+      const result = computeDominance([200, 200, 404, 500, 200]);
+      expect(result.dominantValue).toBe(200);
+      expect(result.dominantRatio).toBe(0.6);
+    });
+
+    test("returns empty object for empty array", () => {
+      const result = computeDominance([]);
+      expect(result.dominantValue).toBeUndefined();
+      expect(result.dominantRatio).toBeUndefined();
+    });
+
+    test("returns first dominant value if tied", () => {
+      const result = computeDominance(["a", "b", "a", "b"]);
+      // "a" was reached count=2 first
+      expect(result.dominantValue).toBe("a");
+      expect(result.dominantRatio).toBe(0.5);
+    });
+  });
+});

package/src/engine/baseline.ts

@@ -0,0 +1,56 @@
+export function computeMean(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sum = values.reduce((a, b) => a + b, 0);
+  return sum / values.length;
+}
+
+export function computeStdDev(values: number[], mean?: number): number {
+  if (values.length <= 1) return 0;
+  const m = mean ?? computeMean(values);
+  const variance = values.reduce((sq, n) => sq + Math.pow(n - m, 2), 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+export function computeLinearRegressionSlope(values: number[]): number {
+  if (values.length <= 1) return 0;
+  // x = index, y = value
+  const n = values.length;
+  let sumX = 0;
+  let sumY = 0;
+  let sumXY = 0;
+  let sumXX = 0;
+
+  for (let i = 0; i < n; i++) {
+    sumX += i;
+    sumY += values[i];
+    sumXY += i * values[i];
+    sumXX += i * i;
+  }
+
+  const denominator = (n * sumXX - sumX * sumX);
+  if (denominator === 0) return 0;
+  
+  return (n * sumXY - sumX * sumY) / denominator;
+}
+
+export function computeDominance(values: (string | boolean | number)[]): { dominantValue?: string | boolean | number, dominantRatio?: number } {
+  if (values.length === 0) return {};
+  
+  const counts = new Map<string | boolean | number, number>();
+  let maxCount = 0;
+  let dominantValue: string | boolean | number | undefined = undefined;
+
+  for (const v of values) {
+    const count = (counts.get(v) || 0) + 1;
+    counts.set(v, count);
+    if (count > maxCount) {
+      maxCount = count;
+      dominantValue = v;
+    }
+  }
+
+  return {
+    dominantValue,
+    dominantRatio: maxCount / values.length,
+  };
+}

package/src/engine/config.test.ts

@@ -0,0 +1,211 @@
+import { describe, test, expect } from "bun:test";
+import { resolveEffectiveConfig } from "./config";
+import type { AnomalySettings } from "../schema";
+
+describe("Anomaly Engine - Config Override Mechanism", () => {
+  const defaultTemplate: AnomalySettings = {
+    enabled: true,
+    sensitivity: 1,
+    confirmationWindow: 3,
+    baselineWindow: "7d",
+    notify: true,
+    driftEnabled: true,
+    driftThreshold: 2,
+    fieldOverrides: {},
+  };
+
+  test("uses defaults when nothing is provided", () => {
+    const result = resolveEffectiveConfig("some.field");
+    expect(result.enabled).toBe(true);
+    expect(result.sensitivity).toBe(1);
+    expect(result.confirmationWindow).toBe(3);
+    expect(result.direction).toBeUndefined();
+    expect(result.driftEnabled).toBe(true);
+    expect(result.driftThreshold).toBe(2);
+  });
+
+  test("uses template configuration as base", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      enabled: false,
+      sensitivity: 2,
+      confirmationWindow: 5,
+    };
+    const result = resolveEffectiveConfig("some.field", template);
+    expect(result.enabled).toBe(false);
+    expect(result.sensitivity).toBe(2);
+    expect(result.confirmationWindow).toBe(5);
+  });
+
+  test("assignment overrides template global settings", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      sensitivity: 1,
+      confirmationWindow: 3,
+    };
+    const assignment: Partial<AnomalySettings> = {
+      sensitivity: 3,
+      confirmationWindow: 1,
+    };
+    const result = resolveEffectiveConfig("some.field", template, assignment);
+    expect(result.sensitivity).toBe(3);
+    expect(result.confirmationWindow).toBe(1);
+    expect(result.enabled).toBe(true); // fallbacks to template
+  });
+
+  test("template field override overrides template global", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      sensitivity: 1,
+      fieldOverrides: {
+        "some.field": {
+          sensitivity: 5,
+        },
+      },
+    };
+    const result = resolveEffectiveConfig("some.field", template);
+    expect(result.sensitivity).toBe(5);
+  });
+
+  test("assignment field override takes absolute precedence", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      sensitivity: 1,
+      fieldOverrides: {
+        "some.field": {
+          sensitivity: 5, // template field level
+        },
+      },
+    };
+    const assignment: Partial<AnomalySettings> = {
+      sensitivity: 2, // assignment global level
+      fieldOverrides: {
+        "some.field": {
+          sensitivity: 10, // assignment field level
+        },
+      },
+    };
+    const result = resolveEffectiveConfig("some.field", template, assignment);
+    expect(result.sensitivity).toBe(10);
+  });
+
+  test("template field override is not overridden by assignment global", () => {
+    // This is intentional: field-level overrides (from any layer) represent
+    // more specific intent and take precedence over global overrides.
+    // See resolveEffectiveConfig JSDoc for the full resolution order.
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      fieldOverrides: {
+        "some.field": {
+          enabled: false,
+        },
+      },
+    };
+    const assignment: Partial<AnomalySettings> = {
+      enabled: true,
+    };
+    const result = resolveEffectiveConfig("some.field", template, assignment);
+    
+    // fieldConfig exists (template field: { enabled: false })
+    // So fieldConfig.enabled is false — field-level is more specific than assignment global.
+    expect(result.enabled).toBe(false);
+  });
+
+  test("template field override sets direction", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      fieldOverrides: {
+        "some.field": {
+          direction: "higher-is-better",
+        },
+      },
+    };
+    const result = resolveEffectiveConfig("some.field", template);
+    expect(result.direction).toBe("higher-is-better");
+  });
+
+  test("assignment field override direction beats template field direction", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      fieldOverrides: {
+        "some.field": { direction: "lower-is-better" },
+      },
+    };
+    const assignment: Partial<AnomalySettings> = {
+      fieldOverrides: {
+        "some.field": { direction: "deviation" },
+      },
+    };
+    const result = resolveEffectiveConfig("some.field", template, assignment);
+    expect(result.direction).toBe("deviation");
+  });
+
+  test("direction is undefined when no override sets it (caller falls back to schema)", () => {
+    const result = resolveEffectiveConfig("some.field", defaultTemplate);
+    expect(result.direction).toBeUndefined();
+  });
+
+  test("preserves explicit falsy values", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      sensitivity: 2,
+    };
+    const assignment: Partial<AnomalySettings> = {
+      sensitivity: 0,
+    };
+    const result = resolveEffectiveConfig("some.field", template, assignment);
+    expect(result.sensitivity).toBe(0);
+  });
+
+  describe("drift settings", () => {
+    test("template driftEnabled is honored", () => {
+      const template: AnomalySettings = {
+        ...defaultTemplate,
+        driftEnabled: false,
+      };
+      const result = resolveEffectiveConfig("some.field", template);
+      expect(result.driftEnabled).toBe(false);
+    });
+
+    test("assignment driftEnabled overrides template", () => {
+      const template: AnomalySettings = {
+        ...defaultTemplate,
+        driftEnabled: true,
+      };
+      const assignment: Partial<AnomalySettings> = { driftEnabled: false };
+      const result = resolveEffectiveConfig("some.field", template, assignment);
+      expect(result.driftEnabled).toBe(false);
+    });
+
+    test("field-level driftEnabled wins over assignment global", () => {
+      const template: AnomalySettings = {
+        ...defaultTemplate,
+        fieldOverrides: {
+          "some.field": { driftEnabled: false },
+        },
+      };
+      const assignment: Partial<AnomalySettings> = { driftEnabled: true };
+      const result = resolveEffectiveConfig("some.field", template, assignment);
+      expect(result.driftEnabled).toBe(false);
+    });
+
+    test("driftThreshold cascades through layers", () => {
+      const template: AnomalySettings = { ...defaultTemplate, driftThreshold: 3 };
+      const assignment: Partial<AnomalySettings> = { driftThreshold: 1.5 };
+      const result = resolveEffectiveConfig("some.field", template, assignment);
+      expect(result.driftThreshold).toBe(1.5);
+    });
+
+    test("field-level driftThreshold wins over assignment global", () => {
+      const template: AnomalySettings = {
+        ...defaultTemplate,
+        fieldOverrides: {
+          "some.field": { driftThreshold: 4 },
+        },
+      };
+      const assignment: Partial<AnomalySettings> = { driftThreshold: 1.5 };
+      const result = resolveEffectiveConfig("some.field", template, assignment);
+      expect(result.driftThreshold).toBe(4);
+    });
+  });
+});

package/src/engine/config.ts

@@ -0,0 +1,71 @@
+import type { AnomalySettings, AnomalyDirection } from "../schema";
+
+export interface EffectiveConfig {
+  enabled: boolean;
+  sensitivity: number;
+  confirmationWindow: number;
+  direction?: AnomalyDirection;
+  driftEnabled: boolean;
+  driftThreshold: number;
+}
+
+/**
+ * Resolves the effective anomaly detection config for a specific field path
+ * using the Three-Layer Override Model.
+ *
+ * Resolution order (highest to lowest precedence):
+ * 1. Assignment field override (most specific — user override for a specific field on a specific system)
+ * 2. Template field override (plugin developer annotation for a specific field)
+ * 3. Assignment global (user override for the entire system assignment)
+ * 4. Template global (plugin developer default for the entire health check)
+ * 5. Engine defaults (hardcoded fallback values)
+ *
+ * Note: Field-level overrides always win over global overrides because they
+ * represent more specific intent. If a template marks a field as `enabled: false`,
+ * only an assignment-level field override can re-enable it — the assignment global
+ * `enabled: true` won't override it, since the template field config is more specific.
+ */
+export function resolveEffectiveConfig(
+  path: string,
+  templateConfig?: AnomalySettings,
+  assignmentConfig?: Partial<AnomalySettings>
+): EffectiveConfig {
+  const fieldConfig = assignmentConfig?.fieldOverrides?.[path] ?? templateConfig?.fieldOverrides?.[path];
+  
+  const enabled = fieldConfig?.enabled 
+    ?? assignmentConfig?.enabled 
+    ?? templateConfig?.enabled 
+    ?? true;
+
+  const sensitivity = fieldConfig?.sensitivity 
+    ?? assignmentConfig?.sensitivity 
+    ?? templateConfig?.sensitivity 
+    ?? 1;
+
+  const confirmationWindow = fieldConfig?.confirmationWindow 
+    ?? assignmentConfig?.confirmationWindow 
+    ?? templateConfig?.confirmationWindow 
+    ?? 3;
+
+  const direction = fieldConfig?.direction;
+
+  const driftEnabled = fieldConfig?.driftEnabled
+    ?? assignmentConfig?.driftEnabled
+    ?? templateConfig?.driftEnabled
+    ?? true;
+
+  const driftThreshold = fieldConfig?.driftThreshold
+    ?? assignmentConfig?.driftThreshold
+    ?? templateConfig?.driftThreshold
+    ?? 2;
+
+  return {
+    enabled,
+    sensitivity,
+    confirmationWindow,
+    direction,
+    driftEnabled,
+    driftThreshold,
+  };
+}
+

package/src/engine/drift.test.ts

@@ -0,0 +1,205 @@
+import { describe, test, expect } from "bun:test";
+import { detectDrift } from "./drift";
+
+describe("Anomaly Engine - Drift Detection", () => {
+  describe("trigger condition |slope × n| > threshold × σ × sensitivity", () => {
+    test("does not trigger when projected change is below threshold", () => {
+      // slope * n = 0.5 * 100 = 50; threshold * σ * sensitivity = 2 * 30 * 1 = 60
+      const result = detectDrift({
+        slope: 0.5,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(false);
+      expect(result.projectedChange).toBe(50);
+    });
+
+    test("triggers when projected change exceeds threshold", () => {
+      // slope * n = 1 * 100 = 100; threshold * σ * sensitivity = 2 * 30 * 1 = 60
+      const result = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(true);
+      expect(result.projectedChange).toBe(100);
+      expect(result.deviationSigmas).toBeCloseTo(100 / 30, 4);
+      expect(result.driftDirection).toBe("above");
+    });
+
+    test("uses absolute value of slope so negative drifts also count", () => {
+      const result = detectDrift({
+        slope: -1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(true);
+      expect(result.driftDirection).toBe("below");
+    });
+  });
+
+  describe("direction filtering", () => {
+    test("lower-is-better only flags positive slopes (metric getting worse)", () => {
+      const rising = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "lower-is-better",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(rising.drifting).toBe(true);
+
+      const falling = detectDrift({
+        slope: -1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "lower-is-better",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(falling.drifting).toBe(false);
+    });
+
+    test("higher-is-better only flags negative slopes", () => {
+      const falling = detectDrift({
+        slope: -1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "higher-is-better",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(falling.drifting).toBe(true);
+
+      const rising = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "higher-is-better",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(rising.drifting).toBe(false);
+    });
+
+    test("dominance never triggers drift", () => {
+      const result = detectDrift({
+        slope: 100,
+        stdDev: 1,
+        sampleCount: 100,
+        direction: "dominance",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(false);
+    });
+  });
+
+  describe("sensitivity scaling", () => {
+    test("higher sensitivity widens the band — fewer detections", () => {
+      // Borderline case: slope*n = 60, threshold*σ = 60. With sensitivity 2.0 the band doubles.
+      const baseline = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(baseline.drifting).toBe(true);
+
+      const desensitized = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 2,
+        threshold: 2,
+      });
+      expect(desensitized.drifting).toBe(false);
+    });
+
+    test("lower sensitivity tightens the band — more detections", () => {
+      const dormant = detectDrift({
+        slope: 0.5,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(dormant.drifting).toBe(false);
+
+      const sensitive = detectDrift({
+        slope: 0.5,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 0.5,
+        threshold: 2,
+      });
+      expect(sensitive.drifting).toBe(true);
+    });
+  });
+
+  describe("degenerate inputs", () => {
+    test("zero stdDev with non-zero slope still drifts (any movement is anomalous)", () => {
+      const result = detectDrift({
+        slope: 1,
+        stdDev: 0,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(true);
+      expect(result.deviationSigmas).toBe(Number.POSITIVE_INFINITY);
+    });
+
+    test("zero slope never drifts", () => {
+      const result = detectDrift({
+        slope: 0,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(false);
+    });
+
+    test("zero sampleCount never drifts", () => {
+      const result = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 0,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(false);
+    });
+
+    test("zero stdDev with zero slope does not drift", () => {
+      const result = detectDrift({
+        slope: 0,
+        stdDev: 0,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+      });
+      expect(result.drifting).toBe(false);
+    });
+  });
+});

package/src/engine/drift.ts

@@ -0,0 +1,80 @@
+import type { AnomalyDirection } from "../schema";
+
+export interface DriftDetectionInput {
+  /** Linear regression slope across the chronologically-ordered baseline window. */
+  slope: number;
+  /** Population standard deviation of the same window. */
+  stdDev: number;
+  /** Number of samples in the window. */
+  sampleCount: number;
+  /** Schema-declared direction for the field. */
+  direction: AnomalyDirection;
+  /** Sensitivity multiplier (matches the spike-detection slider). */
+  sensitivity: number;
+  /** Sigma multiplier on the drift trigger band. Default 2 in callers. */
+  threshold: number;
+}
+
+export interface DriftDetectionResult {
+  drifting: boolean;
+  /** slope × sampleCount — the projected change over the baseline window. */
+  projectedChange: number;
+  /** projectedChange / stdDev — how many σ the trend has shifted the baseline. */
+  deviationSigmas: number;
+  /** Which side of the baseline the drift is moving toward. */
+  driftDirection: "above" | "below";
+}
+
+/**
+ * Pure drift detection.
+ *
+ * Triggers when |slope × sampleCount| > threshold × σ × sensitivity, i.e. when
+ * the regression projects the metric to walk by more than `threshold` standard
+ * deviations across the baseline window. Filtered by direction:
+ *   - lower-is-better: only positive slope (worsening)
+ *   - higher-is-better: only negative slope (worsening)
+ *   - deviation: either
+ *   - dominance: never (categorical fields don't drift continuously)
+ *
+ * Returns deviationSigmas = ∞ when stdDev is 0 and slope is non-zero, since any
+ * movement on a previously-constant metric is by definition outside the noise.
+ */
+export function detectDrift({
+  slope,
+  stdDev,
+  sampleCount,
+  direction,
+  sensitivity,
+  threshold,
+}: DriftDetectionInput): DriftDetectionResult {
+  const projectedChange = slope * sampleCount;
+  const driftDirection: "above" | "below" = slope >= 0 ? "above" : "below";
+
+  const deviationSigmas =
+    stdDev === 0
+      ? slope === 0
+        ? 0
+        : Number.POSITIVE_INFINITY
+      : Math.abs(projectedChange) / stdDev;
+
+  if (sampleCount === 0 || slope === 0) {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  if (direction === "dominance") {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  if (direction === "lower-is-better" && slope < 0) {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  if (direction === "higher-is-better" && slope > 0) {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  const triggerBand = threshold * stdDev * sensitivity;
+  const drifting = Math.abs(projectedChange) > triggerBand;
+
+  return { drifting, projectedChange, deviationSigmas, driftDirection };
+}

package/src/engine/thresholds.test.ts

@@ -0,0 +1,108 @@
+import { describe, test, expect } from "bun:test";
+import { computeThresholds, isAnomalous, isCategoricalAnomalous } from "./thresholds";
+
+describe("Anomaly Engine - Thresholds", () => {
+  describe("computeThresholds", () => {
+    test("higher-is-better generates only lowerTrigger", () => {
+      // e.g. success rate. Mean 90, stdDev 5, sensitivity 1 -> margin 15
+      // lowerTrigger = 90 - 15 = 75
+      const thresholds = computeThresholds(90, 5, "higher-is-better", 1);
+      expect(thresholds.lowerTrigger).toBe(75);
+      expect(thresholds.upperTrigger).toBeUndefined();
+    });
+
+    test("lower-is-better generates only upperTrigger", () => {
+      // e.g. latency. Mean 100, stdDev 20, sensitivity 1 -> margin 60
+      // upperTrigger = 100 + 60 = 160
+      const thresholds = computeThresholds(100, 20, "lower-is-better", 1);
+      expect(thresholds.upperTrigger).toBe(160);
+      expect(thresholds.lowerTrigger).toBeUndefined();
+    });
+
+    test("deviation generates both triggers", () => {
+      // e.g. queue size. Mean 50, stdDev 10, sensitivity 1 -> margin 30
+      // triggers at 20 and 80
+      const thresholds = computeThresholds(50, 10, "deviation", 1);
+      expect(thresholds.lowerTrigger).toBe(20);
+      expect(thresholds.upperTrigger).toBe(80);
+    });
+
+    test("scales margin with sensitivity multiplier", () => {
+      // deviation, sensitivity 0.5 (tighter bounds)
+      // margin = 3 * 10 * 0.5 = 15 -> triggers at 35 and 65
+      const strictThresholds = computeThresholds(50, 10, "deviation", 0.5);
+      expect(strictThresholds.lowerTrigger).toBe(35);
+      expect(strictThresholds.upperTrigger).toBe(65);
+
+      // deviation, sensitivity 2 (looser bounds)
+      // margin = 3 * 10 * 2 = 60 -> triggers at -10 and 110
+      const looseThresholds = computeThresholds(50, 10, "deviation", 2);
+      expect(looseThresholds.lowerTrigger).toBe(-10);
+      expect(looseThresholds.upperTrigger).toBe(110);
+    });
+  });
+
+  describe("isAnomalous", () => {
+    test("detects lower anomalies", () => {
+      const thresholds = { lowerTrigger: 50 };
+      expect(isAnomalous(40, thresholds)).toBe(true);
+      expect(isAnomalous(50, thresholds)).toBe(false); // Exactly at threshold is not anomalous
+      expect(isAnomalous(60, thresholds)).toBe(false);
+    });
+
+    test("detects upper anomalies", () => {
+      const thresholds = { upperTrigger: 100 };
+      expect(isAnomalous(110, thresholds)).toBe(true);
+      expect(isAnomalous(100, thresholds)).toBe(false);
+      expect(isAnomalous(90, thresholds)).toBe(false);
+    });
+
+    test("detects bidirectional anomalies", () => {
+      const thresholds = { lowerTrigger: 20, upperTrigger: 80 };
+      expect(isAnomalous(10, thresholds)).toBe(true);
+      expect(isAnomalous(50, thresholds)).toBe(false);
+      expect(isAnomalous(90, thresholds)).toBe(true);
+    });
+
+    test("handles undefined thresholds gracefully", () => {
+      const thresholds = {};
+      expect(isAnomalous(1000, thresholds)).toBe(false);
+      expect(isAnomalous(-1000, thresholds)).toBe(false);
+    });
+  });
+
+  describe("isCategoricalAnomalous", () => {
+    test("handles undefined baselines safely", () => {
+      expect(isCategoricalAnomalous(200, undefined, undefined, 1)).toBe(false);
+      expect(isCategoricalAnomalous(200, 200, undefined, 1)).toBe(false);
+      expect(isCategoricalAnomalous(200, undefined, 0.9, 1)).toBe(false);
+    });
+
+    test("triggers if value deviates and ratio is sufficiently high (sensitivity = 1)", () => {
+      // ratio 0.95 > 0.9, deviates
+      expect(isCategoricalAnomalous(500, 200, 0.95, 1)).toBe(true);
+      // ratio 0.95 > 0.9, no deviation
+      expect(isCategoricalAnomalous(200, 200, 0.95, 1)).toBe(false);
+    });
+
+    test("ignores deviation if baseline ratio is too noisy (sensitivity = 1)", () => {
+      // ratio 0.85 < 0.9
+      expect(isCategoricalAnomalous(500, 200, 0.85, 1)).toBe(false);
+    });
+
+    test("scales dominance threshold with sensitivity", () => {
+      // High sensitivity (0.5) -> tighter bounds, more alerts.
+      // Required ratio = 0.9 * 0.5 = 0.45.
+      // Even if baseline ratio is 0.50 (very noisy), it still triggers an alert!
+      expect(isCategoricalAnomalous(500, 200, 0.50, 0.5)).toBe(true);
+      
+      // Low sensitivity (2.0) -> looser bounds, fewer alerts.
+      // Required ratio = 0.9 * 2.0 = 1.8 -> clamped to 0.99.
+      // If baseline ratio is 0.95 (pretty stable but not 99%), it does NOT alert.
+      expect(isCategoricalAnomalous(500, 200, 0.95, 2.0)).toBe(false);
+
+      // If baseline ratio is 0.995 (extremely stable), it WILL alert even at sensitivity 2.0.
+      expect(isCategoricalAnomalous(500, 200, 0.995, 2.0)).toBe(true);
+    });
+  });
+});

package/src/engine/thresholds.ts

@@ -0,0 +1,72 @@
+import type { AnomalyDirection } from "../schema";
+
+export interface Thresholds {
+  lowerTrigger?: number;
+  upperTrigger?: number;
+}
+
+export function computeThresholds(
+  mean: number,
+  stdDev: number,
+  direction: AnomalyDirection,
+  sensitivity: number = 1
+): Thresholds {
+  const margin = 3 * stdDev * sensitivity;
+
+  switch (direction) {
+    case "higher-is-better": {
+      return {
+        lowerTrigger: mean - margin,
+        // No upper trigger, values can go as high as they want
+      };
+    }
+    case "lower-is-better": {
+      return {
+        upperTrigger: mean + margin,
+        // No lower trigger, getting faster/better is not an anomaly
+      };
+    }
+    case "deviation": {
+      return {
+        lowerTrigger: mean - margin,
+        upperTrigger: mean + margin,
+      };
+    }
+    default: {
+      return {};
+    }
+  }
+}
+
+export function isAnomalous(
+  value: number,
+  thresholds: Thresholds
+): boolean {
+  if (thresholds.lowerTrigger !== undefined && value < thresholds.lowerTrigger) {
+    return true;
+  }
+  if (thresholds.upperTrigger !== undefined && value > thresholds.upperTrigger) {
+    return true;
+  }
+  return false;
+}
+
+export function isCategoricalAnomalous(
+  value: string | boolean | number,
+  dominantValue: string | boolean | number | undefined,
+  dominantRatio: number | undefined,
+  sensitivity: number = 1
+): boolean {
+  if (dominantValue === undefined || dominantRatio === undefined) return false;
+  
+  // Sensitivity scaling for categorical fields limits false positives.
+  // Base required dominance is 90% stability.
+  // Lower sensitivity values (e.g., 0.5) mean "tighter bounds, more alerts".
+  // Therefore, we lower the required ratio so we alert even if the baseline is noisier.
+  // Higher sensitivity values (e.g., 2.0) mean "looser bounds, fewer alerts".
+  // Therefore, we raise the required ratio so we only alert if the baseline was extremely stable.
+  const requiredRatio = Math.min(0.99, 0.9 * sensitivity);
+  if (dominantRatio < requiredRatio) return false;
+
+  return String(value) !== String(dominantValue);
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export * from "./schema";
+export * from "./engine/baseline";
+export * from "./engine/thresholds";
+export * from "./engine/config";
+export * from "./engine/drift";
+export * from "./access";
+export * from "./rpc-contract";
+export * from "./plugin-metadata";
+
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import { AnomalyStateSchema } from "./schema";
+
+export const ANOMALY_STATE_CHANGED = createSignal(
+  "anomaly.state_changed",
+  z.object({
+    systemId: z.string(),
+    anomalyId: z.string(),
+    newState: AnomalyStateSchema,
+  })
+);
+
+export const ANOMALY_BASELINE_UPDATED = createSignal(
+  "anomaly.baseline_updated",
+  z.object({
+    systemId: z.string(),
+    configurationId: z.string(),
+    fieldPath: z.string(),
+    mean: z.number(),
+    stdDev: z.number(),
+    sampleCount: z.number(),
+  })
+);
+
+export const ANOMALY_TREND_DETECTED = createSignal(
+  "anomaly.trend_detected",
+  z.object({
+    systemId: z.string(),
+    anomalyId: z.string(),
+    fieldPath: z.string(),
+  })
+);

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "anomaly",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,158 @@
+import { createClientDefinition, proc } from "@checkstack/common";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+import { AnomalyStateSchema, AnomalySettingsSchema, AnomalyFieldConfigSchema, AnomalyKindSchema } from "./schema";
+import { anomalyAccess } from "./access";
+
+export const AnomalyDtoSchema = z.object({
+  id: z.string(),
+  systemId: z.string(),
+  configurationId: z.string(),
+  fieldPath: z.string(),
+  kind: AnomalyKindSchema,
+  state: AnomalyStateSchema,
+  direction: z.enum(["above", "below", "changed"]),
+  baselineValue: z.number().nullable(),
+  baselineStdDev: z.number().nullable(),
+  observedValue: z.string(),
+  deviation: z.number(),
+  suspiciousRunCount: z.number(),
+  confirmationThreshold: z.number(),
+  startedAt: z.string(),
+  confirmedAt: z.string().nullable(),
+  recoveredAt: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export type AnomalyDto = z.infer<typeof AnomalyDtoSchema>;
+
+export const AnomalyBaselineDtoSchema = z.object({
+  id: z.string(),
+  systemId: z.string(),
+  configurationId: z.string(),
+  fieldPath: z.string(),
+  mean: z.number(),
+  stdDev: z.number(),
+  trendSlope: z.number(),
+  sampleCount: z.number(),
+  computedAt: z.string(),
+  dominantValue: z.string().nullable(),
+  dominantRatio: z.number().nullable(),
+});
+
+export type AnomalyBaselineDto = z.infer<typeof AnomalyBaselineDtoSchema>;
+
+/**
+ * Schema for a VersionedRecord wrapper used in RPC transport.
+ * Wraps the data with version metadata for backward-compatible schema evolution.
+ */
+const VersionedAnomalySettingsSchema = z.object({
+  version: z.number(),
+  data: AnomalySettingsSchema,
+  migratedAt: z.date().optional(),
+  originalVersion: z.number().optional(),
+});
+
+/**
+ * Partial settings schema for assignment-level overrides.
+ * Only includes fields that the user explicitly sets.
+ */
+const PartialAnomalySettingsSchema = z.object({
+  enabled: z.boolean().optional(),
+  sensitivity: z.number().optional(),
+  confirmationWindow: z.number().int().optional(),
+  baselineWindow: z.string().optional(),
+  notify: z.boolean().optional(),
+  driftEnabled: z.boolean().optional(),
+  driftThreshold: z.number().optional(),
+  fieldOverrides: z.record(z.string(), AnomalyFieldConfigSchema).optional(),
+});
+
+const VersionedPartialAnomalySettingsSchema = z.object({
+  version: z.number(),
+  data: PartialAnomalySettingsSchema,
+  migratedAt: z.date().optional(),
+  originalVersion: z.number().optional(),
+});
+
+export const anomalyContract = {
+  getAnomalies: proc({
+    operationType: "query",
+    userType: "public",
+    access: [anomalyAccess.feed.read],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({
+      systemId: z.string().optional(),
+      configurationId: z.string().optional(),
+      state: AnomalyStateSchema.optional(),
+      kind: AnomalyKindSchema.optional(),
+      limit: z.number().optional().default(50),
+    }))
+    .output(z.array(AnomalyDtoSchema)),
+
+  getAnomalyBaselines: proc({
+    operationType: "query",
+    userType: "public",
+    access: [anomalyAccess.feed.read],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({
+      systemId: z.string(),
+      configurationId: z.string(),
+    }))
+    .output(z.array(AnomalyBaselineDtoSchema)),
+
+  getAnomalyConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [anomalyAccess.feed.manage],
+  })
+    .input(z.object({
+      configurationId: z.string(),
+    }))
+    .output(VersionedAnomalySettingsSchema),
+
+  updateAnomalyConfig: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [anomalyAccess.feed.manage],
+  })
+    .input(z.object({
+      configurationId: z.string(),
+      config: AnomalySettingsSchema,
+    }))
+    .output(VersionedAnomalySettingsSchema),
+
+  getAnomalyAssignmentConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [anomalyAccess.feed.manage],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({
+      systemId: z.string(),
+      configurationId: z.string(),
+    }))
+    .output(VersionedPartialAnomalySettingsSchema.nullable()),
+
+  updateAnomalyAssignmentConfig: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [anomalyAccess.feed.manage],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({
+      systemId: z.string(),
+      configurationId: z.string(),
+      config: PartialAnomalySettingsSchema,
+    }))
+    .output(VersionedPartialAnomalySettingsSchema),
+};
+
+export type AnomalyContract = typeof anomalyContract;
+
+export const AnomalyApi = createClientDefinition(
+  anomalyContract,
+  pluginMetadata
+);

package/src/schema.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+export const AnomalyDirectionSchema = z.enum([
+  "higher-is-better",
+  "lower-is-better",
+  "deviation",
+  "dominance",
+]);
+export type AnomalyDirection = z.infer<typeof AnomalyDirectionSchema>;
+
+export const AnomalyStateSchema = z.enum([
+  "suspicious",
+  "anomaly",
+  "recovered",
+]);
+export type AnomalyState = z.infer<typeof AnomalyStateSchema>;
+
+export const AnomalyKindSchema = z.enum(["spike", "drift"]);
+export type AnomalyKind = z.infer<typeof AnomalyKindSchema>;
+
+export const FieldBaselineSchema = z.object({
+  mean: z.number(),
+  stdDev: z.number(),
+  trendSlope: z.number(),
+  sampleCount: z.number(),
+  computedAt: z.string(), // ISO timestamp
+  dominantValue: z.union([z.string(), z.boolean(), z.number()]).optional(),
+  dominantRatio: z.number().optional(),
+});
+export type FieldBaseline = z.infer<typeof FieldBaselineSchema>;
+
+export const AnomalyMetadataSchema = z
+  .object({
+    trendData: z.record(z.string(), z.unknown()).optional(),
+    relatedAnomalies: z.array(z.string()).optional(), // UUIDs
+  })
+  .catchall(z.unknown());
+export type AnomalyMetadata = z.infer<typeof AnomalyMetadataSchema>;
+
+export const AnomalyFieldConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  sensitivity: z.number().optional(),
+  confirmationWindow: z.number().int().optional(),
+  direction: AnomalyDirectionSchema.optional(),
+  driftEnabled: z.boolean().optional(),
+  driftThreshold: z.number().optional(),
+});
+export type AnomalyFieldConfig = z.infer<typeof AnomalyFieldConfigSchema>;
+
+export const AnomalySettingsSchema = z.object({
+  enabled: z.boolean().default(true),
+  sensitivity: z.number().default(1),
+  confirmationWindow: z.number().int().default(3),
+  baselineWindow: z.string().default("7d"),
+  notify: z.boolean().default(true),
+  driftEnabled: z.boolean().default(true),
+  driftThreshold: z.number().default(2),
+  fieldOverrides: z.record(z.string(), AnomalyFieldConfigSchema).optional(),
+});
+export type AnomalySettings = z.infer<typeof AnomalySettingsSchema>;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}