@checkstack/healthcheck-backend 1.19.0 → 1.20.0

package/src/queue-executor.ts

@@ -379,18 +379,20 @@ export async function recomputeSystemRollupHealth(args: {
   // pure entity-recompute path (pause/resume) skips the extra prev read.
   const wantsSignal = signalService !== undefined || cache !== undefined;
   try {
-    let previousStatus: HealthCheckStatus | undefined;
+    // Capture the FULL rollup states (not just the status enum) so the cache
+    // reconcile can gate on the per-check vector while the frontend signal
+    // stays gated on the coarser rollup-enum transition.
+    let previousState: AggregatedHealth | undefined;
     if (wantsSignal) {
-      const previousState = await service.getSystemHealthStatus(systemId);
-      previousStatus = previousState.status;
+      previousState = await service.getSystemHealthStatus(systemId);
     }
-    let newStatus: HealthCheckStatus | undefined = previousStatus;
+    let newState: AggregatedHealth | undefined = previousState;
     await writeHealthEntity({
       handle: getHealthEntity?.(),
       entityId: rollupEntityId,
       apply: async () => {
         const rollupState = await service.getSystemHealthStatus(systemId);
-        newStatus = rollupState.status;
+        newState = rollupState;
         return toHealthEntityView(rollupState);
       },
       serialize: makeHealthSerializer(rollupEntityId),
@@ -401,21 +403,23 @@ export async function recomputeSystemRollupHealth(args: {
         ),
     });
 
-    if (
-      wantsSignal &&
-      previousStatus !== undefined &&
-      newStatus !== undefined &&
-      newStatus !== previousStatus
-    ) {
-      await cache?.invalidateSystem(systemId);
-      await signalService?.broadcast(SYSTEM_STATUS_CHANGED, {
-        systemId,
-        previousStatus,
-        newStatus,
-      });
+    if (wantsSignal && previousState !== undefined && newState !== undefined) {
+      // Cache: evict the rollup key + broadcast to the cluster on ANY per-check
+      // vector change — a check that flips while the rollup enum stays put still
+      // changes the rollup's `checkStatuses`, and a reader gets that vector.
+      await cache?.reconcile({ systemId, previous: previousState, next: newState });
+      // Frontend signal: only a rollup-enum transition moves the badge, so a
+      // per-check-only change needs no SYSTEM_STATUS_CHANGED refetch signal.
+      if (newState.status !== previousState.status) {
+        await signalService?.broadcast(SYSTEM_STATUS_CHANGED, {
+          systemId,
+          previousStatus: previousState.status,
+          newStatus: newState.status,
+        });
+      }
     }
-    return previousStatus !== undefined && newStatus !== undefined
-      ? { previousStatus, newStatus }
+    return previousState !== undefined && newState !== undefined
+      ? { previousStatus: previousState.status, newStatus: newState.status }
       : undefined;
   } catch (error) {
     // A recompute failure must never break the pause/resume RPC. The
@@ -692,13 +696,14 @@ async function executeHealthCheckJob(props: {
   // other.
   const makeHealthSerializer = createHealthEntitySerializer({ advisoryLock });
 
-  // The system-rollup status BEFORE this tick (all environments + env-less).
-  // Captured once so the post-loop rollup write (§7.4.3) — and the
-  // catastrophic-failure path — can record a correct prev → next rollup
-  // transition (environmentId = null). This is the system-wide aggregate read
-  // the executor has always taken first.
-  const rollupPreviousState = await service.getSystemHealthStatus(systemId);
-  const rollupPreviousStatus = rollupPreviousState.status;
+  // NOTE: the system-rollup status BEFORE this tick is computed LAZILY, only on
+  // the catastrophic-failure path that actually consumes it (see the `catch`
+  // below). It used to be captured here on EVERY run - a full worst-wins rollup
+  // (`getSystemHealthStatus(systemId)`, an N+1 across every check × environment)
+  // - even though the normal success/failure paths record their transition from
+  // the per-env pre-read (`previousState`, below) and never touch the rollup
+  // pre-state. Deferring it to the rare error path removes that whole recompute
+  // from the hot path of every check tick.
 
   // Slow-check lane admission (set when this run was admitted to the suspect
   // lane); released in the outer finally so the slot frees on any exit path.
@@ -954,14 +959,16 @@ async function executeHealthCheckJob(props: {
       const envEntityId = encodeHealthEntityId({ systemId, environmentId });
       const serializeEnvWrite = makeHealthSerializer(envEntityId);
 
-      // Per-env baseline status for the transition log: the env-scoped
-      // aggregate BEFORE this run. Computed per env so a transition row is
-      // recorded against the right (system, environment) streak.
-      const previousState = await service.getSystemHealthStatus(
-        systemId,
-        environmentId,
-      );
-      const previousStatus = previousState.status;
+      // Per-env baseline: the env-scoped aggregate BEFORE this run. Read INSIDE
+      // the serialized `apply` below (assigned to these vars), NOT here — so a
+      // concurrent same-slice run cannot commit between the baseline read and
+      // our own insert. If it were read here (outside the `health:<envEntityId>`
+      // lock), the cache change-gate could compare `next` against a baseline a
+      // sibling run already superseded and miss a real transition, stranding a
+      // stale cached status until the TTL. Assigned by whichever branch's
+      // `apply` runs; used for the transition log AND the cache reconcile.
+      let previousState!: AggregatedHealth;
+      let previousStatus!: HealthCheckStatus;
 
       // Curated, read-only run-context metadata exposed to collectors.
       // Metadata only - never secrets or config. `environment` carries the
@@ -1269,6 +1276,13 @@ async function executeHealthCheckJob(props: {
         handle: getHealthEntity?.(),
         entityId: envEntityId,
         apply: async () => {
+          // In-lock pre-run baseline (see the `previousState` declaration): read
+          // here, inside the serialized critical section, before the insert.
+          previousState = await service.getSystemHealthStatus(
+            systemId,
+            environmentId,
+          );
+          previousStatus = previousState.status;
           // §perf: batch the run INSERT + aggregate SELECT/UPSERT under ONE
           // `SET LOCAL search_path` transaction (3 scoped-db transactions → 1),
           // which also makes the run and its aggregate commit atomically.
@@ -1316,9 +1330,18 @@ async function executeHealthCheckJob(props: {
         `Health check ${configId} for system ${systemId} failed: ${finalError}`,
       );
 
-      // Invalidate the per-system status cache before broadcasting so any
-      // frontend that refetches in response to the signal gets fresh data.
-      await cache.invalidateSystem(systemId);
+      // Reconcile this environment's cached status: evict + broadcast to the
+      // cluster ONLY when the per-check vector actually changed (a run that
+      // leaves every check's status unchanged keeps the cache warm instead of
+      // thrashing it every tick). The rollup key is reconciled separately by
+      // the debounced rollup consumer (recomputeSystemRollupHealth), also
+      // vector-gated.
+      await cache.reconcile({
+        systemId,
+        environmentId,
+        previous: previousState,
+        next: newState,
+      });
 
       await signalService.broadcast(HEALTH_CHECK_RUN_COMPLETED, {
         systemId,
@@ -1427,6 +1450,13 @@ async function executeHealthCheckJob(props: {
       handle: getHealthEntity?.(),
       entityId: envEntityId,
       apply: async () => {
+        // In-lock pre-run baseline (see the `previousState` declaration): read
+        // here, inside the serialized critical section, before the insert.
+        previousState = await service.getSystemHealthStatus(
+          systemId,
+          environmentId,
+        );
+        previousStatus = previousState.status;
         // §perf: batch the run INSERT + aggregate SELECT/UPSERT under ONE
         // `SET LOCAL search_path` transaction (3 scoped-db transactions → 1),
         // which also makes the run and its aggregate commit atomically.
@@ -1473,9 +1503,16 @@ async function executeHealthCheckJob(props: {
       `Ran health check ${configId} for system ${systemId}: ${result.status}`,
     );
 
-    // Invalidate the per-system status cache before broadcasting so any
-    // frontend that refetches in response to the signal gets fresh data.
-    await cache.invalidateSystem(systemId);
+    // Reconcile this environment's cached status: evict + broadcast to the
+    // cluster ONLY when the per-check vector actually changed (a steady-state
+    // healthy run keeps the cache warm). The rollup key is reconciled by the
+    // debounced rollup consumer (recomputeSystemRollupHealth), also vector-gated.
+    await cache.reconcile({
+      systemId,
+      environmentId,
+      previous: previousState,
+      next: newState,
+    });
 
     // Broadcast enriched signal for realtime frontend updates (e.g., terminal feed)
     await signalService.broadcast(HEALTH_CHECK_RUN_COMPLETED, {
@@ -1582,12 +1619,19 @@ async function executeHealthCheckJob(props: {
     // the system-level health change still emits. Reuses the pre-tick
     // rollup status captured before the try block.
     const rollupEntityId = encodeHealthEntityId({ systemId });
-    const previousStatus = rollupPreviousStatus;
+    // The pre-failure rollup baseline. Read INSIDE `apply` (inside the
+    // `health:<systemId>` lock), before the failure-run insert, so a concurrent
+    // catastrophic tick for the same system can't commit between the baseline
+    // read and this insert and make the cache change-gate miss a transition.
+    let rollupPreState!: AggregatedHealth;
+    let previousStatus!: HealthCheckStatus;
     let newState!: AggregatedHealth;
     await writeHealthEntity({
       handle: getHealthEntity?.(),
       entityId: rollupEntityId,
       apply: async () => {
+        rollupPreState = await service.getSystemHealthStatus(systemId);
+        previousStatus = rollupPreState.status;
         // §perf: batch the failure run INSERT + aggregate SELECT/UPSERT under
         // ONE `SET LOCAL search_path` transaction (3 scoped-db transactions →
         // 1), which also makes them commit atomically.
@@ -1646,9 +1690,15 @@ async function executeHealthCheckJob(props: {
       // Use IDs as fallback
     }
 
-    // Invalidate the per-system status cache before broadcasting so any
-    // frontend that refetches in response to the signal gets fresh data.
-    await cache.invalidateSystem(systemId);
+    // Reconcile the rollup cache: evict + broadcast only on a real vector
+    // change. This catastrophic path writes the bare `<systemId>` entity (it IS
+    // the rollup), so it owns the rollup key directly — no debounced consumer
+    // runs for it.
+    await cache.reconcile({
+      systemId,
+      previous: rollupPreState,
+      next: newState,
+    });
 
     // Broadcast enriched failure signal for realtime frontend updates
     await signalService.broadcast(HEALTH_CHECK_RUN_COMPLETED, {

package/src/retention-job.ts

@@ -153,6 +153,14 @@ async function deleteExpiredRawRuns(params: DeleteExpiredRawRunsParams) {
   const cutoffDate = new Date();
   cutoffDate.setDate(cutoffDate.getDate() - rawRetentionDays);
 
+  // Status-cache note: this delete does NOT invalidate the system-health status
+  // cache, and deliberately need not. `evaluateHealthStatus` derives status from
+  // the most-recent-N runs (count-based, no time component), and the cutoff is
+  // days old, so for any ACTIVELY-running check the deleted rows are already
+  // outside the evaluation window — removing them cannot change the current
+  // derived status. The only case it could is a check that STOPPED running long
+  // enough for its entire history to age past the cutoff; that flip is bounded by
+  // the 15s status-cache TTL (an acceptable, rare edge for a stopped check).
   await db
     .delete(healthCheckRuns)
     .where(

package/src/rollup-consumer.test.ts

@@ -35,7 +35,7 @@ interface Harness {
   changeHandler: (change: EntityChanged) => Promise<void>;
   getSystemHealthStatus: ReturnType<typeof mock>;
   broadcast: ReturnType<typeof mock>;
-  invalidateSystem: ReturnType<typeof mock>;
+  reconcile: ReturnType<typeof mock>;
 }
 
 async function setup(opts: {
@@ -75,7 +75,7 @@ async function setup(opts: {
   }) as unknown as OnEntityChanged;
 
   const broadcast = mock(async () => {});
-  const invalidateSystem = mock(async () => {});
+  const reconcile = mock(async () => {});
 
   await setupRollupConsumer({
     queueManager,
@@ -85,7 +85,7 @@ async function setup(opts: {
       withXactLock: async ({ fn }: { fn: () => Promise<unknown> }) => fn(),
     } as never,
     signalService: { broadcast } as never,
-    cache: { invalidateSystem } as never,
+    cache: { reconcile } as never,
     // No entity handle: writeHealthEntity runs `apply` directly.
     getHealthEntity: () => undefined,
     logger: {
@@ -103,7 +103,7 @@ async function setup(opts: {
     changeHandler,
     getSystemHealthStatus,
     broadcast,
-    invalidateSystem,
+    reconcile,
   };
 }
 
@@ -162,12 +162,21 @@ describe("setupRollupConsumer subscription", () => {
 });
 
 describe("setupRollupConsumer rollup recompute", () => {
-  it("broadcasts SYSTEM_STATUS_CHANGED + invalidates cache on a rollup status change", async () => {
+  it("reconciles the cache + broadcasts SYSTEM_STATUS_CHANGED on a rollup status change", async () => {
     const h = await setup({ statuses: ["healthy", "unhealthy"] });
     await h.consumeHandler({ data: { systemId: "s1" } });
 
     expect(h.getSystemHealthStatus).toHaveBeenCalled();
-    expect(h.invalidateSystem).toHaveBeenCalledWith("s1");
+    // Reconcile is handed the FULL prev/next states; the change-gating (evict +
+    // cluster broadcast only on a per-check vector change) lives inside the cache
+    // (see cache.test.ts), so recompute always calls it with both states.
+    expect(h.reconcile).toHaveBeenCalledTimes(1);
+    expect(h.reconcile.mock.calls[0]![0]).toMatchObject({
+      systemId: "s1",
+      previous: { status: "healthy" },
+      next: { status: "unhealthy" },
+    });
+    // The frontend signal IS gated here on the rollup-enum transition.
     expect(h.broadcast).toHaveBeenCalledTimes(1);
     const payload = h.broadcast.mock.calls[0]![1] as {
       systemId: string;
@@ -181,11 +190,13 @@ describe("setupRollupConsumer rollup recompute", () => {
     });
   });
 
-  it("does NOT broadcast when the rollup status is unchanged", async () => {
+  it("does NOT broadcast the frontend signal when the rollup status is unchanged", async () => {
     const h = await setup({ statuses: ["degraded", "degraded"] });
     await h.consumeHandler({ data: { systemId: "s1" } });
 
+    // No enum transition ⇒ no SYSTEM_STATUS_CHANGED frontend signal. Reconcile is
+    // still invoked (its own fingerprint gate no-ops for an unchanged vector).
     expect(h.broadcast).not.toHaveBeenCalled();
-    expect(h.invalidateSystem).not.toHaveBeenCalled();
+    expect(h.reconcile).toHaveBeenCalledTimes(1);
   });
 });

package/src/router-config-secrets.test.ts

@@ -16,7 +16,7 @@ import {
   healthcheckSecretMarker,
   isHealthcheckSecretMarker,
 } from "./config-secrets";
-import type { HealthCheckCache } from "./cache";
+import { createStubHealthCheckCache } from "./cache-test-stub";
 
 /**
  * Guards the SEC-1 fix: `createAndAssign` (the first-check wizard / AI propose
@@ -24,12 +24,7 @@ import type { HealthCheckCache } from "./cache";
  * and return a REDACTED config - never persist or echo a plaintext credential.
  */
 
-const passthroughCache: HealthCheckCache = {
-  wrapSystemHealthStatus: (_systemId, loader) => loader(),
-  invalidateSystem: async () => {},
-  invalidateAllSystems: async () => 0,
-  scope: {} as HealthCheckCache["scope"],
-};
+const passthroughCache = createStubHealthCheckCache();
 
 const mockUser = {
   type: "user" as const,

package/src/router-create-and-assign.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, mock } from "bun:test";
 import { createHealthCheckRouter } from "./router";
 import { createMockRpcContext } from "@checkstack/backend-api";
 import { call } from "@orpc/server";
-import type { HealthCheckCache } from "./cache";
+import { createStubHealthCheckCache } from "./cache-test-stub";
 
 /**
  * Router-level tests for the atomic create+assign path and the
@@ -12,12 +12,7 @@ import type { HealthCheckCache } from "./cache";
  * `input.body.notificationPolicy`).
  */
 
-const passthroughCache: HealthCheckCache = {
-  wrapSystemHealthStatus: (_systemId, loader) => loader(),
-  invalidateSystem: async () => {},
-  invalidateAllSystems: async () => 0,
-  scope: {} as HealthCheckCache["scope"],
-};
+const passthroughCache = createStubHealthCheckCache();
 
 const mockUser = {
   type: "user" as const,

package/src/router-pause-recompute.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { createHealthCheckRouter } from "./router";
 import { createMockRpcContext } from "@checkstack/backend-api";
 import { call } from "@orpc/server";
-import type { HealthCheckCache } from "./cache";
+import { createStubHealthCheckCache } from "./cache-test-stub";
 
 /**
  * Router-level tests for the pause/resume handlers' rollup-health recompute
@@ -14,12 +14,7 @@ import type { HealthCheckCache } from "./cache";
  * any degraded transition (see the resume handler comment for rationale).
  */
 
-const passthroughCache: HealthCheckCache = {
-  wrapSystemHealthStatus: (_systemId, loader) => loader(),
-  invalidateSystem: async () => {},
-  invalidateAllSystems: async () => 0,
-  scope: {} as HealthCheckCache["scope"],
-};
+const passthroughCache = createStubHealthCheckCache();
 
 const mockUser = {
   type: "user" as const,

package/src/router.test.ts

@@ -3,14 +3,9 @@ import { createHealthCheckRouter } from "./router";
 import { createMockRpcContext, Versioned } from "@checkstack/backend-api";
 import { call } from "@orpc/server";
 import { z } from "zod";
-import type { HealthCheckCache } from "./cache";
-
-const passthroughCache: HealthCheckCache = {
-  wrapSystemHealthStatus: (_systemId, loader) => loader(),
-  invalidateSystem: async () => {},
-  invalidateAllSystems: async () => 0,
-  scope: {} as HealthCheckCache["scope"],
-};
+import { createStubHealthCheckCache } from "./cache-test-stub";
+
+const passthroughCache = createStubHealthCheckCache();
 
 describe("HealthCheck Router", () => {
   const mockUser = {

package/src/router.ts

@@ -710,9 +710,10 @@ export const createHealthCheckRouter = (opts: {
     ),
     getSystemHealthStatus: os.getSystemHealthStatus.handler(
       async ({ input }) => {
-        const base = await cache.wrapSystemHealthStatus(input.systemId, () =>
-          service.getSystemHealthStatus(input.systemId),
-        );
+        // The cache holds the RAW (pre-override) status; incident overrides are
+        // folded downstream (always live) so an override lifts the instant its
+        // incident resolves. See ./cache.ts for the key/TTL/invalidation contract.
+        const base = await cache.read(input.systemId);
         const folded = await foldIncidentOverrides({
           [input.systemId]: base,
         });
@@ -724,24 +725,15 @@ export const createHealthCheckRouter = (opts: {
       async ({ input }) => {
         // Per-entity caching: each system's status is cached individually
         // and invalidated by id on mutations, so dashboards with overlapping
-        // (but non-identical) system sets share cache entries. See
-        // ./cache.ts for the key/TTL/invalidation contract.
-        const statuses: Record<string, SystemHealthStatusResponse> = {};
-        await Promise.all(
-          input.systemIds.map(async (systemId) => {
-            statuses[systemId] = await cache.wrapSystemHealthStatus(
-              systemId,
-              () => service.getSystemHealthStatus(systemId),
-            );
-          }),
-        );
+        // (but non-identical) system sets share cache entries.
+        const statuses = await cache.readBulk(input.systemIds);
         return { statuses: await foldIncidentOverrides(statuses) };
       },
     ),
 
     getBulkSystemHealthMatrix: os.getBulkSystemHealthMatrix.handler(
       async ({ input }) => {
-        const matrix = await service.getBulkSystemHealthMatrix(input.systemIds);
+        const matrix = await cache.readMatrix(input.systemIds);
 
         // Fold active incident overrides into each system's OVERALL rollup, so
         // an incident-forced status still propagates through dependencies (as

package/src/schema.ts

@@ -127,6 +127,13 @@ export const systemHealthChecks = pgTable(
   },
   (t) => ({
     pk: primaryKey({ columns: [t.systemId, t.configurationId] }),
+    // Reverse lookup for getSystemIdsForConfiguration on config-change
+    // recompute (WHERE configuration_id [AND enabled]). The PK leads with
+    // system_id, so a config-scoped scan cannot use it.
+    configEnabledIdx: index("system_health_checks_config_enabled_idx").on(
+      t.configurationId,
+      t.enabled,
+    ),
   }),
 );
 
@@ -186,37 +193,65 @@ export const healthCheckStateTransitions = pgTable(
   }),
 );
 
-export const healthCheckRuns = pgTable("health_check_runs", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  configurationId: uuid("configuration_id")
-    .notNull()
-    .references(() => healthCheckConfigurations.id, { onDelete: "cascade" }),
-  systemId: text("system_id").notNull(),
-  /**
-   * Environment this run was executed for (per-environment fan-out).
-   * null = ran with no environment (the opt-out / no-membership case,
-   * which is exactly the pre-feature behavior). Nullable text, NOT a FK
-   * to the catalog `environments` table (healthcheck and catalog are
-   * separate plugins with separate Postgres schemas, mirroring how
-   * `systemId` is a bare text with no FK to `systems`).
-   */
-  environmentId: text("environment_id"),
-  status: healthCheckStatusEnum("status").notNull(),
-  /** Execution duration in milliseconds */
-  latencyMs: integer("latency_ms"),
-  result: jsonb("result").$type<Record<string, unknown>>(),
-  /**
-   * Source identifier for result attribution.
-   * null = local core execution, UUID = satellite ID.
-   */
-  sourceId: text("source_id"),
-  /**
-   * Human-readable source label for UI display.
-   * e.g. "Local" or "EU West (eu-west-1)".
-   */
-  sourceLabel: text("source_label"),
-  timestamp: timestamp("timestamp").defaultNow().notNull(),
-});
+export const healthCheckRuns = pgTable(
+  "health_check_runs",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    configurationId: uuid("configuration_id")
+      .notNull()
+      .references(() => healthCheckConfigurations.id, { onDelete: "cascade" }),
+    systemId: text("system_id").notNull(),
+    /**
+     * Environment this run was executed for (per-environment fan-out).
+     * null = ran with no environment (the opt-out / no-membership case,
+     * which is exactly the pre-feature behavior). Nullable text, NOT a FK
+     * to the catalog `environments` table (healthcheck and catalog are
+     * separate plugins with separate Postgres schemas, mirroring how
+     * `systemId` is a bare text with no FK to `systems`).
+     */
+    environmentId: text("environment_id"),
+    status: healthCheckStatusEnum("status").notNull(),
+    /** Execution duration in milliseconds */
+    latencyMs: integer("latency_ms"),
+    result: jsonb("result").$type<Record<string, unknown>>(),
+    /**
+     * Source identifier for result attribution.
+     * null = local core execution, UUID = satellite ID.
+     */
+    sourceId: text("source_id"),
+    /**
+     * Human-readable source label for UI display.
+     * e.g. "Local" or "EU West (eu-west-1)".
+     */
+    sourceLabel: text("source_label"),
+    timestamp: timestamp("timestamp").defaultNow().notNull(),
+  },
+  (t) => ({
+    // The status read path reads the last N runs for a (system, check) slice
+    // ordered by timestamp DESC. Without a supporting index every such read
+    // sequential-scans the whole (multi-million-row) table and sorts. Postgres
+    // scans a plain btree backward, so an ASC index serves ORDER BY ... DESC.
+    //
+    // Cross-environment newest-run read (WHERE system_id, configuration_id
+    // ORDER BY timestamp DESC LIMIT n - the single hottest query) and the
+    // retention DELETE (WHERE system_id, configuration_id AND timestamp < cutoff).
+    checkRecentIdx: index("health_check_runs_check_recent_idx").on(
+      t.systemId,
+      t.configurationId,
+      t.timestamp,
+    ),
+    // Env-scoped slice read (WHERE system_id, configuration_id,
+    // environment_id [= ? | IS NULL] ORDER BY timestamp DESC LIMIT n), the
+    // per-check DISTINCT-environment discovery, and the per-env "last healthy"
+    // max(timestamp) GROUP BY environment_id.
+    sliceRecentIdx: index("health_check_runs_slice_recent_idx").on(
+      t.systemId,
+      t.configurationId,
+      t.environmentId,
+      t.timestamp,
+    ),
+  }),
+);
 
 /**
  * Bucket size enum for aggregated data.
@@ -286,5 +321,13 @@ export const healthCheckAggregates = pgTable(
       t.bucketSize,
       t.sourceId,
     ).nullsNotDistinct(),
+    // Health-state read with configuration_id absent (WHERE system_id,
+    // bucket_size, bucket_start ...). The unique index leads with
+    // configuration_id, so this query scans without a system-leading index.
+    systemBucketIdx: index("health_check_aggregates_system_bucket_idx").on(
+      t.systemId,
+      t.bucketSize,
+      t.bucketStart,
+    ),
   }),
 );