@checkstack/healthcheck-backend 1.21.2 → 1.22.0

package/drizzle/meta/_journal.json

@@ -148,6 +148,13 @@
       "when": 1783607735562,
       "tag": "0020_certain_mordo",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1784736274302,
+      "tag": "0021_amazing_wolf_cub",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "1.21.2",
+  "version": "1.22.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,50 +14,49 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/ai-backend": "0.11.2",
-    "@checkstack/ai-common": "0.6.6",
-    "@checkstack/automation-backend": "0.11.6",
-    "@checkstack/backend-api": "0.33.0",
-    "@checkstack/cache-api": "0.3.19",
-    "@checkstack/cache-utils": "0.3.0",
-    "@checkstack/catalog-backend": "1.9.2",
-    "@checkstack/catalog-common": "2.7.3",
-    "@checkstack/command-backend": "0.2.25",
-    "@checkstack/common": "0.22.0",
-    "@checkstack/gitops-backend": "0.5.25",
-    "@checkstack/gitops-common": "0.7.3",
-    "@checkstack/healthcheck-common": "1.17.0",
-    "@checkstack/incident-backend": "1.13.4",
-    "@checkstack/incident-common": "1.10.3",
-    "@checkstack/maintenance-common": "1.10.3",
-    "@checkstack/notification-common": "1.7.1",
-    "@checkstack/queue-api": "0.3.19",
-    "@checkstack/satellite-backend": "0.9.2",
-    "@checkstack/script-packages-backend": "0.4.4",
-    "@checkstack/sdk": "0.132.0",
-    "@checkstack/secrets-backend": "0.3.7",
-    "@checkstack/secrets-common": "0.3.2",
-    "@checkstack/signal-common": "0.3.0",
-    "@checkstack/status-page-backend": "0.6.4",
-    "@checkstack/status-page-common": "0.6.3",
+    "@checkstack/ai-backend": "0.11.4",
+    "@checkstack/ai-common": "0.6.7",
+    "@checkstack/automation-backend": "0.11.8",
+    "@checkstack/backend-api": "0.34.1",
+    "@checkstack/cache-api": "0.3.20",
+    "@checkstack/cache-utils": "0.3.1",
+    "@checkstack/catalog-backend": "1.10.1",
+    "@checkstack/catalog-common": "2.8.1",
+    "@checkstack/command-backend": "0.2.27",
+    "@checkstack/common": "0.23.0",
+    "@checkstack/gitops-backend": "0.5.27",
+    "@checkstack/gitops-common": "0.7.4",
+    "@checkstack/healthcheck-common": "1.19.0",
+    "@checkstack/healthcheck-execution": "0.35.0",
+    "@checkstack/incident-backend": "1.13.6",
+    "@checkstack/incident-common": "1.10.5",
+    "@checkstack/maintenance-common": "1.10.5",
+    "@checkstack/notification-common": "1.8.0",
+    "@checkstack/queue-api": "0.4.0",
+    "@checkstack/satellite-backend": "0.9.4",
+    "@checkstack/script-packages-backend": "0.4.6",
+    "@checkstack/sdk": "0.135.1",
+    "@checkstack/secrets-backend": "0.3.9",
+    "@checkstack/secrets-common": "0.3.3",
+    "@checkstack/signal-common": "0.3.1",
+    "@checkstack/status-page-backend": "0.6.6",
+    "@checkstack/status-page-common": "0.6.5",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.25",
     "jsonpath-plus": "^10.4.0",
-    "tdigest": "^0.1.2",
     "yaml": "^2.6.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.7.5",
-    "@checkstack/test-utils-backend": "0.1.59",
+    "@checkstack/scripts": "0.7.6",
+    "@checkstack/test-utils-backend": "0.1.61",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/pg": "^8.20.0",
-    "@types/tdigest": "^0.1.5",
     "bullmq": "^5.66.4",
     "date-fns": "^4.4.0",
     "drizzle-kit": "^0.31.10",

