@checkstack/healthcheck-backend 0.8.3 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @checkstack/healthcheck-backend
 
+## 0.10.0
+
+### Minor Changes
+
+- 869b4ab: ## Health Check Execution Improvements
+
+  ### Breaking Changes (backend-api)
+
+  - `HealthCheckStrategy.createClient()` now accepts `unknown` instead of `TConfig` due to TypeScript contravariance constraints. Implementations should use `this.config.validate(config)` to narrow the type.
+
+  ### Features
+
+  - **Platform-level hard timeout**: The executor now wraps the entire health check execution (connection + all collectors) in a single timeout, ensuring checks never hang indefinitely.
+  - **Parallel collector execution**: Collectors now run in parallel using `Promise.allSettled()`, improving performance while ensuring all collectors complete regardless of individual failures.
+  - **Base strategy config schema**: All strategy configs now extend `baseStrategyConfigSchema` which provides a standardized `timeout` field with sensible defaults (30s, min 100ms).
+
+  ### Fixes
+
+  - Fixed HTTP and Jenkins strategies clearing timeouts before reading the full response body.
+  - Simplified registry type signatures by using default type parameters.
+
+### Patch Changes
+
+- Updated dependencies [869b4ab]
+  - @checkstack/backend-api@0.8.0
+  - @checkstack/catalog-backend@0.2.13
+  - @checkstack/command-backend@0.1.11
+  - @checkstack/integration-backend@0.1.11
+  - @checkstack/queue-api@0.2.5
+
+## 0.9.0
+
+### Minor Changes
+
+- 3dd1914: Migrate health check strategies to VersionedAggregated with \_type discriminator
+
+  All 13 health check strategies now use `VersionedAggregated` for their `aggregatedResult` property, enabling automatic bucket merging with 100% mathematical fidelity.
+
+  **Key changes:**
+
+  - **`_type` discriminator**: All aggregated state objects now include a required `_type` field (`"average"`, `"rate"`, `"counter"`, `"minmax"`) for reliable type detection
+  - The `HealthCheckStrategy` interface now requires `aggregatedResult` to be a `VersionedAggregated<AggregatedResultShape>`
+  - Strategy/collector `mergeResult` methods return state objects with `_type` (e.g., `{ _type: "average", _sum, _count, avg }`)
+  - `mergeAggregatedBucketResults`, `combineBuckets`, and `reaggregateBuckets` now require `registry` and `strategyId` parameters
+  - `HealthCheckService` constructor now requires both `registry` and `collectorRegistry` parameters
+  - Frontend `extractComputedValue` now uses `_type` discriminator for robust type detection
+
+  **Breaking Change**: State objects now require `_type`. Merge functions automatically add `_type` to output. The bucket merging functions and `HealthCheckService` now require additional required parameters.
+
+### Patch Changes
+
+- Updated dependencies [3dd1914]
+  - @checkstack/backend-api@0.7.0
+  - @checkstack/catalog-backend@0.2.12
+  - @checkstack/command-backend@0.1.10
+  - @checkstack/integration-backend@0.1.10
+  - @checkstack/queue-api@0.2.4
+
 ## 0.8.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -10,17 +10,17 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.2",
-    "@checkstack/catalog-backend": "0.2.10",
-    "@checkstack/catalog-common": "1.2.6",
-    "@checkstack/command-backend": "0.1.8",
-    "@checkstack/common": "0.6.1",
-    "@checkstack/healthcheck-common": "0.8.1",
-    "@checkstack/incident-common": "0.4.2",
-    "@checkstack/integration-backend": "0.1.8",
-    "@checkstack/maintenance-common": "0.4.4",
-    "@checkstack/queue-api": "0.2.2",
-    "@checkstack/signal-common": "0.1.5",
+    "@checkstack/backend-api": "0.7.0",
+    "@checkstack/catalog-backend": "0.2.12",
+    "@checkstack/catalog-common": "1.2.7",
+    "@checkstack/command-backend": "0.1.10",
+    "@checkstack/common": "0.6.2",
+    "@checkstack/healthcheck-common": "0.8.2",
+    "@checkstack/incident-common": "0.4.3",
+    "@checkstack/integration-backend": "0.1.10",
+    "@checkstack/maintenance-common": "0.4.5",
+    "@checkstack/queue-api": "0.2.4",
+    "@checkstack/signal-common": "0.1.6",
     "@hono/zod-validator": "^0.7.6",
     "drizzle-orm": "^0.45.1",
     "hono": "^4.0.0",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.3",
     "@checkstack/scripts": "0.1.1",
-    "@checkstack/test-utils-backend": "0.1.8",
+    "@checkstack/test-utils-backend": "0.1.10",
     "@checkstack/tsconfig": "0.0.3",
     "@orpc/server": "^1.13.2",
     "@types/bun": "^1.0.0",

