@checkstack/healthcheck-backend 1.2.0 → 1.4.0

package/src/service-notification-policy.test.ts

@@ -51,9 +51,7 @@ describe("HealthCheckService.getAssignmentNotificationPolicy", () => {
 
   it("falls back to platform defaults when association exists but notificationPolicy is null", async () => {
     const customPlatformDefault: NotificationPolicy = {
-      ...DEFAULT_NOTIFICATION_POLICY,
-      autoCloseAfterMinutes: 120,
-      sustainedUnhealthyTrigger: { enabled: true, durationMinutes: 15 },
+      suppressDeEscalations: true,
     };
     const service = buildServiceWithRows(
       [{ notificationPolicy: null }],
@@ -63,40 +61,27 @@ describe("HealthCheckService.getAssignmentNotificationPolicy", () => {
       systemId: "sys-1",
       configurationId: "cfg-1",
     });
-    expect(policy.autoCloseAfterMinutes).toBe(120);
-    expect(policy.sustainedUnhealthyTrigger.durationMinutes).toBe(15);
+    expect(policy.suppressDeEscalations).toBe(true);
   });
 
   it("falls back to platform defaults when no association exists", async () => {
     const customPlatformDefault: NotificationPolicy = {
-      ...DEFAULT_NOTIFICATION_POLICY,
-      flappingTrigger: { enabled: true, transitions: 10, windowMinutes: 30 },
+      suppressDeEscalations: true,
     };
     const service = buildServiceWithRows([], customPlatformDefault);
     const policy = await service.getAssignmentNotificationPolicy({
       systemId: "sys-1",
       configurationId: "cfg-1",
     });
-    expect(policy.flappingTrigger).toEqual({
-      enabled: true,
-      transitions: 10,
-      windowMinutes: 30,
-    });
+    expect(policy).toEqual({ suppressDeEscalations: true });
   });
 
   it("prefers per-assignment override over platform defaults", async () => {
     const platformDefault: NotificationPolicy = {
-      ...DEFAULT_NOTIFICATION_POLICY,
-      autoOpenIncidentOnUnhealthy: false,
+      suppressDeEscalations: false,
     };
     const assignmentOverride = {
-      suppressDeEscalations: true,
-      autoOpenIncidentOnUnhealthy: true, // overrides platform default
-      useNotificationSuppression: true,
-      skipDuringMaintenance: true,
-      sustainedUnhealthyTrigger: { enabled: true, durationMinutes: 30 },
-      flappingTrigger: { enabled: true, transitions: 3, windowMinutes: 60 },
-      autoCloseAfterMinutes: 30,
+      suppressDeEscalations: true, // overrides platform default
     };
     const service = buildServiceWithRows(
       [{ notificationPolicy: assignmentOverride }],
@@ -106,69 +91,41 @@ describe("HealthCheckService.getAssignmentNotificationPolicy", () => {
       systemId: "sys-1",
       configurationId: "cfg-1",
     });
-    expect(policy.autoOpenIncidentOnUnhealthy).toBe(true);
     expect(policy.suppressDeEscalations).toBe(true);
   });
 
-  it("fills in defaults for partial stored policies", async () => {
-    // Older rows may have only `suppressDeEscalations` set from the
-    // first migration. All other fields must default in.
-    const service = buildServiceWithRows([
-      { notificationPolicy: { suppressDeEscalations: true } },
-    ]);
+  it("fills in defaults for an empty stored policy", async () => {
+    const service = buildServiceWithRows([{ notificationPolicy: {} }]);
     const policy = await service.getAssignmentNotificationPolicy({
       systemId: "sys-1",
       configurationId: "cfg-1",
     });
-    expect(policy.suppressDeEscalations).toBe(true);
-    expect(policy.autoOpenIncidentOnUnhealthy).toBe(true);
-    expect(policy.useNotificationSuppression).toBe(true);
-    expect(policy.skipDuringMaintenance).toBe(true);
-    expect(policy.sustainedUnhealthyTrigger).toEqual({
-      enabled: true,
-      durationMinutes: 30,
-    });
-    expect(policy.flappingTrigger).toEqual({
-      enabled: true,
-      transitions: 3,
-      windowMinutes: 60,
-    });
-    expect(policy.autoCloseAfterMinutes).toBe(30);
+    expect(policy).toEqual({ suppressDeEscalations: false });
   });
 
-  it("returns explicit values exactly when fully specified", async () => {
-    const service = buildServiceWithRows([
-      {
-        notificationPolicy: {
-          suppressDeEscalations: false,
-          autoOpenIncidentOnUnhealthy: false,
-          useNotificationSuppression: false,
-          skipDuringMaintenance: false,
-          sustainedUnhealthyTrigger: { enabled: false, durationMinutes: 15 },
-          flappingTrigger: {
-            enabled: true,
-            transitions: 5,
-            windowMinutes: 30,
-          },
-          autoCloseAfterMinutes: null,
-        },
+  it("strips removed legacy keys (auto-incident AND flapping) from stored rows without throwing", async () => {
+    // A row persisted before the legacy auto-incident fields and the flapping
+    // thresholds were removed still carries the larger object. The schema
+    // strips the dead keys and keeps the one surviving field.
+    const legacyOversizedRow = {
+      notificationPolicy: {
+        suppressDeEscalations: true,
+        // Removed flapping thresholds — moved onto the automation trigger.
+        flappingTrigger: { enabled: true, transitions: 7, windowMinutes: 45 },
+        // Removed legacy auto-incident keys — must be dropped, not rejected.
+        autoOpenIncidentOnUnhealthy: true,
+        useNotificationSuppression: true,
+        skipDuringMaintenance: true,
+        sustainedUnhealthyTrigger: { enabled: true, durationMinutes: 15 },
+        autoCloseAfterMinutes: 120,
       },
-    ]);
+    };
+    const service = buildServiceWithRows([legacyOversizedRow]);
     const policy = await service.getAssignmentNotificationPolicy({
       systemId: "sys-1",
       configurationId: "cfg-1",
     });
-    expect(policy.autoOpenIncidentOnUnhealthy).toBe(false);
-    expect(policy.skipDuringMaintenance).toBe(false);
-    expect(policy.sustainedUnhealthyTrigger).toEqual({
-      enabled: false,
-      durationMinutes: 15,
-    });
-    expect(policy.flappingTrigger).toEqual({
-      enabled: true,
-      transitions: 5,
-      windowMinutes: 30,
-    });
-    expect(policy.autoCloseAfterMinutes).toBeNull();
+    expect(policy).toEqual({ suppressDeEscalations: true });
+    expect(Object.keys(policy)).toEqual(["suppressDeEscalations"]);
   });
 });

package/src/service.ts

@@ -11,6 +11,8 @@ import {
   DEFAULT_NOTIFICATION_POLICY,
 } from "@checkstack/healthcheck-common";
 import type { ConfigService } from "@checkstack/backend-api";
+import type { InferClient } from "@checkstack/common";
+import type { CatalogApi } from "@checkstack/catalog-common";
 import {
   notificationDefaultsConfigV1,
   NOTIFICATION_DEFAULTS_CONFIG_ID,
@@ -36,7 +38,10 @@ import {
 } from "drizzle-orm";
 import { ORPCError } from "@orpc/server";
 import { evaluateHealthStatus } from "./state-evaluator";
+import { computeHealthState, type HealthState } from "./health-state";
 import { stateThresholds } from "./state-thresholds-migrations";
+import type { MaintenanceApi } from "@checkstack/maintenance-common";
+import type { Logger } from "@checkstack/backend-api";
 import { incrementHourlyAggregate } from "./realtime-aggregation";
 import type {
   HealthCheckRegistry,
@@ -56,6 +61,14 @@ import {
 // Drizzle type helper - uses SafeDatabase to prevent relational query API usage
 type Db = SafeDatabase<typeof schema>;
 
+// Catalog client type used to resolve human-readable system names for
+// satellite assignment run-context. Optional on the service.
+type CatalogClient = InferClient<typeof CatalogApi>;
+
+// Maintenance client type used to fold suppression-agnostic maintenance
+// state into the health-state snapshot. Optional on the read path.
+type MaintenanceClient = InferClient<typeof MaintenanceApi>;
+
 interface SystemCheckStatus {
   configurationId: string;
   configurationName: string;
@@ -83,6 +96,12 @@ export class HealthCheckService {
      * have to plumb it through.
      */
     private configService?: ConfigService,
+    /**
+     * Optional — used to resolve human-readable system names when building
+     * satellite assignment run-context. When absent (e.g. GitOps-only /
+     * test constructions), `systemName` falls back to the `systemId`.
+     */
+    private catalogClient?: CatalogClient,
   ) {}
 
   /**
@@ -242,6 +261,35 @@ export class HealthCheckService {
       });
   }
 
+  /**
+   * Flip the `enabled` flag on an existing `systemHealthChecks` row
+   * without touching any of the other configuration (thresholds,
+   * satellite assignment, notification policy). Returns `true` when a
+   * row was updated, `false` when the assignment doesn't exist.
+   *
+   * Carved out so the automation actions `enable_assignment` /
+   * `disable_assignment` don't have to round-trip through
+   * `associateSystem` (which would otherwise wipe operator-managed
+   * fields when invoked with a sparse partial).
+   */
+  async setAssignmentEnabled(
+    systemId: string,
+    configurationId: string,
+    enabled: boolean,
+  ): Promise<boolean> {
+    const result = await this.db
+      .update(systemHealthChecks)
+      .set({ enabled, updatedAt: new Date() })
+      .where(
+        and(
+          eq(systemHealthChecks.systemId, systemId),
+          eq(systemHealthChecks.configurationId, configurationId),
+        ),
+      )
+      .returning({ systemId: systemHealthChecks.systemId });
+    return result.length > 0;
+  }
+
   async disassociateSystem(systemId: string, configurationId: string) {
     await this.db
       .delete(systemHealthChecks)
@@ -517,6 +565,88 @@ export class HealthCheckService {
     };
   }
 
+  /**
+   * Live health-state snapshot for a single system (Wave-2 sensing
+   * contract). When `configurationId` is given, status reflects that
+   * one check; otherwise it is the aggregate. `inStatusSince` /
+   * `inStatusForMs` come from the state-transitions table, latency from
+   * the newest run, windowed metrics from hourly aggregates, and
+   * `inMaintenance` from the maintenance plugin (suppression-agnostic,
+   * fail-open). `now` is threaded so bulk reads share one timestamp.
+   */
+  async getHealthState({
+    systemId,
+    configurationId,
+    maintenanceClient,
+    logger,
+    transitionWindowMinutes,
+    now,
+  }: {
+    systemId: string;
+    configurationId?: string;
+    maintenanceClient?: MaintenanceClient;
+    logger?: Logger;
+    transitionWindowMinutes?: number;
+    now?: Date;
+  }): Promise<HealthState> {
+    return computeHealthState({
+      db: this.db,
+      systemId,
+      configurationId,
+      maintenanceClient,
+      logger,
+      transitionWindowMinutes,
+      now,
+      resolveStatus: async () => {
+        const overview = await this.getSystemHealthStatus(systemId);
+        if (!configurationId) return overview.status;
+        const check = overview.checkStatuses.find(
+          (c) => c.configurationId === configurationId,
+        );
+        // Unknown check id -> treat as healthy (no signal), mirroring
+        // the "no checks configured" default.
+        return check?.status ?? "healthy";
+      },
+    });
+  }
+
+  /**
+   * Bulk variant of {@link getHealthState}. Resolves every system in
+   * parallel against a single shared `now` so durations are consistent
+   * across the batch. Avoids N+1 from dashboards and multi-system
+   * automation rules.
+   */
+  async getBulkHealthState({
+    systemIds,
+    maintenanceClient,
+    logger,
+    transitionWindowMinutes,
+    now = new Date(),
+  }: {
+    systemIds: string[];
+    maintenanceClient?: MaintenanceClient;
+    logger?: Logger;
+    transitionWindowMinutes?: number;
+    now?: Date;
+  }): Promise<Record<string, HealthState>> {
+    const entries = await Promise.all(
+      systemIds.map(
+        async (systemId) =>
+          [
+            systemId,
+            await this.getHealthState({
+              systemId,
+              maintenanceClient,
+              logger,
+              transitionWindowMinutes,
+              now,
+            }),
+          ] as const,
+      ),
+    );
+    return Object.fromEntries(entries);
+  }
+
   /**
    * Get comprehensive health overview for a system.
    * Returns all health checks with their last 25 runs for sparkline visualization.
@@ -1197,6 +1327,27 @@ export class HealthCheckService {
 
     if (matchingAssociations.length === 0) return [];
 
+    // Resolve human-readable system names once per distinct systemId.
+    // Falls back to the systemId when no catalog client is wired or the
+    // lookup fails, mirroring the queue-executor's resolution behaviour.
+    const systemNameCache = new Map<string, string>();
+    const resolveSystemName = async (systemId: string): Promise<string> => {
+      const cached = systemNameCache.get(systemId);
+      if (cached !== undefined) return cached;
+
+      let systemName = systemId;
+      if (this.catalogClient) {
+        try {
+          const system = await this.catalogClient.getSystem({ systemId });
+          if (system) systemName = system.name;
+        } catch {
+          // Fall back to systemId if catalog lookup fails.
+        }
+      }
+      systemNameCache.set(systemId, systemName);
+      return systemName;
+    };
+
     // Get configurations for each matching association
     const assignments = [];
     for (const assoc of matchingAssociations) {
@@ -1214,6 +1365,9 @@ export class HealthCheckService {
         config: config.config,
         collectors: config.collectors ?? undefined,
         intervalSeconds: config.intervalSeconds,
+        // Curated run-context metadata exposed to satellite collectors.
+        configName: config.name,
+        systemName: await resolveSystemName(assoc.systemId),
       });
     }
 

package/src/state-transitions.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, mock } from "bun:test";
+import {
+  countStateTransitionsInWindow,
+  findInStatusSince,
+  recordStateTransition,
+} from "./state-transitions";
+
+/**
+ * Minimal fluent mock for `db.select(...).from(...).where(...).orderBy(...).limit(...)`
+ * that resolves to the provided rows.
+ */
+function selectMockDb(rows: Array<{ transitionedAt: Date }>) {
+  return {
+    select: mock(() => ({
+      from: mock(() => ({
+        where: mock(() => ({
+          orderBy: mock(() => ({
+            limit: mock(() => Promise.resolve(rows)),
+          })),
+        })),
+      })),
+    })),
+  };
+}
+
+describe("findInStatusSince", () => {
+  it("returns the most-recent transitionedAt for the status", async () => {
+    const since = new Date("2026-05-30T10:00:00.000Z");
+    const db = selectMockDb([{ transitionedAt: since }]);
+    const result = await findInStatusSince({
+      db: db as never,
+      systemId: "system-1",
+      status: "unhealthy",
+    });
+    expect(result).toBe(since);
+  });
+
+  it("returns null (fail-safe) when no transition row exists", async () => {
+    const db = selectMockDb([]);
+    const result = await findInStatusSince({
+      db: db as never,
+      systemId: "system-1",
+      status: "degraded",
+    });
+    expect(result).toBeNull();
+  });
+});
+
+describe("recordStateTransition", () => {
+  it("inserts a row with from/to status and the provided timestamp", async () => {
+    const values =
+      mock<(v: Record<string, unknown>) => Promise<void>>(() =>
+        Promise.resolve(),
+      );
+    const db = { insert: mock(() => ({ values })) };
+    const now = new Date("2026-05-30T12:00:00.000Z");
+
+    await recordStateTransition({
+      db: db as never,
+      systemId: "system-1",
+      configurationId: "config-1",
+      fromStatus: "healthy",
+      toStatus: "unhealthy",
+      now,
+    });
+
+    expect(values).toHaveBeenCalledTimes(1);
+    expect(values.mock.calls[0]?.[0]).toEqual({
+      systemId: "system-1",
+      configurationId: "config-1",
+      fromStatus: "healthy",
+      toStatus: "unhealthy",
+      transitionedAt: now,
+    });
+  });
+
+  it("stores null fromStatus on the first-ever transition", async () => {
+    const values =
+      mock<(v: Record<string, unknown>) => Promise<void>>(() =>
+        Promise.resolve(),
+      );
+    const db = { insert: mock(() => ({ values })) };
+
+    await recordStateTransition({
+      db: db as never,
+      systemId: "system-1",
+      configurationId: "config-1",
+      fromStatus: undefined,
+      toStatus: "degraded",
+    });
+
+    const arg = values.mock.calls[0]?.[0] as { fromStatus: unknown };
+    expect(arg.fromStatus).toBeNull();
+  });
+});
+
+describe("countStateTransitionsInWindow", () => {
+  /** Mock for `db.select({count}).from(...).where(...)` resolving to [{count}]. */
+  function countMockDb(count: number) {
+    const where = mock(() => Promise.resolve([{ count }]));
+    const from = mock(() => ({ where }));
+    const select = mock(() => ({ from }));
+    return { db: { select }, where };
+  }
+
+  it("returns the windowed count", async () => {
+    const { db } = countMockDb(4);
+    const result = await countStateTransitionsInWindow({
+      db: db as never,
+      systemId: "system-1",
+      windowMinutes: 60,
+    });
+    expect(result).toBe(4);
+  });
+
+  it("returns 0 (fail-safe) when the query yields no rows", async () => {
+    const where = mock(() => Promise.resolve([]));
+    const db = { select: mock(() => ({ from: mock(() => ({ where })) })) };
+    const result = await countStateTransitionsInWindow({
+      db: db as never,
+      systemId: "system-1",
+      windowMinutes: 30,
+    });
+    expect(result).toBe(0);
+  });
+});

package/src/state-transitions.ts

@@ -0,0 +1,112 @@
+import { and, desc, eq, gte, sql } from "drizzle-orm";
+import type { HealthCheckStatus } from "@checkstack/healthcheck-common";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import { healthCheckStateTransitions } from "./schema";
+import * as schema from "./schema";
+
+type Db = SafeDatabase<typeof schema>;
+
+/**
+ * Record an aggregate health-status transition for a system. Called at
+ * the same point `systemHealthChanged` fires (one row per aggregate
+ * transition, which is rare). `fromStatus` is null on the first-ever
+ * recorded transition for a system.
+ */
+export async function recordStateTransition({
+  db,
+  systemId,
+  configurationId,
+  fromStatus,
+  toStatus,
+  now = new Date(),
+}: {
+  db: Db;
+  systemId: string;
+  configurationId: string;
+  fromStatus: HealthCheckStatus | undefined;
+  toStatus: HealthCheckStatus;
+  now?: Date;
+}): Promise<void> {
+  await db.insert(healthCheckStateTransitions).values({
+    systemId,
+    configurationId,
+    fromStatus: fromStatus ?? null,
+    toStatus,
+    transitionedAt: now,
+  });
+}
+
+/**
+ * Find the timestamp at which the system most recently entered the
+ * given status (the start of its current streak in that status).
+ *
+ * Fail-safe: when no transition row exists (e.g. the table was pruned
+ * before this system ever transitioned, or it has never changed status)
+ * this returns `null` rather than throwing, so callers degrade to
+ * `inStatusSince: null` instead of failing the whole evaluation.
+ */
+export async function findInStatusSince({
+  db,
+  systemId,
+  status,
+}: {
+  db: Db;
+  systemId: string;
+  status: HealthCheckStatus;
+}): Promise<Date | null> {
+  const [row] = await db
+    .select({ transitionedAt: healthCheckStateTransitions.transitionedAt })
+    .from(healthCheckStateTransitions)
+    .where(
+      and(
+        eq(healthCheckStateTransitions.systemId, systemId),
+        eq(healthCheckStateTransitions.toStatus, status),
+      ),
+    )
+    .orderBy(desc(healthCheckStateTransitions.transitionedAt))
+    .limit(1);
+
+  return row?.transitionedAt ?? null;
+}
+
+/**
+ * Count aggregate state transitions for a system within the trailing
+ * window `[now - windowMinutes, now]`. Generalizes the flapping detector's
+ * "N transitions in M minutes" count beyond the unhealthy-only table.
+ *
+ * When `toStatus` is given, counts only transitions INTO that status
+ * (e.g. flapping = repeated transitions into `unhealthy`); omit it to
+ * count all status changes in the window.
+ *
+ * Fail-safe: returns 0 on any error rather than throwing, so a count
+ * read never wedges an evaluation.
+ */
+export async function countStateTransitionsInWindow({
+  db,
+  systemId,
+  windowMinutes,
+  toStatus,
+  now = new Date(),
+}: {
+  db: Db;
+  systemId: string;
+  windowMinutes: number;
+  toStatus?: HealthCheckStatus;
+  now?: Date;
+}): Promise<number> {
+  const windowStart = new Date(now.getTime() - windowMinutes * 60_000);
+  const conditions = [
+    eq(healthCheckStateTransitions.systemId, systemId),
+    gte(healthCheckStateTransitions.transitionedAt, windowStart),
+  ];
+  if (toStatus) {
+    conditions.push(eq(healthCheckStateTransitions.toStatus, toStatus));
+  }
+
+  const [row] = await db
+    .select({ count: sql<number>`COUNT(*)::int` })
+    .from(healthCheckStateTransitions)
+    .where(and(...conditions));
+
+  return row?.count ?? 0;
+}

package/tsconfig.json

@@ -4,6 +4,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },
@@ -43,9 +46,6 @@
     {
       "path": "../incident-common"
     },
-    {
-      "path": "../integration-backend"
-    },
     {
       "path": "../maintenance-common"
     },
@@ -58,6 +58,15 @@
     {
       "path": "../satellite-backend"
     },
+    {
+      "path": "../script-packages-backend"
+    },
+    {
+      "path": "../secrets-backend"
+    },
+    {
+      "path": "../secrets-common"
+    },
     {
       "path": "../signal-common"
     },