package/src/ai/system-signals-contributor.test.ts

@@ -23,6 +23,7 @@ const unhealthyStatuses: HealthcheckSignalStatuses = {
         runsConsidered: 5,
         sliceCount: 1,
         failingSliceCount: 1,
+        slices: [],
       },
     ],
   },

package/src/cache.test.ts

@@ -63,6 +63,9 @@ function response(
       runsConsidered: 1,
       sliceCount: c.sliceCount ?? 1,
       failingSliceCount: c.failingSliceCount ?? 0,
+      // These tests exercise the cache's fingerprint/invalidation behaviour,
+      // which reads the counts rather than the per-slice breakdown.
+      slices: [],
     })),
   };
 }

package/src/effective-environments.test.ts

@@ -1,5 +1,8 @@
-import { describe, it, expect } from "bun:test";
-import { resolveEffectiveEnvironments } from "./effective-environments";
+import { describe, it, test, expect } from "bun:test";
+import {
+  resolveEffectiveEnvironments,
+  resolveSatelliteEnvironments,
+} from "./effective-environments";
 import type { Environment } from "@checkstack/catalog-common";
 
 const env = (
@@ -91,3 +94,61 @@ describe("resolveEffectiveEnvironments", () => {
     expect(result).toEqual([]);
   });
 });
+
+describe("resolveSatelliteEnvironments", () => {
+  const effective = [
+    { id: "env-prod", name: "Production", fields: {} },
+    { id: "env-stage", name: "Staging", fields: {} },
+  ];
+
+  test("an unscoped satellite runs every environment the assignment resolved to", () => {
+    // The backfill-free default: a NULL column means no scoping, so existing
+    // assignments keep behaving exactly as they did.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: undefined,
+      }),
+    ).toEqual(effective);
+    expect(
+      resolveSatelliteEnvironments({ effective, satelliteEnvironmentIds: null }),
+    ).toEqual(effective);
+  });
+
+  test("a scoped satellite runs only its own environments", () => {
+    // The point of the feature: the prod satellite probes prod, and never
+    // reaches for a staging endpoint it may have no route to.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-prod"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod"]);
+  });
+
+  test("a satellite can NARROW but never widen the assignment's scope", () => {
+    // An id the assignment does not cover silently drops - a satellite must not
+    // be able to probe an environment the assignment itself excluded.
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-prod", "env-secret"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod"]);
+  });
+
+  test("an empty selector opts the satellite out into a single env-less run", () => {
+    expect(
+      resolveSatelliteEnvironments({ effective, satelliteEnvironmentIds: [] }),
+    ).toEqual([]);
+  });
+
+  test("preserves the assignment's order, so fan-out stays deterministic", () => {
+    expect(
+      resolveSatelliteEnvironments({
+        effective,
+        satelliteEnvironmentIds: ["env-stage", "env-prod"],
+      }).map((e) => e.id),
+    ).toEqual(["env-prod", "env-stage"]);
+  });
+});

package/src/effective-environments.ts

