@checkstack/anomaly-backend 0.2.1 → 1.0.0

package/src/notification.ts

@@ -1,8 +1,15 @@
-import type { Logger } from "@checkstack/backend-api";
+import type { Logger, SafeDatabase } from "@checkstack/backend-api";
 import type { CatalogApi } from "@checkstack/catalog-common";
-import { catalogRoutes } from "@checkstack/catalog-common";
+import { catalogRoutes, createSystemSubject } from "@checkstack/catalog-common";
 import type { InferClient } from "@checkstack/common";
 import { resolveRoute } from "@checkstack/common";
+import {
+  anomalyCollapseKey,
+  anomalySystemSubscription,
+} from "@checkstack/anomaly-common";
+import type { NotificationApi } from "@checkstack/notification-common";
+import { AnomalyService } from "./service";
+import * as schema from "./schema";
 
 export type AnomalyNotificationAction =
   | "confirmed"
@@ -17,16 +24,19 @@ export interface DispatchAnomalyNotificationInput {
   observedValue: string | boolean | number;
   baselineMean: number;
   catalogClient: InferClient<typeof CatalogApi>;
+  notificationClient: InferClient<typeof NotificationApi>;
+  db: SafeDatabase<typeof schema>;
   logger: Logger;
   /** Drift-specific: projected change over the baseline window. */
   projectedChange?: number;
 }
 
 /**
- * Dispatches anomaly-related notifications following the Sidecar Notification
- * Orchestration pattern. Centralizes system lookup, URL resolution, importance
- * mapping, and error isolation across all anomaly action types (Phase 1 spike
- * confirmed/recovered + Phase 2 drift confirmed/recovered).
+ * Dispatches anomaly notifications via the platform spec contract.
+ * Notification-backend resolves the spec → groupId convention, walks
+ * parent catalog groups via stored target edges, and unions
+ * subscribers. Anomaly only contributes the recipient-exclusion list
+ * (per-field / per-system mutes) before delivery.
  */
 export async function dispatchAnomalyNotification({
   action,
@@ -35,6 +45,8 @@ export async function dispatchAnomalyNotification({
   observedValue,
   baselineMean,
   catalogClient,
+  notificationClient,
+  db,
   logger,
   projectedChange,
 }: DispatchAnomalyNotificationInput): Promise<void> {
@@ -66,13 +78,33 @@ export async function dispatchAnomalyNotification({
 
     const importance = getImportance(action);
 
-    await catalogClient.notifySystemSubscribers({
+    // Mute exclusions are computed against the candidate set the
+    // dispatcher will produce — for that we need to know who *would*
+    // be reached. Ask the AnomalyService for everyone muted on this
+    // (system, fieldPath) regardless of subscription state; backend
+    // does the intersection during dispatch (subscribers ∩ excluded).
+    const service = new AnomalyService(db);
+    const mutedUserIds = await service.getMutedUserIds({
       systemId,
+      fieldPath,
+    });
+
+    await notificationClient.notifyForSubscription({
+      specId: anomalySystemSubscription.specId,
+      resourceKeys: [systemId],
+      excludeUserIds: [...mutedUserIds],
       title,
       body: message,
       importance,
       action: { label: "View System", url: actionUrl },
-      includeGroupSubscribers: true,
+      collapseKey: anomalyCollapseKey(systemId, fieldPath),
+      subjects: [
+        createSystemSubject({
+          id: systemId,
+          name: systemName,
+          url: actionUrl,
+        }),
+      ],
     });
   } catch (error) {
     logger.warn(
@@ -111,9 +143,10 @@ function buildNotificationCopy({
       };
     }
     case "drift_confirmed": {
-      const projectionFragment = driftStr === ""
-        ? ""
-        : ` Projected change over the baseline window: ${driftStr}.`;
+      const projectionFragment =
+        driftStr === ""
+          ? ""
+          : ` Projected change over the baseline window: ${driftStr}.`;
       return {
         title: `Trend Drift Detected: ${systemName}`,
         message: `**${fieldPath}** is drifting. Current mean: ${obsStr}, Baseline: ${baseStr}.${projectionFragment}`,
@@ -128,12 +161,9 @@ function buildNotificationCopy({
   }
 }
 
-/**
- * Action-Based Importance Logic per Sidecar Orchestration standard.
- * - Terminal "Good News" states (recovered, drift_recovered) are always info.
- * - "Bad News" states (confirmed, drift_confirmed) are warnings.
- */
-export function getImportance(action: AnomalyNotificationAction): "info" | "warning" {
+export function getImportance(
+  action: AnomalyNotificationAction,
+): "info" | "warning" {
   if (action === "recovered" || action === "drift_recovered") return "info";
   return "warning";
 }

package/src/plugin.ts

@@ -4,10 +4,17 @@ import { setupBaselineAnalyzerJob } from "./jobs/baseline-analyzer";
 import { processCheckCompleted } from "./detector";
 import * as schema from "./schema";
 import { CatalogApi } from "@checkstack/catalog-common";
+import { NotificationApi } from "@checkstack/notification-common";
 import { AnomalyService } from "./service";
 import { createRouter } from "./router";
 import { createAnomalyRouterCache, type AnomalyRouterCache } from "./router-cache";
-import { anomalyContract, anomalyAccessRules } from "@checkstack/anomaly-common";
+import {
+  anomalyContract,
+  anomalyAccessRules,
+  anomalySystemSubscription,
+  anomalyGroupSubscription,
+} from "@checkstack/anomaly-common";
+import { specToRegistration } from "@checkstack/notification-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
 
 import { definePluginMetadata } from "@checkstack/common";
@@ -18,10 +25,16 @@ export const plugin = createBackendPlugin({
   }),
   register(env) {
     env.registerAccessRules(anomalyAccessRules);
+    // Declared subscription specs feed the plugin loader's
+    // dependency sorter — each spec's target.ownerPlugin becomes an
+    // implicit init-order dep, so anomaly waits for catalog (the
+    // owner of catalogSystemTarget / catalogGroupTarget) before its
+    // own init + afterPluginsReady runs.
+    env.registerSubscriptionSpecs([
+      anomalySystemSubscription,
+      anomalyGroupSubscription,
+    ]);
 
-    // Shared between init (router) and afterPluginsReady (detector hook),
-    // so the detector can drop the router cache before broadcasting state
-    // change signals.
     let routerCache: AnomalyRouterCache | undefined;
 
     env.registerInit({
@@ -30,7 +43,7 @@ export const plugin = createBackendPlugin({
         db: coreServices.database,
         logger: coreServices.logger,
         queueManager: coreServices.queueManager,
-        cacheManager: coreServices.cacheManager, // Pre-req
+        cacheManager: coreServices.cacheManager,
         rpcClient: coreServices.rpcClient,
         rpc: coreServices.rpc,
         signalService: coreServices.signalService,
@@ -43,6 +56,7 @@ export const plugin = createBackendPlugin({
         const typedDb = db as SafeDatabase<typeof schema>;
         const healthCheckClient = rpcClient.forPlugin(HealthCheckApi);
         const catalogClient = rpcClient.forPlugin(CatalogApi);
+        const notificationClient = rpcClient.forPlugin(NotificationApi);
 
         await setupBaselineAnalyzerJob({
           db: typedDb,
@@ -52,6 +66,7 @@ export const plugin = createBackendPlugin({
           healthCheckClient,
           signalService,
           catalogClient,
+          notificationClient,
           collectorRegistry,
         });
 
@@ -66,6 +81,21 @@ export const plugin = createBackendPlugin({
         const cache = cacheManager.getProvider();
         const typedDb = db as SafeDatabase<typeof schema>;
         const catalogClient = rpcClient.forPlugin(CatalogApi);
+        const notificationClient = rpcClient.forPlugin(NotificationApi);
+
+        // Register subscription specs against the platform. notification-
+        // backend takes care of provisioning per-resource groups by joining
+        // the spec's target type onto the resource registry catalog already
+        // pushes — anomaly never needs to know about per-system or
+        // per-group lifecycle.
+        await Promise.all([
+          notificationClient.registerSubscriptionSpec(
+            specToRegistration(anomalySystemSubscription),
+          ),
+          notificationClient.registerSubscriptionSpec(
+            specToRegistration(anomalyGroupSubscription),
+          ),
+        ]);
 
         onHook(healthCheckHooks.checkCompleted, async (payload) => {
           await processCheckCompleted({
@@ -75,6 +105,7 @@ export const plugin = createBackendPlugin({
             routerCache,
             logger,
             catalogClient,
+            notificationClient,
             signalService,
             collectorRegistry,
           });

package/src/router.ts

@@ -1,8 +1,13 @@
 import { implement } from "@orpc/server";
 import { anomalyContract } from "@checkstack/anomaly-common";
 import type { AnomalyService } from "./service";
-import type { Logger } from "@checkstack/backend-api";
-import type { VersionedRecord } from "@checkstack/backend-api";
+import {
+  autoAuthMiddleware,
+  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";
 
@@ -11,7 +16,9 @@ export function createRouter(
   logger: Logger,
   cache: AnomalyRouterCache,
 ) {
-  const os = implement(anomalyContract);
+  const os = implement(anomalyContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
 
   return os.router({
     getAnomalies: os.getAnomalies.handler(
@@ -70,5 +77,36 @@ export function createRouter(
         return result as VersionedRecord<Partial<AnomalySettings>>;
       }
     ),
+
+    listAnomalyNotificationMutes: os.listAnomalyNotificationMutes.handler(
+      async ({ input, context }) => {
+        const userId = (context.user as RealUser).id;
+        return service.listMutes({ userId, systemId: input.systemId });
+      },
+    ),
+
+    muteAnomalyNotification: os.muteAnomalyNotification.handler(
+      async ({ input, context }) => {
+        const userId = (context.user as RealUser).id;
+        await service.addMute({
+          userId,
+          systemId: input.systemId,
+          fieldPath: input.fieldPath,
+        });
+        return { success: true };
+      },
+    ),
+
+    unmuteAnomalyNotification: os.unmuteAnomalyNotification.handler(
+      async ({ input, context }) => {
+        const userId = (context.user as RealUser).id;
+        await service.removeMute({
+          userId,
+          systemId: input.systemId,
+          fieldPath: input.fieldPath,
+        });
+        return { success: true };
+      },
+    ),
   });
 }

package/src/schema.ts

@@ -8,6 +8,8 @@ import {
   timestamp,
   doublePrecision,
   unique,
+  index,
+  primaryKey,
 } from "drizzle-orm/pg-core";
 
 export const anomalyStateEnum = pgEnum("anomaly_state", [
@@ -85,3 +87,27 @@ export const anomalyAssignments = pgTable("anomaly_assignments", {
 }, (t) => ({
   pk: unique("anomaly_assignments_pk").on(t.systemId, t.configurationId),
 }));
+
+/**
+ * Per-user mute records for anomaly notifications. A row's existence means
+ * the user has muted notifications for that (system, fieldPath) pair.
+ *
+ * Empty fieldPath ("") represents a system-wide mute — anomaly notifications
+ * for the entire system are suppressed for that user. We collapse the two
+ * granularities into one table so dispatch can answer "is this user muted?"
+ * with a single index lookup instead of two queries.
+ */
+export const anomalyNotificationMutes = pgTable(
+  "anomaly_notification_mutes",
+  {
+    userId: text("user_id").notNull(),
+    systemId: text("system_id").notNull(),
+    fieldPath: text("field_path").notNull(),
+    mutedAt: timestamp("muted_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.userId, t.systemId, t.fieldPath] }),
+    userIdx: index("anomaly_notification_mutes_user_idx").on(t.userId),
+    systemIdx: index("anomaly_notification_mutes_system_idx").on(t.systemId),
+  }),
+);

package/src/service.ts

@@ -1,4 +1,4 @@
-import { eq, and, desc } from "drizzle-orm";
+import { eq, and, desc, inArray } from "drizzle-orm";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import { anomalySettingsConfig } from "./config";
@@ -160,4 +160,106 @@ export class AnomalyService {
 
     return result.config;
   }
+
+  /**
+   * List anomaly-notification mutes for a user. Optionally narrow to one
+   * system. Returns the same shape as the DTO (mutedAt is ISO-formatted).
+   */
+  async listMutes({
+    userId,
+    systemId,
+  }: {
+    userId: string;
+    systemId?: string;
+  }) {
+    const conditions = [eq(schema.anomalyNotificationMutes.userId, userId)];
+    if (systemId !== undefined) {
+      conditions.push(eq(schema.anomalyNotificationMutes.systemId, systemId));
+    }
+
+    const rows = await this.db
+      .select()
+      .from(schema.anomalyNotificationMutes)
+      .where(and(...conditions));
+
+    return rows.map((r) => ({
+      systemId: r.systemId,
+      fieldPath: r.fieldPath,
+      mutedAt: r.mutedAt.toISOString(),
+    }));
+  }
+
+  async addMute({
+    userId,
+    systemId,
+    fieldPath,
+  }: {
+    userId: string;
+    systemId: string;
+    fieldPath: string;
+  }) {
+    await this.db
+      .insert(schema.anomalyNotificationMutes)
+      .values({ userId, systemId, fieldPath })
+      .onConflictDoNothing();
+  }
+
+  async removeMute({
+    userId,
+    systemId,
+    fieldPath,
+  }: {
+    userId: string;
+    systemId: string;
+    fieldPath: string;
+  }) {
+    await this.db
+      .delete(schema.anomalyNotificationMutes)
+      .where(
+        and(
+          eq(schema.anomalyNotificationMutes.userId, userId),
+          eq(schema.anomalyNotificationMutes.systemId, systemId),
+          eq(schema.anomalyNotificationMutes.fieldPath, fieldPath),
+        ),
+      );
+  }
+
+  /**
+   * For a given (system, fieldPath), return the set of userIds that have
+   * muted notifications. A row with empty fieldPath ("") for the system
+   * counts as a mute regardless of which field triggered the dispatch.
+   * Used by the notification dispatcher to populate `excludeUserIds`.
+   *
+   * `candidateUserIds` is optional — when omitted, returns every user
+   * that ever muted this (system, field). The notification backend
+   * intersects against actual subscribers anyway, so a broader exclude
+   * set is harmless.
+   */
+  async getMutedUserIds({
+    systemId,
+    fieldPath,
+    candidateUserIds,
+  }: {
+    systemId: string;
+    fieldPath: string;
+    candidateUserIds?: string[];
+  }): Promise<Set<string>> {
+    const conditions = [
+      eq(schema.anomalyNotificationMutes.systemId, systemId),
+      inArray(schema.anomalyNotificationMutes.fieldPath, [fieldPath, ""]),
+    ];
+    if (candidateUserIds !== undefined) {
+      if (candidateUserIds.length === 0) return new Set();
+      conditions.push(
+        inArray(schema.anomalyNotificationMutes.userId, candidateUserIds),
+      );
+    }
+
+    const rows = await this.db
+      .select({ userId: schema.anomalyNotificationMutes.userId })
+      .from(schema.anomalyNotificationMutes)
+      .where(and(...conditions));
+
+    return new Set(rows.map((r) => r.userId));
+  }
 }