package/src/aggregation-utils.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "bun:test";
+import { describe, it, expect, mock } from "bun:test";
 import {
   calculatePercentile,
   calculateLatencyStats,
@@ -7,8 +7,35 @@ import {
   mergeTieredBuckets,
   combineBuckets,
   reaggregateBuckets,
+  mergeAggregatedBucketResults,
   type NormalizedBucket,
 } from "./aggregation-utils";
+import {
+  VersionedAggregated,
+  aggregatedCounter,
+  aggregatedAverage,
+  type CollectorRegistry,
+  type HealthCheckRegistry,
+} from "@checkstack/backend-api";
+
+// Helper to create mock registries for testing
+const createMockRegistries = () => {
+  const collectorRegistry: CollectorRegistry = {
+    register: mock(() => {}),
+    getCollector: mock(() => undefined),
+    getCollectors: mock(() => []),
+    getCollectorsForPlugin: mock(() => []),
+  };
+
+  const registry: HealthCheckRegistry = {
+    getStrategy: mock(() => undefined),
+    register: mock(() => {}),
+    getStrategies: mock(() => []),
+    getStrategiesWithMeta: mock(() => []),
+  };
+
+  return { collectorRegistry, registry, strategyId: "test-strategy" };
+};
 
 // Helper to create a NormalizedBucket for testing
 function createBucket(params: {
@@ -409,7 +436,9 @@ describe("aggregation-utils", () => {
 
     it("returns empty bucket for empty input", () => {
       const targetStart = new Date(0);
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets: [],
         targetBucketStart: targetStart,
         targetBucketEndMs: HOUR,
@@ -442,7 +471,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -470,7 +501,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -495,7 +528,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -520,7 +555,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -545,7 +582,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -560,7 +599,9 @@ describe("aggregation-utils", () => {
         createBucket({ startMs: HOUR, durationMs: HOUR, sourceTier: "hourly" }),
       ];
 
+      const mocks = createMockRegistries();
       const result = combineBuckets({
+        ...mocks,
         buckets,
         targetBucketStart: new Date(0),
         targetBucketEndMs: 2 * HOUR,
@@ -576,7 +617,9 @@ describe("aggregation-utils", () => {
     const HOUR = 60 * MINUTE;
 
     it("returns empty array for empty input", () => {
+      const mocks = createMockRegistries();
       const result = reaggregateBuckets({
+        ...mocks,
         sourceBuckets: [],
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
@@ -609,7 +652,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = reaggregateBuckets({
+        ...mocks,
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
@@ -643,7 +688,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = reaggregateBuckets({
+        ...mocks,
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
@@ -670,7 +717,9 @@ describe("aggregation-utils", () => {
         }),
       ];
 
+      const mocks = createMockRegistries();
       const result = reaggregateBuckets({
+        ...mocks,
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart,
@@ -693,7 +742,9 @@ describe("aggregation-utils", () => {
         createBucket({ startMs: HOUR, durationMs: MINUTE, sourceTier: "raw" }),
       ];
 
+      const mocks = createMockRegistries();
       const result = reaggregateBuckets({
+        ...mocks,
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
@@ -706,4 +757,228 @@ describe("aggregation-utils", () => {
       expect(result[2].bucketStart.getTime()).toBe(2 * HOUR);
     });
   });
+
+  describe("mergeAggregatedBucketResults - strategy metadata merging", () => {
+    it("merges strategy-level fields using strategy's mergeAggregatedStates", () => {
+      // Create a strategy with VersionedAggregated that tracks error counts
+      const strategyAggregatedResult = new VersionedAggregated({
+        version: 1,
+        fields: {
+          errorCount: aggregatedCounter({}),
+          avgResponseTime: aggregatedAverage({}),
+        },
+      });
+
+      const mockRegistry: HealthCheckRegistry = {
+        getStrategy: mock(() => ({
+          id: "test-strategy",
+          displayName: "Test",
+          description: "Test",
+          config: { version: 1 } as never,
+          result: { version: 1 } as never,
+          aggregatedResult: strategyAggregatedResult,
+          createClient: mock() as never,
+          mergeResult: mock() as never,
+        })),
+        register: mock(() => {}),
+        getStrategies: mock(() => []),
+        getStrategiesWithMeta: mock(() => []),
+      };
+
+      const mockCollectorRegistry: CollectorRegistry = {
+        register: mock(() => {}),
+        getCollector: mock(() => undefined),
+        getCollectors: mock(() => []),
+        getCollectorsForPlugin: mock(() => []),
+      };
+
+      // Two buckets with strategy-level aggregated data
+      const bucket1 = {
+        errorCount: { count: 5 },
+        avgResponseTime: { _sum: 500, _count: 10, avg: 50 },
+      };
+
+      const bucket2 = {
+        errorCount: { count: 3 },
+        avgResponseTime: { _sum: 300, _count: 5, avg: 60 },
+      };
+
+      const result = mergeAggregatedBucketResults({
+        aggregatedResults: [bucket1, bucket2],
+        collectorRegistry: mockCollectorRegistry,
+        registry: mockRegistry,
+        strategyId: "test-strategy",
+      });
+
+      expect(result).toBeDefined();
+      // Error count should be summed: 5 + 3 = 8
+      expect((result as Record<string, unknown>).errorCount).toEqual({
+        _type: "counter",
+        count: 8,
+      });
+      // Average should be recomputed: (500 + 300) / (10 + 5) = 53.33
+      const avgResult = (result as Record<string, unknown>)
+        .avgResponseTime as Record<string, number>;
+      expect(avgResult._sum).toBe(800);
+      expect(avgResult._count).toBe(15);
+      expect(avgResult.avg).toBeCloseTo(53.33, 1);
+    });
+
+    it("preserves strategy fields when only one bucket exists", () => {
+      const mocks = createMockRegistries();
+
+      const singleBucket = {
+        errorCount: { count: 5 },
+        avgResponseTime: { _sum: 500, _count: 10, avg: 50 },
+      };
+
+      const result = mergeAggregatedBucketResults({
+        aggregatedResults: [singleBucket],
+        ...mocks,
+      });
+
+      expect(result).toEqual(singleBucket);
+    });
+
+    it("returns undefined for empty aggregated results", () => {
+      const mocks = createMockRegistries();
+
+      const result = mergeAggregatedBucketResults({
+        aggregatedResults: [],
+        ...mocks,
+      });
+
+      expect(result).toBeUndefined();
+    });
+
+    it("merges both strategy and collector fields together", () => {
+      // Create a strategy with VersionedAggregated
+      const strategyAggregatedResult = new VersionedAggregated({
+        version: 1,
+        fields: { errorCount: aggregatedCounter({}) },
+      });
+
+      // Create a collector with VersionedAggregated
+      const collectorAggregatedResult = new VersionedAggregated({
+        version: 1,
+        fields: { cpuUsage: aggregatedAverage({}) },
+      });
+
+      const mockRegistry: HealthCheckRegistry = {
+        getStrategy: mock(() => ({
+          id: "test-strategy",
+          displayName: "Test",
+          description: "Test",
+          config: { version: 1 } as never,
+          result: { version: 1 } as never,
+          aggregatedResult: strategyAggregatedResult,
+          createClient: mock() as never,
+          mergeResult: mock() as never,
+        })),
+        register: mock(() => {}),
+        getStrategies: mock(() => []),
+        getStrategiesWithMeta: mock(() => []),
+      };
+
+      const mockCollectorRegistry = {
+        register: mock(() => {}),
+        getCollector: mock((id: string) => {
+          if (id === "test-collector") {
+            return {
+              collector: {
+                id: "test-collector",
+                displayName: "Test Collector",
+                description: "Test",
+                result: { version: 1 },
+                aggregatedResult: collectorAggregatedResult,
+                mergeResult: mock(),
+              },
+              qualifiedId: "test-plugin.test-collector",
+              ownerPlugin: "test-plugin",
+              pluginId: "test-plugin",
+            };
+          }
+          return undefined;
+        }),
+        getCollectors: mock(() => []),
+        getCollectorsForPlugin: mock(() => []),
+      } as unknown as CollectorRegistry;
+
+      // Two buckets with both strategy and collector data
+      const bucket1 = {
+        errorCount: { count: 2 },
+        collectors: {
+          "uuid-1": {
+            _collectorId: "test-collector",
+            cpuUsage: { _sum: 50, _count: 5, avg: 10 },
+          },
+        },
+      };
+
+      const bucket2 = {
+        errorCount: { count: 3 },
+        collectors: {
+          "uuid-1": {
+            _collectorId: "test-collector",
+            cpuUsage: { _sum: 100, _count: 10, avg: 10 },
+          },
+        },
+      };
+
+      const result = mergeAggregatedBucketResults({
+        aggregatedResults: [bucket1, bucket2],
+        collectorRegistry: mockCollectorRegistry,
+        registry: mockRegistry,
+        strategyId: "test-strategy",
+      });
+
+      expect(result).toBeDefined();
+      const typedResult = result as Record<string, unknown>;
+
+      // Strategy-level field merged
+      expect(typedResult.errorCount).toEqual({ _type: "counter", count: 5 });
+
+      // Collector-level field merged
+      const collectors = typedResult.collectors as Record<
+        string,
+        Record<string, unknown>
+      >;
+      expect(collectors["uuid-1"]._collectorId).toBe("test-collector");
+      const cpuUsage = collectors["uuid-1"].cpuUsage as Record<string, number>;
+      expect(cpuUsage._sum).toBe(150);
+      expect(cpuUsage._count).toBe(15);
+    });
+
+    it("falls back to preserving first result when strategy not found", () => {
+      const mockRegistry: HealthCheckRegistry = {
+        getStrategy: mock(() => undefined), // Strategy not found
+        register: mock(() => {}),
+        getStrategies: mock(() => []),
+        getStrategiesWithMeta: mock(() => []),
+      };
+
+      const mockCollectorRegistry: CollectorRegistry = {
+        register: mock(() => {}),
+        getCollector: mock(() => undefined),
+        getCollectors: mock(() => []),
+        getCollectorsForPlugin: mock(() => []),
+      };
+
+      const bucket1 = { errorCount: { count: 5 } };
+      const bucket2 = { errorCount: { count: 3 } };
+
+      const result = mergeAggregatedBucketResults({
+        aggregatedResults: [bucket1, bucket2],
+        collectorRegistry: mockCollectorRegistry,
+        registry: mockRegistry,
+        strategyId: "unknown-strategy",
+      });
+
+      // Should preserve the first bucket's strategy fields (fallback behavior)
+      expect(result).toBeDefined();
+      expect((result as Record<string, unknown>).errorCount).toEqual({
+        count: 5,
+      });
+    });
+  });
 });

package/src/aggregation-utils.ts

@@ -1,4 +1,7 @@
-import type { CollectorRegistry } from "@checkstack/backend-api";
+import type {
+  CollectorRegistry,
+  HealthCheckRegistry,
+} from "@checkstack/backend-api";
 
 // ===== Percentile Calculation =====
 
@@ -163,6 +166,156 @@ export function aggregateCollectorData(
   return result;
 }
 
+// ===== Bucket Result Merging =====
+
+/**
+ * Merge pre-computed aggregated results from multiple buckets.
+ * Uses each collector's VersionedAggregated.mergeAggregatedStates for precise re-aggregation.
+ * Also merges strategy-level fields using the strategy's mergeAggregatedStates.
+ *
+ * @param aggregatedResults - Array of aggregatedResult objects from buckets
+ * @param collectorRegistry - Registry to look up collector merge functions
+ * @param registry - HealthCheckRegistry for strategy-level merging
+ * @param strategyId - Strategy ID for strategy-level merging
+ * @returns Merged aggregated result, or undefined if no data
+ */
+export function mergeAggregatedBucketResults(params: {
+  aggregatedResults: Array<Record<string, unknown> | undefined>;
+  collectorRegistry: CollectorRegistry;
+  registry: HealthCheckRegistry;
+  strategyId: string;
+}): Record<string, unknown> | undefined {
+  const { aggregatedResults, collectorRegistry, registry, strategyId } = params;
+
+  // Filter out undefined results
+  const validResults = aggregatedResults.filter(
+    (r): r is Record<string, unknown> => r !== undefined,
+  );
+
+  if (validResults.length === 0) {
+    return undefined;
+  }
+
+  // If only one result, return it directly
+  if (validResults.length === 1) {
+    return validResults[0];
+  }
+
+  // === Strategy-level field merging ===
+  let mergedStrategyFields: Record<string, unknown> = {};
+
+  const registeredStrategy = registry.getStrategy(strategyId);
+  if (registeredStrategy?.aggregatedResult) {
+    // Extract strategy-level fields (everything except 'collectors')
+    const strategyDataSets: Array<Record<string, unknown>> = [];
+    for (const result of validResults) {
+      const { collectors: _collectors, ...strategyFields } = result;
+      if (Object.keys(strategyFields).length > 0) {
+        strategyDataSets.push(strategyFields);
+      }
+    }
+
+    // Merge strategy-level fields using the strategy's mergeAggregatedStates
+    if (strategyDataSets.length > 0) {
+      let merged: Record<string, unknown> | undefined;
+      for (const data of strategyDataSets) {
+        merged =
+          merged === undefined
+            ? data
+            : registeredStrategy.aggregatedResult.mergeAggregatedStates(
+                merged,
+                data,
+              );
+      }
+      if (merged) {
+        mergedStrategyFields = merged;
+      }
+    }
+  } else {
+    // Strategy not found - preserve strategy fields from first result
+    const { collectors: _collectors, ...firstStrategyFields } = validResults[0];
+    mergedStrategyFields = firstStrategyFields;
+  }
+
+  // === Collector-level field merging ===
+
+  // Extract collectors from each result
+  const allCollectors = validResults.map(
+    (r) => (r.collectors ?? {}) as Record<string, Record<string, unknown>>,
+  );
+
+  // Find all unique collector UUIDs across all results
+  const allUuids = new Set<string>();
+  for (const collectors of allCollectors) {
+    for (const uuid of Object.keys(collectors)) {
+      allUuids.add(uuid);
+    }
+  }
+
+  // Merge each collector's data
+  const mergedCollectors: Record<string, Record<string, unknown>> = {};
+
+  for (const uuid of allUuids) {
+    // Collect all data for this UUID
+    const dataForUuid: Array<Record<string, unknown>> = [];
+    let collectorId: string | undefined;
+
+    for (const collectors of allCollectors) {
+      const data = collectors[uuid];
+      if (data) {
+        collectorId = collectorId ?? (data._collectorId as string);
+        dataForUuid.push(data);
+      }
+    }
+
+    if (!collectorId || dataForUuid.length === 0) {
+      continue;
+    }
+
+    // Get the collector's merge function
+    const registered = collectorRegistry.getCollector(collectorId);
+    if (!registered?.collector.aggregatedResult) {
+      // Can't merge, preserve first data
+      mergedCollectors[uuid] = dataForUuid[0];
+      continue;
+    }
+
+    // Merge all data using mergeAggregatedStates
+    // Strip _collectorId before merging
+    let merged: Record<string, unknown> | undefined;
+    for (const data of dataForUuid) {
+      const { _collectorId, ...stateData } = data;
+      merged =
+        merged === undefined
+          ? stateData
+          : registered.collector.aggregatedResult.mergeAggregatedStates(
+              merged,
+              stateData,
+            );
+    }
+
+    if (merged) {
+      mergedCollectors[uuid] = {
+        _collectorId: collectorId,
+        ...merged,
+      };
+    }
+  }
+
+  // Combine strategy fields and collector fields
+  const hasCollectors = Object.keys(mergedCollectors).length > 0;
+  const hasStrategyFields = Object.keys(mergedStrategyFields).length > 0;
+
+  if (!hasCollectors && !hasStrategyFields) {
+    return undefined;
+  }
+
+  return {
+    ...mergedStrategyFields,
+    ...(hasCollectors ? { collectors: mergedCollectors } : {}),
+  };
+}
+
 // ===== Cross-Tier Aggregation =====
 
 /**
@@ -316,13 +469,26 @@ export function mergeTieredBuckets(params: {
 /**
  * Combine multiple buckets into a single bucket.
  * Used when re-aggregating smaller buckets into larger target buckets.
+ *
+ * Uses automatic merging via each strategy's and collector's
+ * VersionedAggregated.mergeAggregatedStates method.
  */
 export function combineBuckets(params: {
   buckets: NormalizedBucket[];
   targetBucketStart: Date;
   targetBucketEndMs: number;
+  collectorRegistry: CollectorRegistry;
+  registry: HealthCheckRegistry;
+  strategyId: string;
 }): NormalizedBucket {
-  const { buckets, targetBucketStart, targetBucketEndMs } = params;
+  const {
+    buckets,
+    targetBucketStart,
+    targetBucketEndMs,
+    collectorRegistry,
+    registry,
+    strategyId,
+  } = params;
 
   if (buckets.length === 0) {
     return {
@@ -356,7 +522,7 @@ export function combineBuckets(params: {
   // Track which tier the data primarily comes from
   let lowestPriorityTier: NormalizedBucket["sourceTier"] = "raw";
 
-  // Track aggregatedResults - only preserve if single bucket or all from raw
+  // Collect aggregatedResults for merging
   const aggregatedResults: Array<Record<string, unknown> | undefined> = [];
 
   for (const bucket of buckets) {
@@ -388,18 +554,13 @@ export function combineBuckets(params: {
     aggregatedResults.push(bucket.aggregatedResult);
   }
 
-  // Preserve aggregatedResult if there's exactly one bucket (no re-aggregation needed)
-  // or if there's exactly one non-undefined result and all buckets are raw
-  let preservedAggregatedResult: Record<string, unknown> | undefined;
-  if (buckets.length === 1) {
-    preservedAggregatedResult = buckets[0].aggregatedResult;
-  } else if (
-    lowestPriorityTier === "raw" &&
-    aggregatedResults.filter((r) => r !== undefined).length === 1
-  ) {
-    // All raw buckets, and exactly one has aggregatedResult
-    preservedAggregatedResult = aggregatedResults.find((r) => r !== undefined);
-  }
+  // Merge aggregatedResults using registries for precise re-aggregation
+  const mergedAggregatedResult = mergeAggregatedBucketResults({
+    aggregatedResults,
+    collectorRegistry,
+    registry,
+    strategyId,
+  });
 
   return {
     bucketStart: targetBucketStart,
@@ -413,8 +574,8 @@ export function combineBuckets(params: {
     maxLatencyMs: maxValues.length > 0 ? Math.max(...maxValues) : undefined,
     // Use max of p95s as conservative upper-bound approximation
     p95LatencyMs: p95Values.length > 0 ? Math.max(...p95Values) : undefined,
-    // Preserve aggregatedResult only when no actual re-aggregation is needed
-    aggregatedResult: preservedAggregatedResult,
+    // Automatically merged aggregatedResult
+    aggregatedResult: mergedAggregatedResult,
     sourceTier: lowestPriorityTier,
   };
 }
@@ -423,6 +584,9 @@ export function combineBuckets(params: {
  * Re-aggregate a list of normalized buckets into target-sized buckets.
  * Groups source buckets by target bucket boundaries and combines them.
  *
+ * Uses automatic merging of aggregatedResult via each strategy's and
+ * collector's VersionedAggregated.mergeAggregatedStates method.
+ *
  * @param rangeEnd - The end of the query range. The last bucket will extend
  *   to this time to ensure data is visually represented up to the query end.
  */
@@ -431,8 +595,19 @@ export function reaggregateBuckets(params: {
   targetIntervalMs: number;
   rangeStart: Date;
   rangeEnd: Date;
+  collectorRegistry: CollectorRegistry;
+  registry: HealthCheckRegistry;
+  strategyId: string;
 }): NormalizedBucket[] {
-  const { sourceBuckets, targetIntervalMs, rangeStart, rangeEnd } = params;
+  const {
+    sourceBuckets,
+    targetIntervalMs,
+    rangeStart,
+    rangeEnd,
+    collectorRegistry,
+    registry,
+    strategyId,
+  } = params;
 
   if (sourceBuckets.length === 0) {
     return [];
@@ -473,6 +648,9 @@ export function reaggregateBuckets(params: {
         buckets,
         targetBucketStart,
         targetBucketEndMs,
+        collectorRegistry,
+        registry,
+        strategyId,
       }),
     );
   }

package/src/aggregation.test.ts

@@ -5,6 +5,7 @@ describe("HealthCheckService.getAggregatedHistory", () => {
   // Mock database and registry
   let mockDb: ReturnType<typeof createMockDb>;
   let mockRegistry: ReturnType<typeof createMockRegistry>;
+  let mockCollectorRegistry: { getCollector: ReturnType<typeof mock> };
   let service: HealthCheckService;
   // Store mock data for different queries
   let mockConfigResult: { id: string; strategyId: string } | null = null;
@@ -78,7 +79,12 @@ describe("HealthCheckService.getAggregatedHistory", () => {
     mockDailyAggregates = [];
     mockDb = createMockDb();
     mockRegistry = createMockRegistry();
-    service = new HealthCheckService(mockDb as never, mockRegistry as never);
+    mockCollectorRegistry = { getCollector: mock(() => undefined) };
+    service = new HealthCheckService(
+      mockDb as never,
+      mockRegistry as never,
+      mockCollectorRegistry as never,
+    );
   });
 
   describe("dynamic bucket interval calculation", () => {

package/src/availability.test.ts

@@ -59,7 +59,7 @@ describe("HealthCheckService.getAvailabilityStats", () => {
     mockDailyAggregates = [];
     mockRetentionConfig = undefined;
     mockDb = createMockDb();
-    service = new HealthCheckService(mockDb as never);
+    service = new HealthCheckService(mockDb as never, {} as never, {} as never);
   });
 
   describe("with no data", () => {

package/src/index.ts

@@ -184,6 +184,7 @@ export default createBackendPlugin({
         onHook,
         emitHook,
         healthCheckRegistry,
+        collectorRegistry,
       }) => {
         // Store emitHook for the queue worker (Closure-based Hook Getter pattern)
         storedEmitHook = emitHook;
@@ -195,7 +196,11 @@ export default createBackendPlugin({
         });
 
         // Subscribe to catalog system deletion to clean up associations
-        const service = new HealthCheckService(database, healthCheckRegistry);
+        const service = new HealthCheckService(
+          database,
+          healthCheckRegistry,
+          collectorRegistry,
+        );
         onHook(
           catalogHooks.systemDeleted,
           async (payload) => {

package/src/queue-executor.test.ts

@@ -14,6 +14,8 @@ import {
 import {
   type HealthCheckRegistry,
   Versioned,
+  VersionedAggregated,
+  aggregatedCounter,
   z,
 } from "@checkstack/backend-api";
 import { mock } from "bun:test";
@@ -26,15 +28,15 @@ const createMockRegistry = (): HealthCheckRegistry => ({
     description: "Mock",
     config: new Versioned({
       version: 1,
-      schema: z.object({}),
+      schema: z.object({ timeout: z.number().default(30_000) }),
     }),
     result: new Versioned({
       version: 1,
       schema: z.object({}),
     }),
-    aggregatedResult: new Versioned({
+    aggregatedResult: new VersionedAggregated({
       version: 1,
-      schema: z.object({}),
+      fields: { count: aggregatedCounter({}) },
     }),
     createClient: mock(async () => ({
       client: {

package/src/queue-executor.ts

@@ -5,6 +5,9 @@ import {
   type CollectorRegistry,
   evaluateAssertions,
   type SafeDatabase,
+  type BaseStrategyConfig,
+  type ConnectedClient,
+  type TransportClient,
 } from "@checkstack/backend-api";
 import { QueueManager } from "@checkstack/queue-api";
 import {
@@ -237,7 +240,7 @@ async function executeHealthCheckJob(props: {
   const { configId, systemId } = payload;
 
   // Create service for aggregated state evaluation
-  const service = new HealthCheckService(db);
+  const service = new HealthCheckService(db, registry, collectorRegistry);
 
   // Capture aggregated state BEFORE this run for comparison
   const previousState = await service.getSystemHealthStatus(systemId);
@@ -305,24 +308,175 @@ async function executeHealthCheckJob(props: {
       return;
     }
 
-    // Execute health check using createClient pattern
+    // Extract timeout from strategy config for platform-level enforcement
+    const strategyConfig = configRow.config as unknown as BaseStrategyConfig;
+    const executionTimeout = strategyConfig.timeout ?? 60_000;
+
+    // Execute health check using createClient pattern with unified hard timeout
     const start = performance.now();
-    let connectedClient;
+    let connectionTimeMs: number | undefined;
+    let connectedClient:
+      | ConnectedClient<TransportClient<never, unknown>>
+      | undefined;
+    const collectors = configRow.collectors ?? [];
+    const collectorResults: Record<string, unknown> = {};
+    let hasCollectorError = false;
+    let errorMessage: string | undefined;
+
     try {
-      connectedClient = await strategy.createClient(
-        configRow.config as Record<string, unknown>,
-      );
+      // Platform-level hard timeout wrapping the entire execution sequence
+      await Promise.race([
+        (async () => {
+          // 1. Establish connection
+          connectedClient = await strategy.createClient(strategyConfig);
+          connectionTimeMs = Math.round(performance.now() - start);
+
+          // 2. Execute collectors in parallel
+          const collectorPromises = collectors.map(async (collectorEntry) => {
+            const registered = collectorRegistry.getCollector(
+              collectorEntry.collectorId,
+            );
+            if (!registered) {
+              logger.warn(
+                `Collector ${collectorEntry.collectorId} not found, skipping`,
+              );
+              return { storageKey: collectorEntry.id, skipped: true };
+            }
+
+            const storageKey = collectorEntry.id;
+
+            try {
+              const collectorResult = await registered.collector.execute({
+                config: collectorEntry.config,
+                client: connectedClient!.client,
+                pluginId: configRow.strategyId,
+              });
+
+              // Check for collector-level error
+              let collectorError: string | undefined;
+              if (collectorResult.error) {
+                collectorError = collectorResult.error;
+              }
+
+              // Evaluate per-collector assertions
+              let assertionFailed: string | undefined;
+              if (
+                collectorEntry.assertions &&
+                collectorEntry.assertions.length > 0 &&
+                collectorResult.result
+              ) {
+                const failedAssertion = evaluateAssertions(
+                  collectorEntry.assertions,
+                  collectorResult.result as Record<string, unknown>,
+                );
+                if (failedAssertion) {
+                  assertionFailed = `${failedAssertion.field} ${
+                    failedAssertion.operator
+                  } ${failedAssertion.value ?? ""}`;
+                  logger.debug(
+                    `Collector ${storageKey} assertion failed: ${assertionFailed}`,
+                  );
+                }
+              }
+
+              // Strip ephemeral fields before storage
+              const strippedResult = stripEphemeralFields(
+                collectorResult.result as Record<string, unknown>,
+                registered.collector.result.schema,
+              );
+
+              return {
+                storageKey,
+                skipped: false,
+                success: true,
+                collectorError,
+                assertionFailed,
+                result: {
+                  _collectorId: collectorEntry.collectorId,
+                  _assertionFailed: assertionFailed,
+                  ...strippedResult,
+                },
+              };
+            } catch (error) {
+              const errorStr =
+                error instanceof Error ? error.message : String(error);
+              logger.debug(`Collector ${storageKey} failed: ${errorStr}`);
+              return {
+                storageKey,
+                skipped: false,
+                success: false,
+                error: errorStr,
+                result: {
+                  _collectorId: collectorEntry.collectorId,
+                  _assertionFailed: undefined,
+                  error: errorStr,
+                },
+              };
+            }
+          });
+
+          // Wait for all collectors to complete
+          const settledResults = await Promise.allSettled(collectorPromises);
+
+          // Process results from all collectors
+          for (const settled of settledResults) {
+            if (settled.status === "rejected") {
+              // This shouldn't happen since we catch errors above, but handle it
+              hasCollectorError = true;
+              if (!errorMessage) errorMessage = String(settled.reason);
+              continue;
+            }
+
+            const result = settled.value;
+            if (result.skipped) continue;
+
+            // Store the result
+            collectorResults[result.storageKey] = result.result;
+
+            // Track errors
+            if (
+              !result.success ||
+              result.collectorError ||
+              result.assertionFailed
+            ) {
+              hasCollectorError = true;
+              if (!errorMessage) {
+                errorMessage =
+                  result.error ||
+                  result.collectorError ||
+                  (result.assertionFailed
+                    ? `Assertion failed: ${result.assertionFailed}`
+                    : undefined);
+              }
+            }
+          }
+        })(),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () =>
+              reject(
+                new Error(`Execution timeout after ${executionTimeout}ms`),
+              ),
+            executionTimeout,
+          ),
+        ),
+      ]);
     } catch (error) {
-      // Connection failed
       const latencyMs = Math.round(performance.now() - start);
-      const errorMessage =
-        error instanceof Error ? error.message : "Connection failed";
+      const caughtError =
+        error instanceof Error ? error.message : String(error);
+
+      // Use a specific error message if available, otherwise use the caught error
+      const finalError = errorMessage || caughtError;
 
       const result = {
         status: "unhealthy" as const,
         latencyMs,
-        message: errorMessage,
-        metadata: { connected: false, error: errorMessage },
+        message: finalError,
+        metadata: {
+          connected: !!connectedClient,
+          error: finalError,
+        },
       };
 
       await db.insert(healthCheckRuns).values({
@@ -333,7 +487,6 @@ async function executeHealthCheckJob(props: {
         result: { ...result } as Record<string, unknown>,
       });
 
-      // Trigger incremental hourly aggregation
       await incrementHourlyAggregate({
         db,
         systemId,
@@ -346,10 +499,9 @@ async function executeHealthCheckJob(props: {
       });
 
       logger.debug(
-        `Health check ${configId} for system ${systemId} failed: ${errorMessage}`,
+        `Health check ${configId} for system ${systemId} failed: ${finalError}`,
       );
 
-      // Broadcast failure signal
       await signalService.broadcast(HEALTH_CHECK_RUN_COMPLETED, {
         systemId,
         systemName,
@@ -359,7 +511,6 @@ async function executeHealthCheckJob(props: {
         latencyMs: result.latencyMs,
       });
 
-      // Check and notify state change
       const newState = await service.getSystemHealthStatus(systemId);
       if (newState.status !== previousStatus) {
         await notifyStateChange({
@@ -374,98 +525,14 @@ async function executeHealthCheckJob(props: {
       }
 
       return;
-    }
-
-    const connectionTimeMs = Math.round(performance.now() - start);
-
-    // Execute collectors
-    const collectors = configRow.collectors ?? [];
-    const collectorResults: Record<string, unknown> = {};
-    let hasCollectorError = false;
-    let errorMessage: string | undefined;
-
-    try {
-      for (const collectorEntry of collectors) {
-        const registered = collectorRegistry.getCollector(
-          collectorEntry.collectorId,
-        );
-        if (!registered) {
-          logger.warn(
-            `Collector ${collectorEntry.collectorId} not found, skipping`,
-          );
-          continue;
-        }
-
-        // Use the collector's UUID as the storage key
-        const storageKey = collectorEntry.id;
-
+    } finally {
+      if (connectedClient) {
         try {
-          const collectorResult = await registered.collector.execute({
-            config: collectorEntry.config,
-            client: connectedClient.client,
-            pluginId: configRow.strategyId,
-          });
-
-          // Check for collector-level error
-          if (collectorResult.error) {
-            hasCollectorError = true;
-            errorMessage = collectorResult.error;
-          }
-
-          // Evaluate per-collector assertions
-          let assertionFailed: string | undefined;
-          if (
-            collectorEntry.assertions &&
-            collectorEntry.assertions.length > 0 &&
-            collectorResult.result
-          ) {
-            const assertions = collectorEntry.assertions;
-            const failedAssertion = evaluateAssertions(
-              assertions,
-              collectorResult.result as Record<string, unknown>,
-            );
-            if (failedAssertion) {
-              hasCollectorError = true;
-              assertionFailed = `${failedAssertion.field} ${
-                failedAssertion.operator
-              } ${failedAssertion.value ?? ""}`;
-              errorMessage = `Assertion failed: ${assertionFailed}`;
-              logger.debug(
-                `Collector ${storageKey} assertion failed: ${errorMessage}`,
-              );
-            }
-          }
-
-          // Strip ephemeral fields (like HTTP body) before storage to save space
-          const strippedResult = stripEphemeralFields(
-            collectorResult.result as Record<string, unknown>,
-            registered.collector.result.schema,
-          );
-
-          // Store result under the collector's UUID, with collector type and assertion metadata
-          collectorResults[storageKey] = {
-            _collectorId: collectorEntry.collectorId, // Store the type for frontend schema linking
-            _assertionFailed: assertionFailed, // null if no assertion failed
-            ...strippedResult,
-          };
+          connectedClient.close();
         } catch (error) {
-          hasCollectorError = true;
-          errorMessage = error instanceof Error ? error.message : String(error);
-          collectorResults[storageKey] = {
-            _collectorId: collectorEntry.collectorId,
-            _assertionFailed: undefined,
-            error: errorMessage,
-          };
-          logger.debug(`Collector ${storageKey} failed: ${errorMessage}`);
+          logger.warn(`Failed to close connection: ${error}`);
         }
       }
-    } finally {
-      // Clean up connection
-      try {
-        connectedClient.close();
-      } catch {
-        // Ignore close errors
-      }
     }
 
     // Determine health status based on collector results

package/src/service-ordering.test.ts

@@ -120,7 +120,7 @@ describe("HealthCheckService data ordering", () => {
       mockRuns = [newRun, midRun, oldRun];
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getSystemHealthOverview("system-1");
 
@@ -155,7 +155,7 @@ describe("HealthCheckService data ordering", () => {
       }));
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getSystemHealthOverview("system-1");
 
@@ -188,7 +188,7 @@ describe("HealthCheckService data ordering", () => {
       ];
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getHistory({
         systemId: "sys-1",
@@ -223,7 +223,7 @@ describe("HealthCheckService data ordering", () => {
       ];
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getHistory({
         systemId: "sys-1",
@@ -259,7 +259,7 @@ describe("HealthCheckService data ordering", () => {
       ];
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getDetailedHistory({
         systemId: "sys-1",
@@ -296,7 +296,7 @@ describe("HealthCheckService data ordering", () => {
       ];
 
       const mockDb = createMockDb();
-      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+      service = new HealthCheckService(mockDb as never, mockRegistry as never, {} as never);
 
       const result = await service.getDetailedHistory({
         systemId: "sys-1",

package/src/service-pause.test.ts

@@ -15,7 +15,7 @@ describe("HealthCheckService - pause/resume", () => {
     mockSet = mock(() => ({ where: mockWhere }));
     mockUpdate = mock(() => ({ set: mockSet }));
     (mockDb.update as any) = mockUpdate;
-    service = new HealthCheckService(mockDb as any);
+    service = new HealthCheckService(mockDb as never, {} as never, {} as never);
   });
 
   describe("pauseConfiguration", () => {

package/src/service.ts

@@ -54,8 +54,8 @@ interface SystemHealthStatusResponse {
 export class HealthCheckService {
   constructor(
     private db: Db,
-    private registry?: HealthCheckRegistry,
-    private collectorRegistry?: CollectorRegistry,
+    private registry: HealthCheckRegistry,
+    private collectorRegistry: CollectorRegistry,
   ) {}
 
   async createConfiguration(
@@ -751,13 +751,18 @@ export class HealthCheckService {
       dailyBuckets,
     });
 
-    // Re-aggregate to target bucket interval
-    const targetBuckets = reaggregateBuckets({
-      sourceBuckets: mergedBuckets,
-      targetIntervalMs: bucketIntervalMs,
-      rangeStart: startDate,
-      rangeEnd: endDate,
-    });
+    // Re-aggregate to target bucket interval with automatic strategy and collector merging
+    const targetBuckets = config
+      ? reaggregateBuckets({
+          sourceBuckets: mergedBuckets,
+          targetIntervalMs: bucketIntervalMs,
+          rangeStart: startDate,
+          rangeEnd: endDate,
+          collectorRegistry: this.collectorRegistry,
+          registry: this.registry,
+          strategyId: config.strategyId,
+        })
+      : mergedBuckets;
 
     // Convert to output format
     const buckets = targetBuckets.map((bucket) => {