@checkstack/anomaly-backend 1.1.9 → 1.2.0

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;
   }
 
   /**

package/src/suppression.test.ts

@@ -0,0 +1,290 @@
+import { describe, test, expect, mock } from "bun:test";
+import { AnomalyService } from "./service";
+import * as schema from "./schema";
+
+/**
+ * Exercises the global (per-row) suppression surface on AnomalyService:
+ * suppress snapshots the observed value + baseline, unsuppress clears them,
+ * getAnomalies honours the suppression filter, and — critically — both
+ * mutations are scoped by `(anomalyId, systemId)` so a caller authorized on
+ * one system cannot mutate another system's row (IDOR). The detector-side
+ * auto-unsuppress lives in detector.test.ts.
+ */
+
+/**
+ * Walk a drizzle WHERE condition object and collect every embedded scalar
+ * value. Lets the mock faithfully simulate Postgres row scoping: a query for
+ * `and(eq(id, X), eq(systemId, Y))` returns the stored row only when both X
+ * and Y match it (just like the real `WHERE id = X AND system_id = Y`).
+ */
+function collectConditionValues(node: unknown): Set<string> {
+  const acc = new Set<string>();
+  const seen = new Set<unknown>();
+  const walk = (x: unknown): void => {
+    if (x == null || typeof x !== "object" || seen.has(x)) return;
+    seen.add(x);
+    const rec = x as Record<string, unknown>;
+    if (
+      "value" in rec &&
+      (typeof rec.value === "string" || typeof rec.value === "number")
+    ) {
+      acc.add(String(rec.value));
+    }
+    for (const key of Object.keys(rec)) walk(rec[key]);
+  };
+  walk(node);
+  return acc;
+}
+
+function createMockDb({
+  storedRow,
+}: {
+  storedRow?: Record<string, unknown>;
+} = {}) {
+  const updateCalls: Array<Record<string, unknown>> = [];
+  const whereSnapshots: unknown[] = [];
+
+  /**
+   * Returns the stored row only when the condition mentions every scalar
+   * identity field the row carries that the service scopes on (id + systemId).
+   * If the condition is absent (e.g. unfiltered getAnomalies) the row passes.
+   */
+  const rowsFor = (cond: unknown): Record<string, unknown>[] => {
+    if (!storedRow) return [];
+    if (cond === undefined) return [storedRow];
+    const values = collectConditionValues(cond);
+    const id = storedRow.id;
+    const systemId = storedRow.systemId;
+    const idMatches = id === undefined || values.has(String(id));
+    const systemMatches =
+      systemId === undefined || values.has(String(systemId));
+    return idMatches && systemMatches ? [storedRow] : [];
+  };
+
+  const makeThenable = (rows: unknown[]) => {
+    const promise = Promise.resolve(rows);
+    return {
+      then: promise.then.bind(promise),
+      catch: promise.catch.bind(promise),
+      limit: mock(() => Promise.resolve(rows)),
+      orderBy: mock(() => ({
+        limit: mock(() => Promise.resolve(rows)),
+      })),
+    };
+  };
+
+  const db = {
+    select: mock(() => ({
+      from: mock(() => ({
+        where: mock((cond: unknown) => {
+          whereSnapshots.push(cond);
+          return makeThenable(rowsFor(cond));
+        }),
+        // Unfiltered consumption (no .where()) — returns the row unscoped.
+        ...makeThenable(storedRow ? [storedRow] : []),
+      })),
+    })),
+    update: mock(() => ({
+      set: mock((values: Record<string, unknown>) => ({
+        where: mock(() => {
+          updateCalls.push(values);
+          return Promise.resolve();
+        }),
+      })),
+    })),
+    _updateCalls: updateCalls,
+    _whereSnapshots: whereSnapshots,
+  };
+  return db;
+}
+
+const confirmedRow = {
+  id: "a1",
+  systemId: "sys-A",
+  state: "anomaly" as const,
+  observedValue: "250",
+  baselineValue: 100,
+};
+
+describe("AnomalyService.suppressAnomaly", () => {
+  test("snapshots observed value + baseline and sets suppressedAt", async () => {
+    const db = createMockDb({ storedRow: confirmedRow });
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.suppressAnomaly({
+      anomalyId: "a1",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(true);
+    expect(db._updateCalls.length).toBe(1);
+    expect(db._updateCalls[0]).toMatchObject({
+      suppressedValue: 250,
+      suppressedBaseline: 100,
+    });
+    expect(db._updateCalls[0].suppressedAt).toBeInstanceOf(Date);
+  });
+
+  test("stores null suppressedValue for a non-numeric observed value", async () => {
+    const db = createMockDb({
+      storedRow: {
+        id: "a2",
+        systemId: "sys-A",
+        state: "anomaly",
+        observedValue: "ERROR",
+        baselineValue: null,
+      },
+    });
+    const service = new AnomalyService(db as never);
+
+    await service.suppressAnomaly({ anomalyId: "a2", systemId: "sys-A" });
+
+    expect(db._updateCalls[0].suppressedValue).toBeNull();
+  });
+
+  test("returns false (no write) when the row does not exist", async () => {
+    const db = createMockDb();
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.suppressAnomaly({
+      anomalyId: "missing",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(false);
+    expect(db._updateCalls.length).toBe(0);
+  });
+
+  // ─── IDOR regression ──────────────────────────────────────────────────
+  test("cannot suppress a row belonging to a different system", async () => {
+    // Row b1 belongs to system B; attacker authorized on system A passes B's id.
+    const db = createMockDb({
+      storedRow: {
+        id: "b1",
+        systemId: "sys-B",
+        state: "anomaly",
+        observedValue: "250",
+        baselineValue: 100,
+      },
+    });
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.suppressAnomaly({
+      anomalyId: "b1",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(false);
+    expect(db._updateCalls.length).toBe(0);
+  });
+
+  // ─── State guard ──────────────────────────────────────────────────────
+  test("refuses to suppress a non-confirmed (suspicious) row", async () => {
+    const db = createMockDb({
+      storedRow: {
+        id: "a3",
+        systemId: "sys-A",
+        state: "suspicious",
+        observedValue: "250",
+        baselineValue: 100,
+      },
+    });
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.suppressAnomaly({
+      anomalyId: "a3",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(false);
+    expect(db._updateCalls.length).toBe(0);
+  });
+});
+
+describe("AnomalyService.unsuppressAnomaly", () => {
+  test("clears all suppression columns", async () => {
+    const db = createMockDb({ storedRow: confirmedRow });
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.unsuppressAnomaly({
+      anomalyId: "a1",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(true);
+    expect(db._updateCalls[0]).toMatchObject({
+      suppressedAt: null,
+      suppressedValue: null,
+      suppressedBaseline: null,
+    });
+  });
+
+  test("returns false when the row does not exist", async () => {
+    const db = createMockDb();
+    const service = new AnomalyService(db as never);
+
+    expect(
+      await service.unsuppressAnomaly({ anomalyId: "x", systemId: "sys-A" }),
+    ).toBe(false);
+    expect(db._updateCalls.length).toBe(0);
+  });
+
+  // ─── IDOR regression ──────────────────────────────────────────────────
+  test("cannot unsuppress a row belonging to a different system", async () => {
+    const db = createMockDb({
+      storedRow: {
+        id: "b1",
+        systemId: "sys-B",
+        state: "anomaly",
+        observedValue: "250",
+        suppressedAt: new Date(),
+      },
+    });
+    const service = new AnomalyService(db as never);
+
+    const ok = await service.unsuppressAnomaly({
+      anomalyId: "b1",
+      systemId: "sys-A",
+    });
+
+    expect(ok).toBe(false);
+    expect(db._updateCalls.length).toBe(0);
+  });
+});
+
+describe("AnomalyService.getAnomalies suppression filter", () => {
+  test("default ('active') adds a suppressedAt IS NULL predicate", async () => {
+    const db = createMockDb();
+    const service = new AnomalyService(db as never);
+
+    await service.getAnomalies({ systemId: "sys-1" });
+
+    // A where() with a non-undefined condition was issued (the active filter
+    // contributes a predicate even when no other filters are set).
+    expect(db._whereSnapshots.length).toBe(1);
+    expect(db._whereSnapshots[0]).toBeDefined();
+  });
+
+  test("ISO-formats suppressedAt in the returned DTO", async () => {
+    const suppressedAt = new Date("2026-05-01T00:00:00.000Z");
+    const db = createMockDb({
+      storedRow: {
+        // No `id` field: getAnomalies scopes by systemId (+ the suppression
+        // predicate), not by row id, so the mock only enforces systemId here.
+        systemId: "sys-1",
+        startedAt: new Date("2026-04-01T00:00:00.000Z"),
+        confirmedAt: null,
+        recoveredAt: null,
+        suppressedAt,
+      },
+    });
+    const service = new AnomalyService(db as never);
+
+    const [row] = await service.getAnomalies({
+      systemId: "sys-1",
+      suppression: "suppressed",
+    });
+
+    expect(row.suppressedAt).toBe(suppressedAt.toISOString());
+  });
+});

package/tsconfig.json

@@ -4,6 +4,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../ai-backend"
+    },
     {
       "path": "../anomaly-common"
     },