@checkstack/anomaly-backend 1.1.9 → 1.2.1

package/src/drift-evaluator.ts

@@ -8,7 +8,10 @@ import {
   ANOMALY_TREND_DETECTED,
   detectDrift,
   resolveEffectiveConfig,
+  isDriftFlatRelative,
+  STABLE_DRIFT_RESOLUTION_RUN_COUNT,
   type AnomalyDirection,
+  type AnomalyMetadata,
   type AnomalySettings,
   type FieldBaseline,
 } from "@checkstack/anomaly-common";
@@ -170,7 +173,7 @@ export async function evaluateDrift({
             deviation: driftResult.deviationSigmas,
           })
           .where(eq(schema.anomalies.id, existing.id));
-        logger.warn(`Drift confirmed for ${systemId} on ${fieldPath}`);
+        logger.debug(`Drift confirmed for ${systemId} on ${fieldPath}`);
 
         if (signalService) {
           await signalService.broadcast(ANOMALY_STATE_CHANGED, {
@@ -211,11 +214,65 @@ export async function evaluateDrift({
     }
 
     if (existing.state === "anomaly") {
+      // PART A (drift self-resolution): the slope-based detector still reports
+      // drift because the 7-day window straddles the old and new regimes, but
+      // if the *projected change relative to the (new) mean* has gone flat for
+      // several consecutive analyzer runs, the metric has settled at its new
+      // level — resolve independently of the slow window catching up. The
+      // run-count lives on the row's metadata (shared Postgres) so it survives
+      // across whichever pod claims the analyzer job.
+      const metadata = (existing.metadata ?? {}) as AnomalyMetadata;
+      const flat = isDriftFlatRelative({
+        projectedChange: driftResult.projectedChange,
+        mean: baseline.mean,
+      });
+      const stableDriftRunCount = flat
+        ? (metadata.stableDriftRunCount ?? 0) + 1
+        : 0;
+
+      if (stableDriftRunCount >= STABLE_DRIFT_RESOLUTION_RUN_COUNT) {
+        await db
+          .update(schema.anomalies)
+          .set({
+            state: "recovered",
+            recoveredAt: new Date(),
+            observedValue: baseline.mean.toString(),
+            deviation: driftResult.deviationSigmas,
+            metadata: { ...metadata, stableDriftRunCount: 0 },
+          })
+          .where(eq(schema.anomalies.id, existing.id));
+        logger.debug(
+          `Drift self-resolved (settled at new level) for ${systemId} on ${fieldPath}`,
+        );
+
+        if (signalService) {
+          await signalService.broadcast(ANOMALY_STATE_CHANGED, {
+            systemId,
+            anomalyId: existing.id,
+            newState: "recovered",
+          });
+        }
+
+        await dispatchAnomalyNotification({
+          action: "drift_recovered",
+          systemId,
+          fieldPath,
+          observedValue: baseline.mean,
+          baselineMean: baseline.mean,
+          catalogClient,
+          notificationClient,
+          db,
+          logger,
+        });
+        return;
+      }
+
       await db
         .update(schema.anomalies)
         .set({
           observedValue: baseline.mean.toString(),
           deviation: driftResult.deviationSigmas,
+          metadata: { ...metadata, stableDriftRunCount },
         })
         .where(eq(schema.anomalies.id, existing.id));
       return;
@@ -241,9 +298,12 @@ export async function evaluateDrift({
         state: "recovered",
         recoveredAt: new Date(),
         observedValue: baseline.mean.toString(),
+        suppressedAt: null,
+        suppressedValue: null,
+        suppressedBaseline: null,
       })
       .where(eq(schema.anomalies.id, existing.id));
-    logger.info(`Drift recovered for ${systemId} on ${fieldPath}`);
+    logger.debug(`Drift recovered for ${systemId} on ${fieldPath}`);
 
     if (signalService) {
       await signalService.broadcast(ANOMALY_STATE_CHANGED, {

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Contract test: every anomaly Versioned config that is stored and read back
+ * via the migration chain MUST have a COMPLETE, contiguous chain from version
+ * 1 to its current `version`. Pure STRUCTURAL check
+ * (`validateMigrationChainFromV1` — no `migrate()` is run), so it carries zero
+ * per-config upkeep: the day someone bumps a config's `version` without
+ * shipping a covering migration, `parse`/`parseRecord` would silently fail at
+ * runtime on a genuinely-v1 stored record — this test turns that into a CI
+ * failure instead. See the HTTP plugin's equivalent test for the full
+ * rationale.
+ *
+ * Covers the two module-level Versioned wrappers this package owns: the
+ * site-wide settings config and the assignment-level override config.
+ */
+import { describe, expect, it } from "bun:test";
+import { anomalySettingsConfig, anomalyAssignmentConfig } from "./config";
+
+describe("anomaly config migration-chain contract", () => {
+  const configs = [
+    { name: "anomaly settings", config: anomalySettingsConfig },
+    { name: "anomaly assignment", config: anomalyAssignmentConfig },
+  ];
+
+  it("every registered Versioned config has a complete v1->version chain", () => {
+    for (const { name, config } of configs) {
+      const problem = config.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `${name} config (version ${config.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/plugin.ts

@@ -1,4 +1,8 @@
 import { createBackendPlugin, coreServices, type SafeDatabase } from "@checkstack/backend-api";
+import {
+  aiToolProjectionExtensionPoint,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
 import { setupBaselineAnalyzerJob } from "./jobs/baseline-analyzer";
 import { processCheckCompleted } from "./detector";
@@ -13,6 +17,7 @@ import {
   anomalyAccessRules,
   anomalySystemSubscription,
   anomalyGroupSubscription,
+  pluginMetadata,
 } from "@checkstack/anomaly-common";
 import { specToRegistration } from "@checkstack/notification-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
@@ -46,6 +51,20 @@ export const plugin = createBackendPlugin({
     // Mutable ref populated during init(); the reconciler closure pulls
     // the service via the lazy accessor at sync time.
     let gitopsService: AnomalyService | undefined;
+    // Expose anomaly's own read-only AI projection so ai-backend never has
+    // to import @checkstack/anomaly-common. The projection re-uses the
+    // existing getAnomalies contract procedure (read-only, access-gated).
+    env.getExtensionPoint(aiToolProjectionExtensionPoint).expose({
+      procedure: anomalyContract.getAnomalies,
+      sourcePluginMetadata: pluginMetadata,
+      procedureKey: "getAnomalies",
+      name: "anomaly.explain",
+      description:
+        "List detected anomalies (statistical sigma/drift) for context. Read-only.",
+      effect: "read",
+      execute: deferredProjectionExecute,
+    });
+
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
     registerAnomalyGitOpsKinds({
       kindRegistry,

package/src/router.ts

@@ -7,9 +7,7 @@ import {
   type Logger,
   type RealUser,
   type RpcContext,
-  type VersionedRecord,
 } from "@checkstack/backend-api";
-import type { AnomalySettings } from "@checkstack/anomaly-common";
 import type { AnomalyRouterCache } from "./router-cache";
 
 export function createRouter(
@@ -57,15 +55,14 @@ export function createRouter(
           cache.invalidateAnomalies(),
           cache.invalidateBaselines(),
         ]);
-        return result as VersionedRecord<AnomalySettings>;
+        return result;
       }
     ),
 
     getAnomalyAssignmentConfig: os.getAnomalyAssignmentConfig.handler(
       async ({ input }) => {
         const result = await service.getAnomalyAssignmentConfig(input.systemId, input.configurationId);
-         
-        return (result as VersionedRecord<Partial<AnomalySettings>>) ?? null;
+        return result ?? null;
       }
     ),
 
@@ -76,10 +73,32 @@ export function createRouter(
           cache.invalidateAnomalies(),
           cache.invalidateBaselines(),
         ]);
-        return result as VersionedRecord<Partial<AnomalySettings>>;
+        return result;
       }
     ),
 
+    suppressAnomaly: os.suppressAnomaly.handler(
+      async ({ input }) => {
+        const success = await service.suppressAnomaly({
+          anomalyId: input.anomalyId,
+          systemId: input.systemId,
+        });
+        await cache.invalidateAnomalies();
+        return { success };
+      },
+    ),
+
+    unsuppressAnomaly: os.unsuppressAnomaly.handler(
+      async ({ input }) => {
+        const success = await service.unsuppressAnomaly({
+          anomalyId: input.anomalyId,
+          systemId: input.systemId,
+        });
+        await cache.invalidateAnomalies();
+        return { success };
+      },
+    ),
+
     listAnomalyNotificationMutes: os.listAnomalyNotificationMutes.handler(
       async ({ input, context }) => {
         const userId = (context.user as RealUser).id;

package/src/schema.ts

@@ -52,6 +52,21 @@ export const anomalies = pgTable("anomalies", {
   startedAt: timestamp("started_at").defaultNow().notNull(),
   confirmedAt: timestamp("confirmed_at"),
   recoveredAt: timestamp("recovered_at"),
+  /**
+   * Global (per-row) suppression. We model suppression as a flag layered on top
+   * of `state` rather than a new `suppressed` enum value: the existing
+   * suspicious/anomaly/recovered state machine (in both the spike detector and
+   * the drift evaluator) stays intact, and un-suppressing simply reveals the
+   * underlying state again. A NULL `suppressedAt` means "not suppressed".
+   *
+   * Lives on the shared `anomalies` row (Postgres) so every horizontally-scaled
+   * pod reads the same suppressed/active set — see state-and-scale.md. The
+   * snapshot columns capture the value/baseline at suppression time so the
+   * inline detector can auto-unsuppress once the metric "changes again".
+   */
+  suppressedAt: timestamp("suppressed_at"),
+  suppressedValue: doublePrecision("suppressed_value"),
+  suppressedBaseline: doublePrecision("suppressed_baseline"),
   metadata: jsonb("metadata").$type<Record<string, unknown>>(),
 });
 

package/src/service.ts

@@ -1,9 +1,16 @@
-import { eq, and, desc, inArray } from "drizzle-orm";
+import { eq, and, desc, inArray, isNull, isNotNull } from "drizzle-orm";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
-import { anomalySettingsConfig } from "./config";
+import {
+  anomalySettingsConfig,
+  anomalyAssignmentConfig,
+  toVersionedRecord,
+} from "./config";
 import type { VersionedRecord } from "@checkstack/backend-api";
-import type { AnomalySettings } from "@checkstack/anomaly-common";
+import type {
+  AnomalySettings,
+  PartialAnomalySettings,
+} from "@checkstack/anomaly-common";
 
 export class AnomalyService {
   constructor(private readonly db: SafeDatabase<typeof schema>) {}
@@ -13,6 +20,12 @@ export class AnomalyService {
     configurationId?: string;
     state?: schema.AnomalyState;
     kind?: schema.AnomalyKind;
+    /**
+     * Suppression filter. Defaults to "active": suppressed rows are excluded
+     * from the active view. Pass "suppressed" to list only suppressed rows, or
+     * "all" to ignore the suppression flag entirely.
+     */
+    suppression?: "active" | "suppressed" | "all";
     limit?: number;
   }) {
     const conditions = [];
@@ -32,6 +45,13 @@ export class AnomalyService {
       conditions.push(eq(schema.anomalies.kind, params.kind));
     }
 
+    const suppression = params.suppression ?? "active";
+    if (suppression === "active") {
+      conditions.push(isNull(schema.anomalies.suppressedAt));
+    } else if (suppression === "suppressed") {
+      conditions.push(isNotNull(schema.anomalies.suppressedAt));
+    }
+
     const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
 
     const results = await this.db
@@ -44,13 +64,112 @@ export class AnomalyService {
     return results.map((r) => ({
       ...r,
       startedAt: r.startedAt.toISOString(),
-       
+
       confirmedAt: r.confirmedAt?.toISOString() ?? null,
-       
+
       recoveredAt: r.recoveredAt?.toISOString() ?? null,
+
+      suppressedAt: r.suppressedAt?.toISOString() ?? null,
     }));
   }
 
+  /**
+   * Globally suppress a single anomaly row. Snapshots the current observed
+   * value and baseline so the inline detector can auto-unsuppress once the
+   * metric "changes again" (moves outside the relative reactivation band).
+   *
+   * The mutation is scoped by BOTH `anomalyId` and `systemId` — the access
+   * gate authorizes the caller on `systemId`, so we must verify the target row
+   * actually belongs to that system, otherwise a user with `feed.manage` on
+   * system A could suppress system B's anomaly by passing B's id (IDOR).
+   *
+   * Only confirmed (`state === "anomaly"`) rows can be suppressed: the
+   * auto-unsuppress re-evaluation lives in the confirmed-anomaly branch of the
+   * detector, and a suppressed suspicious row would otherwise still confirm and
+   * notify. Returns false if no matching confirmed row exists.
+   */
+  async suppressAnomaly({
+    anomalyId,
+    systemId,
+  }: {
+    anomalyId: string;
+    systemId: string;
+  }): Promise<boolean> {
+    const [existing] = await this.db
+      .select()
+      .from(schema.anomalies)
+      .where(
+        and(
+          eq(schema.anomalies.id, anomalyId),
+          eq(schema.anomalies.systemId, systemId),
+        ),
+      )
+      .limit(1);
+
+    if (!existing || existing.state !== "anomaly") return false;
+
+    const observedNumeric = Number(existing.observedValue);
+
+    await this.db
+      .update(schema.anomalies)
+      .set({
+        suppressedAt: new Date(),
+        suppressedValue: Number.isFinite(observedNumeric)
+          ? observedNumeric
+          : null,
+        suppressedBaseline: existing.baselineValue,
+      })
+      .where(
+        and(
+          eq(schema.anomalies.id, anomalyId),
+          eq(schema.anomalies.systemId, systemId),
+        ),
+      );
+
+    return true;
+  }
+
+  /**
+   * Clear suppression on a single anomaly row. Scoped by both `anomalyId` and
+   * `systemId` for the same IDOR reason as {@link suppressAnomaly}.
+   */
+  async unsuppressAnomaly({
+    anomalyId,
+    systemId,
+  }: {
+    anomalyId: string;
+    systemId: string;
+  }): Promise<boolean> {
+    const [existing] = await this.db
+      .select()
+      .from(schema.anomalies)
+      .where(
+        and(
+          eq(schema.anomalies.id, anomalyId),
+          eq(schema.anomalies.systemId, systemId),
+        ),
+      )
+      .limit(1);
+
+    if (!existing) return false;
+
+    await this.db
+      .update(schema.anomalies)
+      .set({
+        suppressedAt: null,
+        suppressedValue: null,
+        suppressedBaseline: null,
+      })
+      .where(
+        and(
+          eq(schema.anomalies.id, anomalyId),
+          eq(schema.anomalies.systemId, systemId),
+        ),
+      );
+
+    return true;
+  }
+
   async getAnomalyBaselines(params: {
     systemId: string;
     configurationId: string;
@@ -88,7 +207,10 @@ export class AnomalyService {
       });
     }
 
-    return result.config as VersionedRecord<AnomalySettings>;
+    // Migrate-then-validate the stored record on read. `version: 1` with no
+    // migrations today, so this is behavior-preserving now and stays correct
+    // once a migration is added.
+    return anomalySettingsConfig.parseRecord(toVersionedRecord(result.config));
   }
 
   async updateAnomalyConfig(
@@ -97,7 +219,7 @@ export class AnomalyService {
   ) {
     const newConfigRecord = anomalySettingsConfig.create(configData);
 
-    const [result] = await this.db
+    await this.db
       .insert(schema.anomalyConfigurations)
       .values({
         configurationId,
@@ -106,10 +228,11 @@ export class AnomalyService {
       .onConflictDoUpdate({
         target: [schema.anomalyConfigurations.configurationId],
         set: { config: newConfigRecord },
-      })
-      .returning();
+      });
 
-    return result!.config;
+    // Return the validated record we just persisted (typed), rather than the
+    // untyped jsonb round-trip.
+    return newConfigRecord;
   }
 
   async getAnomalyAssignmentConfig(systemId: string, configurationId: string) {
@@ -123,22 +246,23 @@ export class AnomalyService {
         ),
       );
 
-    return result
-      ? (result.config as VersionedRecord<Partial<AnomalySettings>>)
-      : undefined;
+    if (!result) return;
+
+    // Migrate-then-validate the stored override record on read (see
+    // getAnomalyConfig). `version: 1` no-migrations today.
+    return anomalyAssignmentConfig.parseRecord(
+      toVersionedRecord(result.config),
+    );
   }
 
   async updateAnomalyAssignmentConfig(
     systemId: string,
     configurationId: string,
-    configData: Partial<AnomalySettings>,
+    configData: PartialAnomalySettings,
   ) {
-    const newConfigRecord = {
-      version: anomalySettingsConfig.version,
-      data: configData,
-    };
+    const newConfigRecord = anomalyAssignmentConfig.create(configData);
 
-    const [result] = await this.db
+    await this.db
       .insert(schema.anomalyAssignments)
       .values({
         systemId,
@@ -151,10 +275,10 @@ export class AnomalyService {
           schema.anomalyAssignments.configurationId,
         ],
         set: { config: newConfigRecord },
-      })
-      .returning();
+      });
 
-    return result.config;
+    // Return the validated record we just persisted (typed).
+    return newConfigRecord;
   }
 
   /**