@checkstack/anomaly-common 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @checkstack/anomaly-common
 
+## 1.1.0
+
+### Minor Changes
+
+- 42abfff: Remove global anomaly settings — configuration is now field-only.
+
+  `AnomalySettings` (template- and assignment-level) no longer carries
+  `sensitivity`, `confirmationWindow`, `driftEnabled`, or `driftThreshold`.
+  These were duplicating the per-field configuration path with awkward
+  cascade semantics, and a single global multiplier was meaningless across
+  fields with different units (ms, %, counts).
+
+  The schema retains only the truly global concerns:
+
+  - `enabled` — master kill switch for the assignment
+  - `baselineWindow` — there is one history per system, not per field
+  - `notify` — one notification preference per assignment
+  - `fieldOverrides` — per-field configuration (where everything else now lives)
+
+  `resolveEffectiveConfig` collapses to two layers: field override → schema
+  default → engine fallback constant. The plugin-author defaults set via
+  `x-anomaly-*` annotations now drive sensitivity/window/drift across the
+  detector and drift evaluator (previously only floors were threaded
+  through the schema layer).
+
+  **Breaking changes:**
+
+  - Any global `sensitivity`/`confirmationWindow`/`driftEnabled`/
+    `driftThreshold` values previously stored in `anomaly_configurations`
+    or `anomaly_assignments` are silently stripped on parse. Users who
+    customized these globals will revert to the plugin's tuned per-field
+    defaults; if they want to keep those values they must re-apply them
+    per field in the new UI.
+  - `AnomalySettingsForm` no longer renders the global sliders. The form
+    now shows: enable toggle, baseline window selector, notify toggle,
+    field overrides editor.
+  - `AnomalyFieldOverridesEditor` props `defaultSensitivity`,
+    `defaultConfirmationWindow`, `defaultDriftEnabled`, `defaultDriftThreshold`
+    are removed. Engine fallbacks (1.0, 3, true, 2) are now hard-coded
+    internal constants used only when neither field override nor schema
+    default is set.
+  - The GitOps `System.anomaly` entry schema (in `anomaly-gitops-kinds`)
+    drops `sensitivity`, `confirmationWindow`, `driftEnabled`, and
+    `driftThreshold` to match the new `AnomalySettings` shape. YAML files
+    declaring those fields will be rejected at parse time — operators
+    must move per-field tuning into `fieldOverrides`.
+
+  This change makes the override model trivial to explain ("plugin defaults,
+  overridden per field") and removes a class of confusing "where did this
+  threshold come from?" questions.
+
+- 42abfff: Add practical-significance floors to anomaly detection.
+
+  Two new schema annotations — `x-anomaly-min-absolute-delta` and `x-anomaly-min-relative-delta` — let plugin authors and operators suppress alerts whose statistical deviation is large but practical impact is negligible. Both floors must clear in addition to the existing μ ± Nσ trigger; defaults are 0 (disabled) so existing behaviour is unchanged.
+
+  This is the fix for cases like a 6 ms latency baseline whose σ ≈ 1 ms causes routine 20 ms blips to fire as anomalies despite Δ=14 ms being operationally irrelevant. With `min-absolute-delta: 50` and `min-relative-delta: 0.5`, those blips stay silent while a 6 ms → 200 ms spike still fires.
+
+  Built-in plugins ship with sensible defaults applied to every per-run field: 50 ms + 50 % for ms-unit fields, 5 percentage points for `%`-unit fields, 1 + 25 % for counter fields, 1 GB + 5 % for disk fields, 50 MB + 10 % for memory fields, 1 day for TLS expiry, 0.5 + 25 % for load average, 1 + 5 % for Minecraft TPS. Operators can override per-system or per-field via the assignment UI.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [1ef2e79]
+  - @checkstack/common@0.9.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/notification-common@1.0.2
+  - @checkstack/signal-common@0.2.2
+
 ## 1.0.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/anomaly-common",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,16 +9,16 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/notification-common": "1.0.0",
-    "@checkstack/signal-common": "0.2.0",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/catalog-common": "2.0.1",
+    "@checkstack/notification-common": "1.0.1",
+    "@checkstack/signal-common": "0.2.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
-    "@checkstack/tsconfig": "0.0.6",
-    "@checkstack/scripts": "0.1.2"
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/engine/config.test.ts

@@ -5,16 +5,12 @@ 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", () => {
+  test("uses engine defaults when nothing is provided", () => {
     const result = resolveEffectiveConfig("some.field");
     expect(result.enabled).toBe(true);
     expect(result.sensitivity).toBe(1);
@@ -22,190 +18,145 @@ describe("Anomaly Engine - Config Override Mechanism", () => {
     expect(result.direction).toBeUndefined();
     expect(result.driftEnabled).toBe(true);
     expect(result.driftThreshold).toBe(2);
+    expect(result.minAbsoluteDelta).toBe(0);
+    expect(result.minRelativeDelta).toBe(0);
   });
 
-  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("master enabled toggle cascades from template to assignment to field", () => {
+    const template: AnomalySettings = { ...defaultTemplate, enabled: false };
+    expect(resolveEffectiveConfig("some.field", template).enabled).toBe(false);
 
-  test("assignment overrides template global settings", () => {
-    const template: AnomalySettings = {
+    const assignment: Partial<AnomalySettings> = { enabled: true };
+    expect(
+      resolveEffectiveConfig("some.field", template, assignment).enabled,
+    ).toBe(true);
+
+    // Field override beats both globals.
+    const templateWithFieldOff: AnomalySettings = {
       ...defaultTemplate,
-      sensitivity: 1,
-      confirmationWindow: 3,
-    };
-    const assignment: Partial<AnomalySettings> = {
-      sensitivity: 3,
-      confirmationWindow: 1,
+      enabled: true,
+      fieldOverrides: { "some.field": { enabled: false } },
     };
-    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
+    expect(
+      resolveEffectiveConfig("some.field", templateWithFieldOff).enabled,
+    ).toBe(false);
   });
 
-  test("template field override overrides template global", () => {
+  test("template field override drives sensitivity / confirmation / drift", () => {
     const template: AnomalySettings = {
       ...defaultTemplate,
-      sensitivity: 1,
       fieldOverrides: {
         "some.field": {
-          sensitivity: 5,
+          sensitivity: 2,
+          confirmationWindow: 5,
+          driftEnabled: false,
+          driftThreshold: 4,
         },
       },
     };
     const result = resolveEffectiveConfig("some.field", template);
-    expect(result.sensitivity).toBe(5);
+    expect(result.sensitivity).toBe(2);
+    expect(result.confirmationWindow).toBe(5);
+    expect(result.driftEnabled).toBe(false);
+    expect(result.driftThreshold).toBe(4);
   });
 
-  test("assignment field override takes absolute precedence", () => {
+  test("assignment field override beats template field override", () => {
     const template: AnomalySettings = {
       ...defaultTemplate,
-      sensitivity: 1,
-      fieldOverrides: {
-        "some.field": {
-          sensitivity: 5, // template field level
-        },
-      },
+      fieldOverrides: { "some.field": { sensitivity: 2 } },
     };
     const assignment: Partial<AnomalySettings> = {
-      sensitivity: 2, // assignment global level
-      fieldOverrides: {
-        "some.field": {
-          sensitivity: 10, // assignment field level
-        },
-      },
+      fieldOverrides: { "some.field": { sensitivity: 0.5 } },
     };
     const result = resolveEffectiveConfig("some.field", template, assignment);
-    expect(result.sensitivity).toBe(10);
+    expect(result.sensitivity).toBe(0.5);
   });
 
-  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,
-        },
+  test("schema defaults fill in when no field override is set", () => {
+    const result = resolveEffectiveConfig(
+      "some.field",
+      undefined,
+      undefined,
+      {
+        sensitivity: 1.5,
+        confirmationWindow: 5,
+        driftEnabled: false,
+        driftThreshold: 3,
+        minAbsoluteDelta: 50,
+        minRelativeDelta: 0.5,
       },
-    };
-    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);
+    );
+    expect(result.sensitivity).toBe(1.5);
+    expect(result.confirmationWindow).toBe(5);
+    expect(result.driftEnabled).toBe(false);
+    expect(result.driftThreshold).toBe(3);
+    expect(result.minAbsoluteDelta).toBe(50);
+    expect(result.minRelativeDelta).toBe(0.5);
   });
 
-  test("template field override sets direction", () => {
+  test("field override beats schema defaults", () => {
     const template: AnomalySettings = {
       ...defaultTemplate,
-      fieldOverrides: {
-        "some.field": {
-          direction: "higher-is-better",
-        },
-      },
+      fieldOverrides: { "some.field": { sensitivity: 0.7 } },
     };
-    const result = resolveEffectiveConfig("some.field", template);
-    expect(result.direction).toBe("higher-is-better");
+    const result = resolveEffectiveConfig(
+      "some.field",
+      template,
+      undefined,
+      { sensitivity: 1.5 },
+    );
+    expect(result.sensitivity).toBe(0.7);
   });
 
-  test("assignment field override direction beats template field direction", () => {
+  test("template field override sets direction", () => {
     const template: AnomalySettings = {
       ...defaultTemplate,
-      fieldOverrides: {
-        "some.field": { direction: "lower-is-better" },
-      },
-    };
-    const assignment: Partial<AnomalySettings> = {
-      fieldOverrides: {
-        "some.field": { direction: "deviation" },
-      },
+      fieldOverrides: { "some.field": { direction: "higher-is-better" } },
     };
-    const result = resolveEffectiveConfig("some.field", template, assignment);
-    expect(result.direction).toBe("deviation");
+    expect(resolveEffectiveConfig("some.field", template).direction).toBe(
+      "higher-is-better",
+    );
   });
 
   test("direction is undefined when no override sets it (caller falls back to schema)", () => {
-    const result = resolveEffectiveConfig("some.field", defaultTemplate);
-    expect(result.direction).toBeUndefined();
+    expect(
+      resolveEffectiveConfig("some.field", defaultTemplate).direction,
+    ).toBeUndefined();
   });
 
   test("preserves explicit falsy values", () => {
     const template: AnomalySettings = {
       ...defaultTemplate,
-      sensitivity: 2,
-    };
-    const assignment: Partial<AnomalySettings> = {
-      sensitivity: 0,
+      fieldOverrides: { "some.field": { sensitivity: 0 } },
     };
-    const result = resolveEffectiveConfig("some.field", template, assignment);
-    expect(result.sensitivity).toBe(0);
+    expect(resolveEffectiveConfig("some.field", template).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("explicit 0 floor from field override re-enables noise (overrides schema default)", () => {
+    const template: AnomalySettings = {
+      ...defaultTemplate,
+      fieldOverrides: { "some.field": { minAbsoluteDelta: 0 } },
+    };
+    const result = resolveEffectiveConfig(
+      "some.field",
+      template,
+      undefined,
+      { minAbsoluteDelta: 50 },
+    );
+    expect(result.minAbsoluteDelta).toBe(0);
+  });
 
-    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);
-    });
+  test("globals other than enabled are ignored — only fieldOverrides shape detection", () => {
+    // The schema doesn't accept sensitivity/confirmationWindow/drift* at the
+    // global level any more, so even if a stale config carries them they
+    // would be stripped by Zod parse. This test asserts that the resolver
+    // doesn't accidentally read them off the typed AnomalySettings shape.
+    const template: AnomalySettings = { ...defaultTemplate };
+    const result = resolveEffectiveConfig("some.field", template);
+    expect(result.sensitivity).toBe(1);
+    expect(result.confirmationWindow).toBe(3);
+    expect(result.driftEnabled).toBe(true);
+    expect(result.driftThreshold).toBe(2);
   });
 });

package/src/engine/config.ts

@@ -7,57 +7,96 @@ export interface EffectiveConfig {
   direction?: AnomalyDirection;
   driftEnabled: boolean;
   driftThreshold: number;
+  /** Practical-significance floor on absolute deviation (default 0). */
+  minAbsoluteDelta: number;
+  /** Practical-significance floor on relative deviation (default 0). */
+  minRelativeDelta: number;
 }
 
 /**
- * Resolves the effective anomaly detection config for a specific field path
- * using the Three-Layer Override Model.
+ * Per-field schema-declared anomaly defaults. These are the plugin author's
+ * tuned defaults — the layer beneath user-supplied field overrides.
+ */
+export interface SchemaDefaults {
+  sensitivity?: number;
+  confirmationWindow?: number;
+  driftEnabled?: boolean;
+  driftThreshold?: number;
+  minAbsoluteDelta?: number;
+  minRelativeDelta?: number;
+}
+
+/** Engine fallback constants — used only when neither the user nor the schema set a value. */
+const ENGINE_DEFAULTS = {
+  enabled: true,
+  sensitivity: 1,
+  confirmationWindow: 3,
+  driftEnabled: true,
+  driftThreshold: 2,
+  minAbsoluteDelta: 0,
+  minRelativeDelta: 0,
+} as const;
+
+/**
+ * Resolves the effective anomaly detection config for a specific field path.
  *
  * 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)
+ * 1. Assignment field override
+ * 2. Template field override
+ * 3. Schema annotation (plugin-author default)
+ * 4. Engine fallback constant
  *
- * 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.
+ * Globals were removed in favour of per-field configuration only. Plugin
+ * defaults are tuned per-field with awareness of each metric's unit and
+ * nature, so a single global multiplier across heterogeneous fields would
+ * be meaningless. Templates and assignments influence detection through
+ * `fieldOverrides`; the only true global on `AnomalySettings` is the master
+ * `enabled` toggle (and the `baselineWindow` / `notify` knobs which are
+ * inherently scoped to the whole assignment).
  */
 export function resolveEffectiveConfig(
   path: string,
   templateConfig?: AnomalySettings,
-  assignmentConfig?: Partial<AnomalySettings>
+  assignmentConfig?: Partial<AnomalySettings>,
+  schemaDefaults?: SchemaDefaults
 ): EffectiveConfig {
-  const fieldConfig = assignmentConfig?.fieldOverrides?.[path] ?? templateConfig?.fieldOverrides?.[path];
-  
-  const enabled = fieldConfig?.enabled 
-    ?? assignmentConfig?.enabled 
-    ?? templateConfig?.enabled 
-    ?? true;
+  const fieldConfig =
+    assignmentConfig?.fieldOverrides?.[path] ??
+    templateConfig?.fieldOverrides?.[path];
 
-  const sensitivity = fieldConfig?.sensitivity 
-    ?? assignmentConfig?.sensitivity 
-    ?? templateConfig?.sensitivity 
-    ?? 1;
+  // The master toggle remains a global — it's the kill switch for the
+  // entire assignment, not a per-field setting. A field override of
+  // `enabled: false` can still locally opt out.
+  const enabled = fieldConfig?.enabled
+    ?? assignmentConfig?.enabled
+    ?? templateConfig?.enabled
+    ?? ENGINE_DEFAULTS.enabled;
 
-  const confirmationWindow = fieldConfig?.confirmationWindow 
-    ?? assignmentConfig?.confirmationWindow 
-    ?? templateConfig?.confirmationWindow 
-    ?? 3;
+  const sensitivity = fieldConfig?.sensitivity
+    ?? schemaDefaults?.sensitivity
+    ?? ENGINE_DEFAULTS.sensitivity;
+
+  const confirmationWindow = fieldConfig?.confirmationWindow
+    ?? schemaDefaults?.confirmationWindow
+    ?? ENGINE_DEFAULTS.confirmationWindow;
 
   const direction = fieldConfig?.direction;
 
   const driftEnabled = fieldConfig?.driftEnabled
-    ?? assignmentConfig?.driftEnabled
-    ?? templateConfig?.driftEnabled
-    ?? true;
+    ?? schemaDefaults?.driftEnabled
+    ?? ENGINE_DEFAULTS.driftEnabled;
 
   const driftThreshold = fieldConfig?.driftThreshold
-    ?? assignmentConfig?.driftThreshold
-    ?? templateConfig?.driftThreshold
-    ?? 2;
+    ?? schemaDefaults?.driftThreshold
+    ?? ENGINE_DEFAULTS.driftThreshold;
+
+  const minAbsoluteDelta = fieldConfig?.minAbsoluteDelta
+    ?? schemaDefaults?.minAbsoluteDelta
+    ?? ENGINE_DEFAULTS.minAbsoluteDelta;
+
+  const minRelativeDelta = fieldConfig?.minRelativeDelta
+    ?? schemaDefaults?.minRelativeDelta
+    ?? ENGINE_DEFAULTS.minRelativeDelta;
 
   return {
     enabled,
@@ -66,6 +105,7 @@ export function resolveEffectiveConfig(
     direction,
     driftEnabled,
     driftThreshold,
+    minAbsoluteDelta,
+    minRelativeDelta,
   };
 }
-

package/src/engine/drift.test.ts

@@ -202,4 +202,91 @@ describe("Anomaly Engine - Drift Detection", () => {
       expect(result.drifting).toBe(false);
     });
   });
+
+  describe("practical-significance floors", () => {
+    test("absolute floor suppresses drift below the floor", () => {
+      // slope*n = 100, statistical band = 60 → would normally drift.
+      // But projected change 100 < absolute floor 200 → no drift.
+      const suppressed = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        minAbsoluteDelta: 200,
+      });
+      expect(suppressed.drifting).toBe(false);
+
+      const passes = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        minAbsoluteDelta: 50,
+      });
+      expect(passes.drifting).toBe(true);
+    });
+
+    test("relative floor suppresses drift below the proportional floor", () => {
+      // mean=1000, projected change=100 → relative=0.1 (10%).
+      // With minRelativeDelta=0.5 (50%), drift suppressed.
+      const suppressed = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        mean: 1000,
+        minRelativeDelta: 0.5,
+      });
+      expect(suppressed.drifting).toBe(false);
+
+      // mean=100, same projected change=100 → relative=1.0 → fires.
+      const fires = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        mean: 100,
+        minRelativeDelta: 0.5,
+      });
+      expect(fires.drifting).toBe(true);
+    });
+
+    test("relative floor without mean is a no-op", () => {
+      // No mean provided → relative floor cannot be evaluated, so it doesn't suppress.
+      const result = detectDrift({
+        slope: 1,
+        stdDev: 30,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        minRelativeDelta: 0.99,
+      });
+      expect(result.drifting).toBe(true);
+    });
+
+    test("zero stdDev still respects floors", () => {
+      // Without floors, this drifts (any movement on constant metric).
+      // With absolute floor above projected change, it's suppressed.
+      const result = detectDrift({
+        slope: 0.001,
+        stdDev: 0,
+        sampleCount: 100,
+        direction: "deviation",
+        sensitivity: 1,
+        threshold: 2,
+        minAbsoluteDelta: 1,
+      });
+      expect(result.drifting).toBe(false);
+      expect(result.deviationSigmas).toBe(Number.POSITIVE_INFINITY);
+    });
+  });
 });