@@ -62,3 +62,37 @@ export function resolveEffectiveEnvironments({
     .filter((env) => wanted.has(env.id))
     .map((env) => toEffective(env));
 }
+
+/**
+ * Narrow an assignment's effective environments to those a SPECIFIC satellite
+ * should run.
+ *
+ * A satellite's selector can only ever narrow, never widen: the assignment
+ * decides which environments exist for this check, and the satellite decides
+ * which of those it is responsible for. That ordering is what lets a prod
+ * satellite run only prod without being able to reach environments the
+ * assignment itself excluded.
+ *
+ * - `undefined` / `null` => every environment the assignment resolved to. This
+ *   is the default for an unscoped satellite, so existing assignments keep
+ *   behaving exactly as they did.
+ * - `[]`                 => opt out: one env-less run on this satellite.
+ * - non-empty            => exactly those ids, intersected with `effective`;
+ *   an id the assignment does not cover silently drops.
+ *
+ * Order follows `effective`, so fan-out order stays deterministic.
+ */
+export function resolveSatelliteEnvironments({
+  effective,
+  satelliteEnvironmentIds,
+}: {
+  effective: EffectiveEnvironment[];
+  satelliteEnvironmentIds: string[] | null | undefined;
+}): EffectiveEnvironment[] {
+  if (satelliteEnvironmentIds === null || satelliteEnvironmentIds === undefined) {
+    return effective;
+  }
+  if (satelliteEnvironmentIds.length === 0) return [];
+  const wanted = new Set(satelliteEnvironmentIds);
+  return effective.filter((env) => wanted.has(env.id));
+}

package/src/health-entity.ts

@@ -22,7 +22,7 @@
  *  - the `writeHealthEntity` helper called at every evaluation-write site.
  */
 import { z } from "zod";
-import { HealthCheckStatusSchema } from "@checkstack/healthcheck-common";
+import { SystemHealthStatusSchema } from "@checkstack/healthcheck-common";
 import type { AdvisoryLockService } from "@checkstack/backend-api";
 import type {
   EntityChangeDeriver,
@@ -43,7 +43,13 @@ export const HEALTH_ENTITY_KIND = "health";
  * same durable data `getSystemHealthStatus` reads — never materialized.
  */
 export const HealthEntityStateSchema = z.object({
-  status: HealthCheckStatusSchema,
+  /**
+   * `unknown` when the system's checks have produced no runs to evaluate.
+   * Automations matching on `unhealthy` therefore do NOT fire for a system that
+   * is merely unmeasured - which is the point: an unmeasured system is not a
+   * detected outage, and inventing `healthy` for it would hide the gap instead.
+   */
+  status: SystemHealthStatusSchema,
   healthyChecks: z.number().int().nonnegative(),
   totalChecks: z.number().int().nonnegative(),
 });

package/src/health-state.ts

@@ -1,5 +1,5 @@
 import { and, desc, eq, gte, isNull } from "drizzle-orm";
-import type { HealthCheckStatus } from "@checkstack/healthcheck-common";
+import type { SystemHealthStatus } from "@checkstack/healthcheck-common";
 import type { Logger, SafeDatabase } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
@@ -20,8 +20,11 @@ type MaintenanceClient = InferClient<typeof MaintenanceApi>;
  * re-deriving the math each time.
  */
 export interface HealthState {
-  /** Aggregate status across all enabled checks. */
-  status: HealthCheckStatus;
+  /**
+   * Aggregate status across all enabled checks. `unknown` when nothing has been
+   * measured yet - the system has no checks, or none of them has ever run.
+   */
+  status: SystemHealthStatus;
   /**
    * When the system most recently entered `status`. Null when no
    * transition has been recorded yet (fail-safe: never throws).
@@ -58,7 +61,8 @@ export interface HealthState {
 
 /** Raw inputs to the pure builder, decoupled from the DB layer. */
 export interface HealthStateInputs {
-  status: HealthCheckStatus;
+  /** May be `unknown` - nothing measured yet. */
+  status: SystemHealthStatus;
   inStatusSince: Date | null;
   latencyMs?: number;
   avgLatencyMs?: number;
@@ -330,7 +334,7 @@ export async function computeHealthState({
    */
   environmentId?: string | null;
   /** Returns the aggregate status for the system (per-check when scoped). */
-  resolveStatus: () => Promise<HealthCheckStatus>;
+  resolveStatus: () => Promise<SystemHealthStatus>;
   maintenanceClient?: MaintenanceClient;
   logger?: Logger;
   /** Trailing window (minutes) for the transition count. */
@@ -341,7 +345,12 @@ export async function computeHealthState({
 
   const [inStatusSince, latest, windowed, inMaintenance, transitionsInWindow] =
     await Promise.all([
-      findInStatusSince({ db, systemId, status, environmentId }),
+      // An UNMEASURED system has no transition rows to find - and `unknown` is
+      // not a member of the transition table's status enum, so querying for it
+      // would be a database error, not merely an empty result.
+      status === "unknown"
+        ? Promise.resolve(null)
+        : findInStatusSince({ db, systemId, status, environmentId }),
       findLatestRun({ db, systemId, configurationId, environmentId }),
       computeWindowedMetrics({ db, systemId, configurationId, environmentId, now }),
       resolveInMaintenance({ maintenanceClient, systemId, logger }),

package/src/index.ts

@@ -1,6 +1,7 @@
 import {
   setupHealthCheckWorker,
   recomputeSystemRollupHealth,
+  persistRunAndReact,
 } from "./queue-executor";
 import { reconcileHealthCheckJobs } from "./schedule-reconciler";
 import { setupRetentionJob } from "./retention-job";
@@ -287,20 +288,12 @@ export default createBackendPlugin({
         };
         gitopsConfigSecrets = configSecrets;
 
-        // Move any pre-channel inline secrets out of stored rows (idempotent,
-        // advisory-locked, fail-open: a backfill failure must not block boot).
-        try {
-          await backfillConfigSecrets({
-            db: typedDb,
-            registry: healthCheckRegistry,
-            collectorRegistry,
-            internalSecrets,
-            advisoryLock,
-            logger,
-          });
-        } catch (error) {
-          logger.warn("Config-secrets backfill failed; continuing boot", error);
-        }
+        // NOTE: the config-secrets backfill runs in afterPluginsReady, NOT
+        // here. Strategies contributed by OTHER plugins (e.g. logstream's
+        // LogStreamHealthStrategy) register during THEIR init(), and init
+        // order follows the service-ref graph - it is NOT guaranteed that
+        // every contributor initialized before this plugin. Backfilling here
+        // would skip configs of not-yet-registered strategies with a warn.
 
         // Resolve/search health-check configurations by name for the Teams admin
         // UI (team grants are stored as opaque `<type>:<configId>` rows, where
@@ -600,6 +593,28 @@ export default createBackendPlugin({
               logger,
             });
           },
+          // Bind the service deps ONCE so an ingested satellite result drives
+          // the exact same post-run path (`persistRunAndReact`) as a local run:
+          // reactive entity write, cache reconcile, signals, automation hooks,
+          // transition, and notification. The router only supplies the per-run
+          // fields, so the two callers cannot drift.
+          reactToSatelliteRun: (run) =>
+            persistRunAndReact({
+              db: database,
+              service,
+              cache,
+              signalService,
+              notificationClient,
+              catalogClient,
+              maintenanceClient,
+              incidentClient,
+              getHealthEntity: () => healthEntity,
+              getEmitHook: () => storedEmitHook,
+              collectorRegistry,
+              advisoryLock,
+              logger,
+              ...run,
+            }),
         });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);
 
@@ -644,6 +659,30 @@ export default createBackendPlugin({
         // Store emitHook for the queue worker (Closure-based Hook Getter pattern)
         storedEmitHook = emitHook;
 
+        // Move any pre-channel inline secrets out of stored rows (idempotent,
+        // advisory-locked, fail-open: a backfill failure must not block boot).
+        // Runs HERE - after every plugin's init() - because strategies are
+        // contributed by other plugins during their init (e.g. logstream's
+        // health strategy), and only afterPluginsReady guarantees the registry
+        // is complete; running in init raced contributor init order.
+        if (gitopsConfigSecrets && resolvedAdvisoryLock) {
+          try {
+            await backfillConfigSecrets({
+              db: database,
+              registry: healthCheckRegistry,
+              collectorRegistry,
+              internalSecrets: gitopsConfigSecrets.internalSecrets,
+              advisoryLock: resolvedAdvisoryLock,
+              logger,
+            });
+          } catch (error) {
+            logger.warn(
+              "Config-secrets backfill failed; continuing boot",
+              error,
+            );
+          }
+        }
+
         // No cross-pod status-cache broadcast: the status cache runs on the
         // platform CacheManager, so a distributed backend (Redis) makes every
         // eviction visible to all pods through the shared store. The prior