@checkstack/healthcheck-jenkins-backend 0.2.12 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/healthcheck-jenkins-backend
 
+## 0.3.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
+
+## 0.2.13
+
+### Patch Changes
+
+- 48c2080: Migrate aggregation from batch to incremental (`mergeResult`)
+
+  ### Breaking Changes (Internal)
+
+  - Replaced `aggregateResult(runs[])` with `mergeResult(existing, run)` interface across all HealthCheckStrategy and CollectorStrategy implementations
+
+  ### New Features
+
+  - Added incremental aggregation utilities in `@checkstack/backend-api`:
+    - `mergeCounter()` - track occurrences
+    - `mergeAverage()` - track sum/count, compute avg
+    - `mergeRate()` - track success/total, compute %
+    - `mergeMinMax()` - track min/max values
+  - Exported Zod schemas for internal state: `averageStateSchema`, `rateStateSchema`, `minMaxStateSchema`, `counterStateSchema`
+
+  ### Improvements
+
+  - Enables O(1) storage overhead by maintaining incremental aggregation state
+  - Prepares for real-time hourly aggregation without batch accumulation
+
+- Updated dependencies [f676e11]
+- Updated dependencies [48c2080]
+  - @checkstack/common@0.6.2
+  - @checkstack/backend-api@0.6.0
+  - @checkstack/healthcheck-common@0.8.2
+
 ## 0.2.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-jenkins-backend",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -10,14 +10,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.1",
-    "@checkstack/common": "0.6.0",
-    "@checkstack/healthcheck-common": "0.7.0"
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
-    "@checkstack/tsconfig": "0.0.2",
-    "@checkstack/scripts": "0.1.0"
+    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/scripts": "0.1.1"
   }
 }

package/src/collectors/build-history.test.ts

@@ -65,7 +65,7 @@ describe("BuildHistoryCollector", () => {
   });
 
   it("should aggregate correctly", () => {
-    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+    const runs: Parameters<typeof collector.mergeResult>[1][] = [
       {
         status: "healthy" as const,
         latencyMs: 100,
@@ -98,9 +98,10 @@ describe("BuildHistoryCollector", () => {
       },
     ];
 
-    const aggregated = collector.aggregateResult(runs);
+    let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-    expect(aggregated.avgSuccessRate).toBe(70);
-    expect(aggregated.avgBuildDuration).toBe(70000);
+    expect(aggregated.avgSuccessRate.avg).toBe(70);
+    expect(aggregated.avgBuildDuration.avg).toBe(70000);
   });
 });

package/src/collectors/build-history.ts