package/src/engine/drift.ts

@@ -13,6 +13,19 @@ export interface DriftDetectionInput {
   sensitivity: number;
   /** Sigma multiplier on the drift trigger band. Default 2 in callers. */
   threshold: number;
+  /** Baseline mean — required when applying the relative floor. */
+  mean?: number;
+  /**
+   * Floor on |slope × sampleCount| (projected absolute change). The
+   * statistical drift trigger must be exceeded *and* the projected change
+   * must be ≥ this floor. Default 0 (disabled).
+   */
+  minAbsoluteDelta?: number;
+  /**
+   * Floor on |slope × sampleCount| / max(|μ|, ε) (projected relative
+   * change), expressed as a fraction. Default 0 (disabled).
+   */
+  minRelativeDelta?: number;
 }
 
 export interface DriftDetectionResult {
@@ -46,8 +59,12 @@ export function detectDrift({
   direction,
   sensitivity,
   threshold,
+  mean,
+  minAbsoluteDelta = 0,
+  minRelativeDelta = 0,
 }: DriftDetectionInput): DriftDetectionResult {
   const projectedChange = slope * sampleCount;
+  const absChange = Math.abs(projectedChange);
   const driftDirection: "above" | "below" = slope >= 0 ? "above" : "below";
 
   const deviationSigmas =
@@ -55,7 +72,7 @@ export function detectDrift({
       ? slope === 0
         ? 0
         : Number.POSITIVE_INFINITY
-      : Math.abs(projectedChange) / stdDev;
+      : absChange / stdDev;
 
   if (sampleCount === 0 || slope === 0) {
     return { drifting: false, projectedChange, deviationSigmas, driftDirection };
@@ -74,7 +91,21 @@ export function detectDrift({
   }
 
   const triggerBand = threshold * stdDev * sensitivity;
-  const drifting = Math.abs(projectedChange) > triggerBand;
+  const exceedsStatistical = absChange > triggerBand;
+  if (!exceedsStatistical) {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  if (absChange < minAbsoluteDelta) {
+    return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+  }
+
+  if (minRelativeDelta > 0 && mean !== undefined) {
+    const denominator = Math.max(Math.abs(mean), Number.EPSILON);
+    if (absChange / denominator < minRelativeDelta) {
+      return { drifting: false, projectedChange, deviationSigmas, driftDirection };
+    }
+  }
 
-  return { drifting, projectedChange, deviationSigmas, driftDirection };
+  return { drifting: true, projectedChange, deviationSigmas, driftDirection };
 }

package/src/engine/thresholds.test.ts

@@ -45,29 +45,105 @@ describe("Anomaly Engine - Thresholds", () => {
   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);
+      expect(isAnomalous({ value: 40, mean: 60, thresholds })).toBe(true);
+      expect(isAnomalous({ value: 50, mean: 60, thresholds })).toBe(false); // Exactly at threshold is not anomalous
+      expect(isAnomalous({ value: 60, mean: 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);
+      expect(isAnomalous({ value: 110, mean: 80, thresholds })).toBe(true);
+      expect(isAnomalous({ value: 100, mean: 80, thresholds })).toBe(false);
+      expect(isAnomalous({ value: 90, mean: 80, 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);
+      expect(isAnomalous({ value: 10, mean: 50, thresholds })).toBe(true);
+      expect(isAnomalous({ value: 50, mean: 50, thresholds })).toBe(false);
+      expect(isAnomalous({ value: 90, mean: 50, thresholds })).toBe(true);
     });
 
     test("handles undefined thresholds gracefully", () => {
       const thresholds = {};
-      expect(isAnomalous(1000, thresholds)).toBe(false);
-      expect(isAnomalous(-1000, thresholds)).toBe(false);
+      expect(isAnomalous({ value: 1000, mean: 0, thresholds })).toBe(false);
+      expect(isAnomalous({ value: -1000, mean: 0, thresholds })).toBe(false);
+    });
+
+    test("absolute floor suppresses statistically-anomalous but practically-tiny swings", () => {
+      // 6ms baseline, σ=1 → upperTrigger ≈ 9. Value 20 crosses statistical trigger
+      // but Δ=14ms is below the 50ms practical-significance floor → no fire.
+      const thresholds = computeThresholds(6, 1, "lower-is-better", 1);
+      expect(
+        isAnomalous({ value: 20, mean: 6, thresholds, minAbsoluteDelta: 50 }),
+      ).toBe(false);
+      // Same baseline, value 200ms (Δ=194ms) → fires.
+      expect(
+        isAnomalous({ value: 200, mean: 6, thresholds, minAbsoluteDelta: 50 }),
+      ).toBe(true);
+    });
+
+    test("relative floor suppresses small proportional changes", () => {
+      // 1000ms baseline, σ=10 → upperTrigger=1030. Value 1100 crosses statistically.
+      // Δ=100, Δ/μ=0.1. With minRelativeDelta=0.5 (50%), still doesn't fire.
+      const thresholds = computeThresholds(1000, 10, "lower-is-better", 1);
+      expect(
+        isAnomalous({ value: 1100, mean: 1000, thresholds, minRelativeDelta: 0.5 }),
+      ).toBe(false);
+      // Value 2000, Δ/μ=1.0 → fires.
+      expect(
+        isAnomalous({ value: 2000, mean: 1000, thresholds, minRelativeDelta: 0.5 }),
+      ).toBe(true);
+    });
+
+    test("both floors must clear when both are set", () => {
+      const thresholds = computeThresholds(100, 5, "lower-is-better", 1);
+      // Δ=20 passes minAbsoluteDelta=10 but Δ/μ=0.2 fails minRelativeDelta=0.5
+      expect(
+        isAnomalous({
+          value: 120,
+          mean: 100,
+          thresholds,
+          minAbsoluteDelta: 10,
+          minRelativeDelta: 0.5,
+        }),
+      ).toBe(false);
+      // Δ=80 passes both floors
+      expect(
+        isAnomalous({
+          value: 180,
+          mean: 100,
+          thresholds,
+          minAbsoluteDelta: 10,
+          minRelativeDelta: 0.5,
+        }),
+      ).toBe(true);
+    });
+
+    test("floors of 0 are no-ops (backward compatible)", () => {
+      const thresholds = { upperTrigger: 100 };
+      expect(
+        isAnomalous({
+          value: 101,
+          mean: 50,
+          thresholds,
+          minAbsoluteDelta: 0,
+          minRelativeDelta: 0,
+        }),
+      ).toBe(true);
+    });
+
+    test("relative floor handles mean ≈ 0 without dividing by zero", () => {
+      const thresholds = { upperTrigger: 0.01 };
+      // mean=0, value=10, Δ=10. Math.max(0, ε)=ε ≈ 2.2e-16. Δ/ε = 4.5e16 → passes.
+      expect(
+        isAnomalous({
+          value: 10,
+          mean: 0,
+          thresholds,
+          minRelativeDelta: 0.5,
+        }),
+      ).toBe(true);
     });
   });
 

package/src/engine/thresholds.ts

@@ -38,17 +38,47 @@ export function computeThresholds(
   }
 }
 
-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;
+export interface AnomalyCheckInput {
+  value: number;
+  mean: number;
+  thresholds: Thresholds;
+  /**
+   * Floor on |value − μ|. The statistical trigger must be exceeded *and*
+   * the absolute deviation must be ≥ this floor for the value to count as
+   * anomalous. Default 0 (disabled).
+   */
+  minAbsoluteDelta?: number;
+  /**
+   * Floor on |value − μ| / max(|μ|, ε), expressed as a fraction. The
+   * statistical trigger must be exceeded *and* the relative deviation must
+   * be ≥ this floor for the value to count as anomalous. Default 0
+   * (disabled).
+   */
+  minRelativeDelta?: number;
+}
+
+export function isAnomalous({
+  value,
+  mean,
+  thresholds,
+  minAbsoluteDelta = 0,
+  minRelativeDelta = 0,
+}: AnomalyCheckInput): boolean {
+  const exceedsStatistical =
+    (thresholds.lowerTrigger !== undefined && value < thresholds.lowerTrigger) ||
+    (thresholds.upperTrigger !== undefined && value > thresholds.upperTrigger);
+
+  if (!exceedsStatistical) return false;
+
+  const absoluteDelta = Math.abs(value - mean);
+  if (absoluteDelta < minAbsoluteDelta) return false;
+
+  if (minRelativeDelta > 0) {
+    const denominator = Math.max(Math.abs(mean), Number.EPSILON);
+    if (absoluteDelta / denominator < minRelativeDelta) return false;
   }
-  return false;
+
+  return true;
 }
 
 export function isCategoricalAnomalous(
@@ -58,7 +88,7 @@ export function isCategoricalAnomalous(
   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".

package/src/schema.ts

@@ -44,17 +44,15 @@ export const AnomalyFieldConfigSchema = z.object({
   direction: AnomalyDirectionSchema.optional(),
   driftEnabled: z.boolean().optional(),
   driftThreshold: z.number().optional(),
+  minAbsoluteDelta: z.number().nonnegative().optional(),
+  minRelativeDelta: z.number().nonnegative().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>;