@@ -4,6 +4,10 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  VersionedAggregated,
+  aggregatedAverage,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import { pluginMetadata } from "../plugin-metadata";
@@ -86,21 +90,23 @@ const buildHistoryResultSchema = z.object({
 
 export type BuildHistoryResult = z.infer<typeof buildHistoryResultSchema>;
 
-const buildHistoryAggregatedSchema = z.object({
-  avgSuccessRate: healthResultNumber({
+// Aggregated result fields definition
+const buildHistoryAggregatedFields = {
+  avgSuccessRate: aggregatedAverage({
     "x-chart-type": "gauge",
     "x-chart-label": "Avg Success Rate",
     "x-chart-unit": "%",
   }),
-  avgBuildDuration: healthResultNumber({
+  avgBuildDuration: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Build Duration",
     "x-chart-unit": "ms",
   }),
-});
+};
 
-export type BuildHistoryAggregatedResult = z.infer<
-  typeof buildHistoryAggregatedSchema
+// Type inferred from field definitions
+export type BuildHistoryAggregatedResult = InferAggregatedResult<
+  typeof buildHistoryAggregatedFields
 >;
 
 // ============================================================================
@@ -111,15 +117,12 @@ export type BuildHistoryAggregatedResult = z.infer<
  * Collector for Jenkins build history.
  * Analyzes recent builds for trends and patterns.
  */
-export class BuildHistoryCollector
-  implements
-    CollectorStrategy<
-      JenkinsTransportClient,
-      BuildHistoryConfig,
-      BuildHistoryResult,
-      BuildHistoryAggregatedResult
-    >
-{
+export class BuildHistoryCollector implements CollectorStrategy<
+  JenkinsTransportClient,
+  BuildHistoryConfig,
+  BuildHistoryResult,
+  BuildHistoryAggregatedResult
+> {
   id = "build-history";
   displayName = "Build History";
   description = "Analyze recent build trends for a Jenkins job";
@@ -129,9 +132,9 @@ export class BuildHistoryCollector
 
   config = new Versioned({ version: 1, schema: buildHistoryConfigSchema });
   result = new Versioned({ version: 1, schema: buildHistoryResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: buildHistoryAggregatedSchema,
+    fields: buildHistoryAggregatedFields,
   });
 
   async execute({
@@ -253,28 +256,21 @@ export class BuildHistoryCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<BuildHistoryResult>[]
+  mergeResult(
+    existing: BuildHistoryAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<BuildHistoryResult>,
   ): BuildHistoryAggregatedResult {
-    const successRates = runs
-      .map((r) => r.metadata?.successRate)
-      .filter((v): v is number => typeof v === "number");
-
-    const durations = runs
-      .map((r) => r.metadata?.avgDurationMs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     return {
-      avgSuccessRate:
-        successRates.length > 0
-          ? Math.round(
-              successRates.reduce((a, b) => a + b, 0) / successRates.length
-            )
-          : 0,
-      avgBuildDuration:
-        durations.length > 0
-          ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
-          : 0,
+      avgSuccessRate: mergeAverage(
+        existing?.avgSuccessRate,
+        metadata?.successRate,
+      ),
+      avgBuildDuration: mergeAverage(
+        existing?.avgBuildDuration,
+        metadata?.avgDurationMs,
+      ),
     };
   }
 }

package/src/collectors/job-status.test.ts

@@ -9,7 +9,7 @@ describe("JobStatusCollector", () => {
   const collector = new JobStatusCollector();
 
   const createMockClient = (
-    response: JenkinsResponse
+    response: JenkinsResponse,
   ): JenkinsTransportClient => ({
     exec: async () => response,
   });
@@ -93,12 +93,12 @@ describe("JobStatusCollector", () => {
     });
 
     expect(capturedPath).toBe(
-      "/job/folder/job/subfolder/job/nested-job/api/json"
+      "/job/folder/job/subfolder/job/nested-job/api/json",
     );
   });
 
   it("should aggregate success rate correctly", () => {
-    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+    const runs: Parameters<typeof collector.mergeResult>[1][] = [
       {
         status: "healthy" as const,
         latencyMs: 100,
@@ -137,10 +137,12 @@ describe("JobStatusCollector", () => {
       },
     ];
 
-    const aggregated = collector.aggregateResult(runs);
+    let aggregated = collector.mergeResult(undefined, runs[0]);
+    aggregated = collector.mergeResult(aggregated, runs[1]);
+    aggregated = collector.mergeResult(aggregated, runs[2]);
 
-    expect(aggregated.successRate).toBe(67); // 2/3
-    expect(aggregated.avgBuildDurationMs).toBe(60000); // (60000+80000+40000)/3
-    expect(aggregated.buildableRate).toBe(100);
+    expect(aggregated.successRate.rate).toBe(67); // 2/3
+    expect(aggregated.avgBuildDurationMs.avg).toBe(60000); // (60000+80000+40000)/3
+    expect(aggregated.buildableRate.rate).toBe(100);
   });
 });

package/src/collectors/job-status.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeRate,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedRate,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -77,26 +83,28 @@ const jobStatusResultSchema = z.object({
 
 export type JobStatusResult = z.infer<typeof jobStatusResultSchema>;
 
-const jobStatusAggregatedSchema = z.object({
-  avgBuildDurationMs: healthResultNumber({
+// Aggregated result fields definition
+const jobStatusAggregatedFields = {
+  avgBuildDurationMs: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Build Duration",
     "x-chart-unit": "ms",
   }),
-  successRate: healthResultNumber({
+  successRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Success Rate",
     "x-chart-unit": "%",
   }),
-  buildableRate: healthResultNumber({
+  buildableRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Enabled Rate",
     "x-chart-unit": "%",
   }),
-});
+};
 
-export type JobStatusAggregatedResult = z.infer<
-  typeof jobStatusAggregatedSchema
+// Type inferred from field definitions
+export type JobStatusAggregatedResult = InferAggregatedResult<
+  typeof jobStatusAggregatedFields
 >;
 
 // ============================================================================
@@ -107,15 +115,12 @@ export type JobStatusAggregatedResult = z.infer<
  * Collector for Jenkins job status.
  * Monitors individual job health and last build information.
  */
-export class JobStatusCollector
-  implements
-    CollectorStrategy<
-      JenkinsTransportClient,
-      JobStatusConfig,
-      JobStatusResult,
-      JobStatusAggregatedResult
-    >
-{
+export class JobStatusCollector implements CollectorStrategy<
+  JenkinsTransportClient,
+  JobStatusConfig,
+  JobStatusResult,
+  JobStatusAggregatedResult
+> {
   id = "job-status";
   displayName = "Job Status";
   description = "Monitor Jenkins job status and last build information";
@@ -125,9 +130,9 @@ export class JobStatusCollector
 
   config = new Versioned({ version: 1, schema: jobStatusConfigSchema });
   result = new Versioned({ version: 1, schema: jobStatusResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: jobStatusAggregatedSchema,
+    fields: jobStatusAggregatedFields,
   });
 
   async execute({
@@ -205,37 +210,22 @@ export class JobStatusCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<JobStatusResult>[]
+  mergeResult(
+    existing: JobStatusAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<JobStatusResult>,
   ): JobStatusAggregatedResult {
-    const durations = runs
-      .map((r) => r.metadata?.lastBuildDurationMs)
-      .filter((v): v is number => typeof v === "number");
-
-    const results = runs
-      .map((r) => r.metadata?.lastBuildResult)
-      .filter((v): v is string => typeof v === "string");
-
-    const buildables = runs
-      .map((r) => r.metadata?.buildable)
-      .filter((v): v is boolean => typeof v === "boolean");
-
-    const successCount = results.filter((r) => r === "SUCCESS").length;
-    const buildableCount = buildables.filter(Boolean).length;
+    const metadata = run.metadata;
 
     return {
-      avgBuildDurationMs:
-        durations.length > 0
-          ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
-          : 0,
-      successRate:
-        results.length > 0
-          ? Math.round((successCount / results.length) * 100)
-          : 0,
-      buildableRate:
-        buildables.length > 0
-          ? Math.round((buildableCount / buildables.length) * 100)
-          : 0,
+      avgBuildDurationMs: mergeAverage(
+        existing?.avgBuildDurationMs,
+        metadata?.lastBuildDurationMs,
+      ),
+      successRate: mergeRate(
+        existing?.successRate,
+        metadata?.lastBuildResult === "SUCCESS",
+      ),
+      buildableRate: mergeRate(existing?.buildableRate, metadata?.buildable),
     };
   }
 }

package/src/collectors/node-health.test.ts

@@ -111,7 +111,7 @@ describe("NodeHealthCollector", () => {
   });
 
   it("should aggregate correctly", () => {
-    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+    const runs: Parameters<typeof collector.mergeResult>[1][] = [
       {
         status: "healthy" as const,
         latencyMs: 100,
@@ -140,10 +140,11 @@ describe("NodeHealthCollector", () => {
       },
     ];
 
-    const aggregated = collector.aggregateResult(runs);
+    let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-    expect(aggregated.avgOnlineNodes).toBe(4);
-    expect(aggregated.avgUtilization).toBe(60);
-    expect(aggregated.minOnlineNodes).toBe(3);
+    expect(aggregated.avgOnlineNodes.avg).toBe(4);
+    expect(aggregated.avgUtilization.avg).toBe(60);
+    expect(aggregated.minOnlineNodes.min).toBe(3);
   });
 });

package/src/collectors/node-health.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
@@ -77,24 +83,26 @@ const nodeHealthResultSchema = z.object({
 
 export type NodeHealthResult = z.infer<typeof nodeHealthResultSchema>;
 
-const nodeHealthAggregatedSchema = z.object({
-  avgOnlineNodes: healthResultNumber({
+// Aggregated result fields definition
+const nodeHealthAggregatedFields = {
+  avgOnlineNodes: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Online Nodes",
   }),
-  avgUtilization: healthResultNumber({
+  avgUtilization: aggregatedAverage({
     "x-chart-type": "gauge",
     "x-chart-label": "Avg Utilization",
     "x-chart-unit": "%",
   }),
-  minOnlineNodes: healthResultNumber({
+  minOnlineNodes: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Min Online Nodes",
   }),
-});
+};
 
-export type NodeHealthAggregatedResult = z.infer<
-  typeof nodeHealthAggregatedSchema
+// Type inferred from field definitions
+export type NodeHealthAggregatedResult = InferAggregatedResult<
+  typeof nodeHealthAggregatedFields
 >;
 
 // ============================================================================
@@ -105,15 +113,12 @@ export type NodeHealthAggregatedResult = z.infer<
  * Collector for Jenkins node/agent health.
  * Monitors node availability and executor utilization.
  */
-export class NodeHealthCollector
-  implements
-    CollectorStrategy<
-      JenkinsTransportClient,
-      NodeHealthConfig,
-      NodeHealthResult,
-      NodeHealthAggregatedResult
-    >
-{
+export class NodeHealthCollector implements CollectorStrategy<
+  JenkinsTransportClient,
+  NodeHealthConfig,
+  NodeHealthResult,
+  NodeHealthAggregatedResult
+> {
   id = "node-health";
   displayName = "Node Health";
   description = "Monitor Jenkins agent/node availability and executor usage";
@@ -123,9 +128,9 @@ export class NodeHealthCollector
 
   config = new Versioned({ version: 1, schema: nodeHealthConfigSchema });
   result = new Versioned({ version: 1, schema: nodeHealthResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: nodeHealthAggregatedSchema,
+    fields: nodeHealthAggregatedFields,
   });
 
   async execute({
@@ -147,7 +152,7 @@ export class NodeHealthCollector
 
   private async executeForSingleNode(
     nodeName: string,
-    client: JenkinsTransportClient
+    client: JenkinsTransportClient,
   ): Promise<CollectorResult<NodeHealthResult>> {
     const encodedName = encodeURIComponent(nodeName);
     const response = await client.exec({
@@ -209,7 +214,7 @@ export class NodeHealthCollector
   }
 
   private async executeForAllNodes(
-    client: JenkinsTransportClient
+    client: JenkinsTransportClient,
   ): Promise<CollectorResult<NodeHealthResult>> {
     const response = await client.exec({
       path: "/computer/api/json",
@@ -275,31 +280,25 @@ export class NodeHealthCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<NodeHealthResult>[]
+  mergeResult(
+    existing: NodeHealthAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<NodeHealthResult>,
   ): NodeHealthAggregatedResult {
-    const onlineNodes = runs
-      .map((r) => r.metadata?.onlineNodes)
-      .filter((v): v is number => typeof v === "number");
-
-    const utilizations = runs
-      .map((r) => r.metadata?.executorUtilization)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     return {
-      avgOnlineNodes:
-        onlineNodes.length > 0
-          ? Math.round(
-              onlineNodes.reduce((a, b) => a + b, 0) / onlineNodes.length
-            )
-          : 0,
-      avgUtilization:
-        utilizations.length > 0
-          ? Math.round(
-              utilizations.reduce((a, b) => a + b, 0) / utilizations.length
-            )
-          : 0,
-      minOnlineNodes: onlineNodes.length > 0 ? Math.min(...onlineNodes) : 0,
+      avgOnlineNodes: mergeAverage(
+        existing?.avgOnlineNodes,
+        metadata?.onlineNodes,
+      ),
+      avgUtilization: mergeAverage(
+        existing?.avgUtilization,
+        metadata?.executorUtilization,
+      ),
+      minOnlineNodes: mergeMinMax(
+        existing?.minOnlineNodes,
+        metadata?.onlineNodes,
+      ),
     };
   }
 }

package/src/collectors/queue-info.test.ts

@@ -77,7 +77,7 @@ describe("QueueInfoCollector", () => {
   });
 
   it("should aggregate correctly", () => {
-    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+    const runs: Parameters<typeof collector.mergeResult>[1][] = [
       {
         status: "healthy" as const,
         latencyMs: 100,
@@ -104,10 +104,11 @@ describe("QueueInfoCollector", () => {
       },
     ];
 
-    const aggregated = collector.aggregateResult(runs);
+    let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-    expect(aggregated.avgQueueLength).toBe(4);
-    expect(aggregated.maxQueueLength).toBe(5);
-    expect(aggregated.avgWaitTime).toBe(15000);
+    expect(aggregated.avgQueueLength.avg).toBe(4);
+    expect(aggregated.maxQueueLength.max).toBe(5);
+    expect(aggregated.avgWaitTime.avg).toBe(15000);
   });
 });

package/src/collectors/queue-info.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import { pluginMetadata } from "../plugin-metadata";
@@ -52,24 +58,26 @@ const queueInfoResultSchema = z.object({
 
 export type QueueInfoResult = z.infer<typeof queueInfoResultSchema>;
 
-const queueInfoAggregatedSchema = z.object({
-  avgQueueLength: healthResultNumber({
+// Aggregated result fields definition
+const queueInfoAggregatedFields = {
+  avgQueueLength: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Queue Length",
   }),
-  maxQueueLength: healthResultNumber({
+  maxQueueLength: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Queue Length",
   }),
-  avgWaitTime: healthResultNumber({
+  avgWaitTime: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Wait Time",
     "x-chart-unit": "ms",
   }),
-});
+};
 
-export type QueueInfoAggregatedResult = z.infer<
-  typeof queueInfoAggregatedSchema
+// Type inferred from field definitions
+export type QueueInfoAggregatedResult = InferAggregatedResult<
+  typeof queueInfoAggregatedFields
 >;
 
 // ============================================================================
@@ -80,15 +88,12 @@ export type QueueInfoAggregatedResult = z.infer<
  * Collector for Jenkins build queue.
  * Monitors queue length and wait times.
  */
-export class QueueInfoCollector
-  implements
-    CollectorStrategy<
-      JenkinsTransportClient,
-      QueueInfoConfig,
-      QueueInfoResult,
-      QueueInfoAggregatedResult
-    >
-{
+export class QueueInfoCollector implements CollectorStrategy<
+  JenkinsTransportClient,
+  QueueInfoConfig,
+  QueueInfoResult,
+  QueueInfoAggregatedResult
+> {
   id = "queue-info";
   displayName = "Queue Info";
   description = "Monitor Jenkins build queue length and wait times";
@@ -97,9 +102,9 @@ export class QueueInfoCollector
 
   config = new Versioned({ version: 1, schema: queueInfoConfigSchema });
   result = new Versioned({ version: 1, schema: queueInfoResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: queueInfoAggregatedSchema,
+    fields: queueInfoAggregatedFields,
   });
 
   async execute({
@@ -187,29 +192,22 @@ export class QueueInfoCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<QueueInfoResult>[]
+  mergeResult(
+    existing: QueueInfoAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<QueueInfoResult>,
   ): QueueInfoAggregatedResult {
-    const queueLengths = runs
-      .map((r) => r.metadata?.queueLength)
-      .filter((v): v is number => typeof v === "number");
-
-    const waitTimes = runs
-      .map((r) => r.metadata?.avgWaitingMs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     return {
-      avgQueueLength:
-        queueLengths.length > 0
-          ? Math.round(
-              queueLengths.reduce((a, b) => a + b, 0) / queueLengths.length
-            )
-          : 0,
-      maxQueueLength: queueLengths.length > 0 ? Math.max(...queueLengths) : 0,
-      avgWaitTime:
-        waitTimes.length > 0
-          ? Math.round(waitTimes.reduce((a, b) => a + b, 0) / waitTimes.length)
-          : 0,
+      avgQueueLength: mergeAverage(
+        existing?.avgQueueLength,
+        metadata?.queueLength,
+      ),
+      maxQueueLength: mergeMinMax(
+        existing?.maxQueueLength,
+        metadata?.queueLength,
+      ),
+      avgWaitTime: mergeAverage(existing?.avgWaitTime, metadata?.avgWaitingMs),
     };
   }
 }

package/src/collectors/server-info.test.ts

@@ -9,7 +9,7 @@ describe("ServerInfoCollector", () => {
   const collector = new ServerInfoCollector();
 
   const createMockClient = (
-    response: JenkinsResponse
+    response: JenkinsResponse,
   ): JenkinsTransportClient => ({
     exec: async () => response,
   });
@@ -57,7 +57,7 @@ describe("ServerInfoCollector", () => {
   });
 
   it("should aggregate results correctly", () => {
-    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+    const runs: Parameters<typeof collector.mergeResult>[1][] = [
       {
         status: "healthy" as const,
         latencyMs: 100,
@@ -82,9 +82,10 @@ describe("ServerInfoCollector", () => {
       },
     ];
 
-    const aggregated = collector.aggregateResult(runs);
+    let aggregated = collector.mergeResult(undefined, runs[0]);
+    aggregated = collector.mergeResult(aggregated, runs[1]);
 
-    expect(aggregated.avgExecutors).toBe(5);
-    expect(aggregated.avgTotalJobs).toBe(11);
+    expect(aggregated.avgExecutors.avg).toBe(5);
+    expect(aggregated.avgTotalJobs.avg).toBe(11);
   });
 });

package/src/collectors/server-info.ts

@@ -4,6 +4,10 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  VersionedAggregated,
+  aggregatedAverage,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -54,19 +58,21 @@ const serverInfoResultSchema = z.object({
 
 export type ServerInfoResult = z.infer<typeof serverInfoResultSchema>;
 
-const serverInfoAggregatedSchema = z.object({
-  avgExecutors: healthResultNumber({
+// Aggregated result fields definition
+const serverInfoAggregatedFields = {
+  avgExecutors: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Executors",
   }),
-  avgTotalJobs: healthResultNumber({
+  avgTotalJobs: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Jobs",
   }),
-});
+};
 
-export type ServerInfoAggregatedResult = z.infer<
-  typeof serverInfoAggregatedSchema
+// Type inferred from field definitions
+export type ServerInfoAggregatedResult = InferAggregatedResult<
+  typeof serverInfoAggregatedFields
 >;
 
 // ============================================================================
@@ -77,15 +83,12 @@ export type ServerInfoAggregatedResult = z.infer<
  * Built-in collector for Jenkins server information.
  * Fetches basic server health metrics via /api/json.
  */
-export class ServerInfoCollector
-  implements
-    CollectorStrategy<
-      JenkinsTransportClient,
-      ServerInfoConfig,
-      ServerInfoResult,
-      ServerInfoAggregatedResult
-    >
-{
+export class ServerInfoCollector implements CollectorStrategy<
+  JenkinsTransportClient,
+  ServerInfoConfig,
+  ServerInfoResult,
+  ServerInfoAggregatedResult
+> {
   id = "server-info";
   displayName = "Server Info";
   description = "Collects Jenkins server information and health metrics";
@@ -94,9 +97,9 @@ export class ServerInfoCollector
 
   config = new Versioned({ version: 1, schema: serverInfoConfigSchema });
   result = new Versioned({ version: 1, schema: serverInfoResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: serverInfoAggregatedSchema,
+    fields: serverInfoAggregatedFields,
   });
 
   async execute({
@@ -144,26 +147,18 @@ export class ServerInfoCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<ServerInfoResult>[]
+  mergeResult(
+    existing: ServerInfoAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<ServerInfoResult>,
   ): ServerInfoAggregatedResult {
-    const executors = runs
-      .map((r) => r.metadata?.numExecutors)
-      .filter((v): v is number => typeof v === "number");
-
-    const jobs = runs
-      .map((r) => r.metadata?.totalJobs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     return {
-      avgExecutors:
-        executors.length > 0
-          ? Math.round(executors.reduce((a, b) => a + b, 0) / executors.length)
-          : 0,
-      avgTotalJobs:
-        jobs.length > 0
-          ? Math.round(jobs.reduce((a, b) => a + b, 0) / jobs.length)
-          : 0,
+      avgExecutors: mergeAverage(
+        existing?.avgExecutors,
+        metadata?.numExecutors,
+      ),
+      avgTotalJobs: mergeAverage(existing?.avgTotalJobs, metadata?.totalJobs),
     };
   }
 }

package/src/strategy.test.ts

@@ -41,7 +41,7 @@ describe("JenkinsHealthCheckStrategy", () => {
           status: 200,
           statusText: "OK",
           headers: { "X-Jenkins": "2.426.1" },
-        })
+        }),
       );
 
       const connectedClient = await strategy.createClient({
@@ -66,7 +66,7 @@ describe("JenkinsHealthCheckStrategy", () => {
     it("should include query parameters in request", async () => {
       let capturedUrl = "";
       spyOn(globalThis, "fetch").mockImplementation((async (
-        url: RequestInfo | URL
+        url: RequestInfo | URL,
       ) => {
         capturedUrl = url.toString();
         return new Response(JSON.stringify({}), { status: 200 });
@@ -94,7 +94,7 @@ describe("JenkinsHealthCheckStrategy", () => {
       let capturedHeaders: Record<string, string> | undefined;
       spyOn(globalThis, "fetch").mockImplementation((async (
         _url: RequestInfo | URL,
-        options?: RequestInit
+        options?: RequestInit,
       ) => {
         capturedHeaders = options?.headers as Record<string, string>;
         return new Response(JSON.stringify({}), { status: 200 });
@@ -112,7 +112,7 @@ describe("JenkinsHealthCheckStrategy", () => {
       expect(capturedHeaders?.["Authorization"]).toContain("Basic ");
       const decoded = Buffer.from(
         capturedHeaders?.["Authorization"]?.replace("Basic ", "") || "",
-        "base64"
+        "base64",
       ).toString();
       expect(decoded).toBe("admin:api-token-123");
 
@@ -121,7 +121,7 @@ describe("JenkinsHealthCheckStrategy", () => {
 
     it("should return error for HTTP error response", async () => {
       spyOn(globalThis, "fetch").mockResolvedValue(
-        new Response(null, { status: 401, statusText: "Unauthorized" })
+        new Response(null, { status: 401, statusText: "Unauthorized" }),
       );
 
       const connectedClient = await strategy.createClient({
@@ -160,9 +160,9 @@ describe("JenkinsHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate success rate from runs", () => {
-      const runs: Parameters<typeof strategy.aggregateResult>[0] = [
+      const runs: Parameters<typeof strategy.mergeResult>[1][] = [
         {
           status: "healthy" as const,
           latencyMs: 100,
@@ -180,19 +180,26 @@ describe("JenkinsHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
+      aggregated = strategy.mergeResult(aggregated, runs[2]);
 
-      expect(aggregated.successRate).toBe(67); // 2/3
-      expect(aggregated.avgResponseTimeMs).toBe(175); // (150+200)/2
-      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.successRate.rate).toBe(67); // 2/3
+      expect(aggregated.avgResponseTimeMs.avg).toBe(175); // (150+200)/2
+      expect(aggregated.errorCount.count).toBe(1);
     });
 
-    it("should handle empty runs", () => {
-      const aggregated = strategy.aggregateResult([]);
-
-      expect(aggregated.successRate).toBe(0);
-      expect(aggregated.avgResponseTimeMs).toBe(0);
-      expect(aggregated.errorCount).toBe(0);
+    it("should handle single run", () => {
+      const run = {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: { connected: true, responseTimeMs: 150 },
+      };
+      const aggregated = strategy.mergeResult(undefined, run);
+
+      expect(aggregated.successRate.rate).toBe(100);
+      expect(aggregated.avgResponseTimeMs.avg).toBe(150);
+      expect(aggregated.errorCount.count).toBe(0);
     });
   });
 });

package/src/strategy.ts

@@ -2,10 +2,18 @@ import {
   HealthCheckStrategy,
   HealthCheckRunForAggregation,
   Versioned,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedRate,
+  aggregatedCounter,
+  mergeAverage,
+  mergeRate,
+  mergeCounter,
   z,
   configString,
   configNumber,
   type ConnectedClient,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -33,10 +41,10 @@ export const jenkinsConfigSchema = z.object({
     .url()
     .describe("Jenkins server URL (e.g., https://jenkins.example.com)"),
   username: configString({}).describe(
-    "Jenkins username for API authentication"
+    "Jenkins username for API authentication",
   ),
   apiToken: configString({ "x-secret": true }).describe(
-    "Jenkins API token (generate from User > Configure > API Token)"
+    "Jenkins API token (generate from User > Configure > API Token)",
   ),
   timeout: configNumber({})
     .int()
@@ -66,39 +74,38 @@ const jenkinsResultSchema = healthResultSchema({
 
 type JenkinsResult = z.infer<typeof jenkinsResultSchema>;
 
-/** Aggregated metadata for buckets */
-const jenkinsAggregatedSchema = healthResultSchema({
-  successRate: healthResultNumber({
+/** Aggregated field definitions for bucket merging */
+const jenkinsAggregatedFields = {
+  successRate: aggregatedRate({
     "x-chart-type": "gauge",
     "x-chart-label": "Success Rate",
     "x-chart-unit": "%",
   }),
-  avgResponseTimeMs: healthResultNumber({
+  avgResponseTimeMs: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Response Time",
     "x-chart-unit": "ms",
   }),
-  errorCount: healthResultNumber({
+  errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
   }),
-});
+};
 
-type JenkinsAggregatedResult = z.infer<typeof jenkinsAggregatedSchema>;
+type JenkinsAggregatedResult = InferAggregatedResult<
+  typeof jenkinsAggregatedFields
+>;
 
 // ============================================================================
 // STRATEGY
 // ============================================================================
 
-export class JenkinsHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      JenkinsConfig,
-      JenkinsTransportClient,
-      JenkinsResult,
-      JenkinsAggregatedResult
-    >
-{
+export class JenkinsHealthCheckStrategy implements HealthCheckStrategy<
+  JenkinsConfig,
+  JenkinsTransportClient,
+  JenkinsResult,
+  typeof jenkinsAggregatedFields
+> {
   id = "jenkins";
   displayName = "Jenkins Health Check";
   description = "Monitor Jenkins CI/CD server health and job status";
@@ -113,23 +120,23 @@ export class JenkinsHealthCheckStrategy
     schema: jenkinsResultSchema,
   });
 
-  aggregatedResult: Versioned<JenkinsAggregatedResult> = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: jenkinsAggregatedSchema,
+    fields: jenkinsAggregatedFields,
   });
 
   /**
    * Create a Jenkins transport client for API requests.
    */
   async createClient(
-    config: JenkinsConfig
+    config: JenkinsConfig,
   ): Promise<ConnectedClient<JenkinsTransportClient>> {
     const validatedConfig = this.config.validate(config);
     const baseUrl = validatedConfig.baseUrl.replace(/\/$/, ""); // Remove trailing slash
 
     // Create Basic Auth header
     const authHeader = `Basic ${Buffer.from(
-      `${validatedConfig.username}:${validatedConfig.apiToken}`
+      `${validatedConfig.username}:${validatedConfig.apiToken}`,
     ).toString("base64")}`;
 
     const client: JenkinsTransportClient = {
@@ -144,7 +151,7 @@ export class JenkinsHealthCheckStrategy
         const controller = new AbortController();
         const timeoutId = setTimeout(
           () => controller.abort(),
-          validatedConfig.timeout
+          validatedConfig.timeout,
         );
 
         try {
@@ -200,31 +207,23 @@ export class JenkinsHealthCheckStrategy
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<JenkinsResult>[]
+  mergeResult(
+    existing: JenkinsAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<JenkinsResult>,
   ): JenkinsAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
+    const metadata = run.metadata;
 
-    if (validRuns.length === 0) {
-      return { successRate: 0, avgResponseTimeMs: 0, errorCount: 0 };
-    }
+    const avgResponseTimeMs = mergeAverage(
+      existing?.avgResponseTimeMs,
+      metadata?.responseTimeMs,
+    );
 
-    const responseTimes = validRuns
-      .map((r) => r.metadata?.responseTimeMs)
-      .filter((t): t is number => typeof t === "number");
+    const isSuccess = metadata?.connected ?? false;
+    const successRate = mergeRate(existing?.successRate, isSuccess);
 
-    const successCount = validRuns.filter((r) => r.metadata?.connected).length;
-    const errorCount = validRuns.filter((r) => r.metadata?.error).length;
+    const hasError = metadata?.error !== undefined;
+    const errorCount = mergeCounter(existing?.errorCount, hasError);
 
-    return {
-      successRate: Math.round((successCount / validRuns.length) * 100),
-      avgResponseTimeMs:
-        responseTimes.length > 0
-          ? Math.round(
-              responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length
-            )
-          : 0,
-      errorCount,
-    };
+    return { successRate, avgResponseTimeMs, errorCount };
   }
 }