@checkstack/healthcheck-backend 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @checkstack/healthcheck-backend
 
+## 0.7.0
+
+### Minor Changes
+
+- 1f81b60: ### Clickable Run History with Deep Linking
+
+  **Backend (`healthcheck-backend`):**
+
+  - Added `getRunById` service method to fetch a single health check run by ID
+
+  **Schema (`healthcheck-common`):**
+
+  - Added `getRunById` RPC procedure for fetching individual runs
+  - Added `historyRun` route for deep linking to specific runs (`/history/:systemId/:configurationId/:runId`)
+
+  **Frontend (`healthcheck-frontend`):**
+
+  - Table rows in Recent Runs and Run History now navigate to detailed view instead of expanding inline
+  - Added "Selected Run" card that displays when navigating to a specific run
+  - Extracted `ExpandedResultView` into reusable component
+  - Fixed layout shift during table pagination by preserving previous data while loading
+  - Removed accordion expansion in favor of consistent navigation UX
+
+### Patch Changes
+
+- 090143b: ### Health Check Aggregation & UI Fixes
+
+  **Backend (`healthcheck-backend`):**
+
+  - Fixed tail-end bucket truncation where the last aggregated bucket was cut off at the interval boundary instead of extending to the query end date
+  - Added `rangeEnd` parameter to `reaggregateBuckets()` to properly extend the last bucket
+  - Fixed cross-tier merge logic (`mergeTieredBuckets`) to prevent hourly aggregates from blocking fresh raw data
+
+  **Schema (`healthcheck-common`):**
+
+  - Added `bucketEnd` field to `AggregatedBucketBaseSchema` so frontends know the actual end time of each bucket
+
+  **Frontend (`healthcheck-frontend`):**
+
+  - Updated all components to use `bucket.bucketEnd` instead of calculating from `bucketIntervalSeconds`
+  - Fixed aggregation mode detection: changed `>` to `>=` so 7-day queries use aggregated data when `rawRetentionDays` is 7
+  - Added ref-based memoization in `useHealthCheckData` to prevent layout shift during signal-triggered refetches
+  - Exposed `isFetching` state to show loading spinner during background refetches
+  - Added debounced custom date range with Apply button to prevent fetching on every field change
+  - Added validation preventing start date >= end date in custom ranges
+  - Added sparkline downsampling: when there are 60+ data points, they are aggregated into buckets with informative tooltips
+
+  **UI (`ui`):**
+
+  - Fixed `DateRangeFilter` presets to use true sliding windows (removed `startOfDay` from 7-day and 30-day ranges)
+  - Added `disabled` prop to `DateRangeFilter` and `DateTimePicker` components
+  - Added `onCustomChange` prop to `DateRangeFilter` for debounced custom date handling
+  - Improved layout: custom date pickers now inline with preset buttons on desktop
+  - Added responsive mobile layout: date pickers stack vertically with down arrow
+  - Added validation error display for invalid date ranges
+
+- Updated dependencies [1f81b60]
+- Updated dependencies [090143b]
+  - @checkstack/healthcheck-common@0.7.0
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/aggregation-utils.test.ts

@@ -342,6 +342,66 @@ describe("aggregation-utils", () => {
       expect(result[1].sourceTier).toBe("hourly");
       expect(result[2].sourceTier).toBe("raw");
     });
+
+    it("raw buckets take precedence even when hourly starts earlier (regression test)", () => {
+      /**
+       * Regression test for the "Tail-End Stale" bug:
+       * When an hourly aggregate (e.g., 21:00-22:00) exists and raw data
+       * arrives mid-hour (e.g., 21:48), the raw data should take precedence,
+       * not be blocked by the hourly aggregate.
+       *
+       * Bug scenario:
+       * - Hourly aggregate: 21:00 to 22:00
+       * - Raw buckets: 21:48 to 22:11 (fresh data)
+       * - Old buggy behavior: hourly was processed first (earlier start time),
+       *   set coveredUntil=22:00, and raw was skipped
+       * - Correct behavior: raw always takes precedence, hourly is excluded
+       */
+      const baseTime = 21 * HOUR; // 21:00
+
+      // Hourly bucket covering 21:00-22:00 (stale aggregate)
+      const hourlyBuckets = [
+        createBucket({
+          startMs: baseTime,
+          durationMs: HOUR,
+          runCount: 60, // Old stale data
+          sourceTier: "hourly",
+        }),
+      ];
+
+      // Raw buckets at 21:48 and 22:00 (fresh data that should NOT be blocked)
+      const rawBuckets = [
+        createBucket({
+          startMs: baseTime + 48 * MINUTE, // 21:48
+          durationMs: 12 * MINUTE,
+          runCount: 12, // Fresh data
+          sourceTier: "raw",
+        }),
+        createBucket({
+          startMs: baseTime + HOUR, // 22:00
+          durationMs: 11 * MINUTE,
+          runCount: 11, // Fresh data
+          sourceTier: "raw",
+        }),
+      ];
+
+      const result = mergeTieredBuckets({
+        rawBuckets,
+        hourlyBuckets,
+        dailyBuckets: [],
+      });
+
+      // CRITICAL: Both raw buckets should be included
+      expect(result).toHaveLength(2);
+      expect(result[0].sourceTier).toBe("raw");
+      expect(result[1].sourceTier).toBe("raw");
+      expect(result[0].runCount).toBe(12); // 21:48 bucket
+      expect(result[1].runCount).toBe(11); // 22:00 bucket
+
+      // Hourly bucket should be excluded because raw data covers its range
+      const hourlyInResult = result.find((b) => b.sourceTier === "hourly");
+      expect(hourlyInResult).toBeUndefined();
+    });
   });
 
   describe("combineBuckets", () => {
@@ -520,6 +580,7 @@ describe("aggregation-utils", () => {
         sourceBuckets: [],
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
+        rangeEnd: new Date(HOUR),
       });
 
       expect(result).toEqual([]);
@@ -552,6 +613,7 @@ describe("aggregation-utils", () => {
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
+        rangeEnd: new Date(HOUR),
       });
 
       expect(result).toHaveLength(1);
@@ -585,6 +647,7 @@ describe("aggregation-utils", () => {
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
+        rangeEnd: new Date(2 * HOUR),
       });
 
       expect(result).toHaveLength(2);
@@ -611,6 +674,7 @@ describe("aggregation-utils", () => {
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart,
+        rangeEnd: new Date(rangeStart.getTime() + HOUR),
       });
 
       expect(result).toHaveLength(1);
@@ -633,6 +697,7 @@ describe("aggregation-utils", () => {
         sourceBuckets,
         targetIntervalMs: HOUR,
         rangeStart: new Date(0),
+        rangeEnd: new Date(3 * HOUR),
       });
 
       expect(result).toHaveLength(3);

package/src/aggregation-utils.ts

@@ -193,6 +193,10 @@ const TIER_PRIORITY: Record<NormalizedBucket["sourceTier"], number> = {
 /**
  * Merge buckets from different tiers, preferring most granular data.
  * For overlapping time periods, uses priority: raw > hourly > daily.
+ *
+ * IMPORTANT: Raw buckets always take precedence over hourly/daily aggregates,
+ * even when the aggregate bucket starts earlier. This ensures fresh raw data
+ * is never blocked by stale pre-computed aggregates.
  */
 export function mergeTieredBuckets(params: {
   rawBuckets: NormalizedBucket[];
@@ -201,42 +205,108 @@ export function mergeTieredBuckets(params: {
 }): NormalizedBucket[] {
   const { rawBuckets, hourlyBuckets, dailyBuckets } = params;
 
-  // Combine all buckets
-  const allBuckets = [...rawBuckets, ...hourlyBuckets, ...dailyBuckets];
-
-  if (allBuckets.length === 0) {
+  if (
+    rawBuckets.length === 0 &&
+    hourlyBuckets.length === 0 &&
+    dailyBuckets.length === 0
+  ) {
     return [];
   }
 
-  // Sort by start time, then by tier priority (most granular first)
-  allBuckets.sort((a, b) => {
-    const timeDiff = a.bucketStart.getTime() - b.bucketStart.getTime();
-    if (timeDiff !== 0) return timeDiff;
-    return TIER_PRIORITY[a.sourceTier] - TIER_PRIORITY[b.sourceTier];
-  });
+  // Two-pass approach:
+  // 1. First, collect all time ranges covered by raw data (highest priority)
+  // 2. Then, add hourly/daily buckets only for gaps not covered by raw data
+
+  // Build a sorted list of raw bucket time ranges for efficient lookup
+  const rawTimeRanges = rawBuckets
+    .map((b) => ({
+      start: b.bucketStart.getTime(),
+      end: b.bucketEndMs,
+    }))
+    .toSorted((a, b) => a.start - b.start);
+
+  // Merge overlapping raw time ranges into continuous coverage
+  const rawCoverage: Array<{ start: number; end: number }> = [];
+  for (const range of rawTimeRanges) {
+    if (rawCoverage.length === 0) {
+      rawCoverage.push({ ...range });
+    } else {
+      const last = rawCoverage.at(-1)!;
+      // If this range overlaps or is adjacent to the last, extend it
+      if (range.start <= last.end) {
+        last.end = Math.max(last.end, range.end);
+      } else {
+        rawCoverage.push({ ...range });
+      }
+    }
+  }
 
-  // Merge overlapping buckets, keeping the most granular tier
-  const result: NormalizedBucket[] = [];
-  let coveredUntil = 0; // Timestamp up to which we have data
-
-  for (const bucket of allBuckets) {
-    const bucketStartMs = bucket.bucketStart.getTime();
-
-    // Skip if this bucket's time range is already covered by higher-priority data
-    if (bucketStartMs < coveredUntil) {
-      // Check if this bucket extends beyond current coverage
-      if (bucket.bucketEndMs > coveredUntil) {
-        // Partial overlap - for simplicity, we skip partially overlapping lower-priority buckets
-        // This is acceptable because we prefer raw data which is more granular
-        continue;
+  // Helper: check if a bucket has ANY overlap with raw data
+  // Two ranges overlap if: start1 < end2 AND start2 < end1
+  const doesBucketOverlapWithRaw = (bucket: NormalizedBucket): boolean => {
+    const bucketStart = bucket.bucketStart.getTime();
+    const bucketEnd = bucket.bucketEndMs;
+
+    for (const range of rawCoverage) {
+      // Check for overlap: ranges overlap if they intersect
+      if (bucketStart < range.end && range.start < bucketEnd) {
+        return true;
+      }
+      // Optimization: if raw range starts after bucket ends, no more overlaps possible
+      if (range.start >= bucketEnd) {
+        break;
       }
-      continue;
     }
+    return false;
+  };
 
-    result.push(bucket);
-    coveredUntil = bucket.bucketEndMs;
+  // Start with all raw buckets (they always take precedence)
+  const result: NormalizedBucket[] = [...rawBuckets];
+
+  // Add hourly buckets that don't overlap with raw data
+  for (const bucket of hourlyBuckets) {
+    if (!doesBucketOverlapWithRaw(bucket)) {
+      result.push(bucket);
+    }
   }
 
+  // Add daily buckets that don't overlap with raw or hourly data
+  // Build hourly coverage to check against
+  const hourlyTimeRanges = hourlyBuckets
+    .map((b) => ({
+      start: b.bucketStart.getTime(),
+      end: b.bucketEndMs,
+    }))
+    .toSorted((a, b) => a.start - b.start);
+
+  // Helper: check if a bucket has ANY overlap with hourly data
+  const doesBucketOverlapWithHourly = (bucket: NormalizedBucket): boolean => {
+    const bucketStart = bucket.bucketStart.getTime();
+    const bucketEnd = bucket.bucketEndMs;
+
+    for (const range of hourlyTimeRanges) {
+      if (bucketStart < range.end && range.start < bucketEnd) {
+        return true;
+      }
+      if (range.start >= bucketEnd) {
+        break;
+      }
+    }
+    return false;
+  };
+
+  for (const bucket of dailyBuckets) {
+    if (
+      !doesBucketOverlapWithRaw(bucket) &&
+      !doesBucketOverlapWithHourly(bucket)
+    ) {
+      result.push(bucket);
+    }
+  }
+
+  // Sort final result by bucket start time
+  result.sort((a, b) => a.bucketStart.getTime() - b.bucketStart.getTime());
+
   return result;
 }
 
@@ -349,19 +419,24 @@ 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.
+ *
+ * @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.
  */
 export function reaggregateBuckets(params: {
   sourceBuckets: NormalizedBucket[];
   targetIntervalMs: number;
   rangeStart: Date;
+  rangeEnd: Date;
 }): NormalizedBucket[] {
-  const { sourceBuckets, targetIntervalMs, rangeStart } = params;
+  const { sourceBuckets, targetIntervalMs, rangeStart, rangeEnd } = params;
 
   if (sourceBuckets.length === 0) {
     return [];
   }
 
   const rangeStartMs = rangeStart.getTime();
+  const rangeEndMs = rangeEnd.getTime();
 
   // Group source buckets by target bucket index
   const bucketGroups = new Map<number, NormalizedBucket[]>();
@@ -379,9 +454,16 @@ export function reaggregateBuckets(params: {
   // Combine each group into a single target bucket
   const result: NormalizedBucket[] = [];
 
+  // Find the maximum bucket index to identify the last bucket
+  const maxIndex = Math.max(...bucketGroups.keys());
+
   for (const [index, buckets] of bucketGroups) {
     const targetBucketStart = new Date(rangeStartMs + index * targetIntervalMs);
-    const targetBucketEndMs = targetBucketStart.getTime() + targetIntervalMs;
+    const intervalEndMs = targetBucketStart.getTime() + targetIntervalMs;
+
+    // For the last bucket, extend to rangeEnd to capture all trailing data
+    const targetBucketEndMs =
+      index === maxIndex ? Math.max(intervalEndMs, rangeEndMs) : intervalEndMs;
 
     result.push(
       combineBuckets({

package/src/aggregation.test.ts

@@ -476,4 +476,386 @@ describe("HealthCheckService.getAggregatedHistory", () => {
       expect(collectorData.successRate).toBe(100);
     });
   });
+
+  describe("recent runs near endDate - edge case for live data", () => {
+    /**
+     * This test suite verifies that runs occurring close to the query endDate
+     * are properly included in the last bucket. This is critical for real-time
+     * dashboards where users expect to see data up to "now".
+     *
+     * Scenario: User queries "Last 7 days" and runs have been occurring every minute.
+     * The last bucket should include runs up to the endDate, not stop at a previous
+     * bucket boundary.
+     */
+
+    it("includes runs right up to endDate in the last bucket", async () => {
+      // Simulate a 7-day query range that creates ~23 minute buckets
+      // 7 days = 604,800 seconds / 500 target points = 1,209.6 seconds (~20 min) per bucket
+      const endDate = new Date("2026-01-20T22:05:00Z"); // Current time
+      const startDate = new Date("2026-01-13T22:05:00Z"); // 7 days ago
+
+      // Create runs: some old ones and some very recent ones near endDate
+      const runs = [
+        // Old run at the start of the range
+        {
+          id: "run-old-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: { statusCode: 200 },
+          timestamp: new Date("2026-01-13T22:10:00Z"),
+        },
+        // Run ~25 minutes before endDate
+        {
+          id: "run-recent-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 2500,
+          result: { statusCode: 500 },
+          timestamp: new Date("2026-01-20T21:40:00Z"),
+        },
+        // Run ~15 minutes before endDate
+        {
+          id: "run-recent-2",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 3000,
+          result: { statusCode: 503 },
+          timestamp: new Date("2026-01-20T21:50:00Z"),
+        },
+        // Run ~5 minutes before endDate
+        {
+          id: "run-recent-3",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 2800,
+          result: { statusCode: 502 },
+          timestamp: new Date("2026-01-20T22:00:00Z"),
+        },
+        // Run 2 minutes before endDate - SHOULD BE IN LAST BUCKET
+        {
+          id: "run-recent-4",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 2600,
+          result: { statusCode: 500 },
+          timestamp: new Date("2026-01-20T22:03:00Z"),
+        },
+        // Run 1 minute before endDate - SHOULD BE IN LAST BUCKET
+        {
+          id: "run-recent-5",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 2700,
+          result: { statusCode: 500 },
+          timestamp: new Date("2026-01-20T22:04:00Z"),
+        },
+      ];
+
+      mockRunsResult = runs;
+      mockConfigResult = { id: "config-1", strategyId: "http" };
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          targetPoints: 500,
+        },
+        { includeAggregatedResult: true },
+      );
+
+      // We should have buckets that cover the entire range
+      expect(result.buckets.length).toBeGreaterThan(0);
+
+      // Find the last bucket
+      const lastBucket = result.buckets[result.buckets.length - 1];
+
+      // The last bucket should contain runs from the most recent times
+      // Specifically, the runs at 22:03 and 22:04 should be in some bucket
+      const allRunCounts = result.buckets.reduce(
+        (sum, b) => sum + b.runCount,
+        0,
+      );
+      expect(allRunCounts).toBe(6); // All 6 runs should be accounted for
+
+      // The last bucket's bucketStart + interval should cover endDate
+      const bucketIntervalMs = result.bucketIntervalSeconds * 1000;
+      const lastBucketEnd = new Date(
+        lastBucket.bucketStart.getTime() + bucketIntervalMs,
+      );
+
+      // Last bucket should extend close to endDate
+      // (within one bucket interval of endDate)
+      expect(lastBucketEnd.getTime()).toBeGreaterThanOrEqual(
+        endDate.getTime() - bucketIntervalMs,
+      );
+    });
+
+    it("includes partial last bucket when endDate is mid-bucket", async () => {
+      // Scenario: Query ends at a time that's not aligned to bucket boundaries
+      // Runs exist right before endDate and should still appear
+      const startDate = new Date("2026-01-20T21:00:00Z");
+      const endDate = new Date("2026-01-20T22:00:00Z"); // 1 hour range
+
+      // Create runs every 5 minutes for the hour
+      const runs = [];
+      for (let i = 0; i < 12; i++) {
+        runs.push({
+          id: `run-${i}`,
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "healthy" as const,
+          latencyMs: 100 + i * 10,
+          result: { statusCode: 200 },
+          timestamp: new Date(
+            startDate.getTime() + i * 5 * 60 * 1000, // Every 5 minutes
+          ),
+        });
+      }
+
+      mockRunsResult = runs;
+      mockConfigResult = { id: "config-1", strategyId: "http" };
+
+      // Use 10 target points = 6 minute buckets
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          targetPoints: 10,
+        },
+        { includeAggregatedResult: true },
+      );
+
+      // All 12 runs should be accounted for in the buckets
+      const allRunCounts = result.buckets.reduce(
+        (sum, b) => sum + b.runCount,
+        0,
+      );
+      expect(allRunCounts).toBe(12);
+
+      // Last bucket should exist and have runs in it
+      const lastBucket = result.buckets[result.buckets.length - 1];
+      expect(lastBucket.runCount).toBeGreaterThan(0);
+
+      // The run at 21:55 (55 minutes after start) should be in a bucket
+      // That's in bucket index floor(55/6) = 9 (the last bucket)
+      expect(result.buckets.length).toBe(10);
+    });
+
+    it("handles runs at exact endDate boundary", async () => {
+      const startDate = new Date("2026-01-20T21:00:00Z");
+      const endDate = new Date("2026-01-20T22:00:00Z");
+
+      const runs = [
+        {
+          id: "run-start",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: { statusCode: 200 },
+          timestamp: new Date("2026-01-20T21:00:00Z"), // Exact start
+        },
+        {
+          id: "run-end",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 5000,
+          result: { statusCode: 500 },
+          timestamp: new Date("2026-01-20T22:00:00Z"), // Exact end
+        },
+      ];
+
+      mockRunsResult = runs;
+      mockConfigResult = { id: "config-1", strategyId: "http" };
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          targetPoints: 10,
+        },
+        { includeAggregatedResult: true },
+      );
+
+      // Both runs should be included
+      const allRunCounts = result.buckets.reduce(
+        (sum, b) => sum + b.runCount,
+        0,
+      );
+      expect(allRunCounts).toBe(2);
+
+      // First bucket should have the start run
+      expect(result.buckets[0].runCount).toBeGreaterThan(0);
+
+      // Last bucket should have the end run
+      const lastBucket = result.buckets[result.buckets.length - 1];
+      expect(lastBucket.runCount).toBeGreaterThan(0);
+    });
+
+    it("simulates real-world 7-day dashboard with minute-by-minute runs", async () => {
+      /**
+       * Real-world simulation:
+       * - 7 day query range
+       * - Health check runs every minute
+       * - Query with 500 target points (~20 min buckets)
+       * - Recent runs should appear in the latest bucket
+       */
+      const endDate = new Date("2026-01-20T22:05:00Z");
+      const startDate = new Date("2026-01-13T22:05:00Z");
+
+      // Create runs for the last 30 minutes (simulates recent activity)
+      const runs = [];
+      for (let i = 0; i < 30; i++) {
+        const timestamp = new Date(endDate.getTime() - (30 - i) * 60 * 1000);
+        runs.push({
+          id: `run-${i}`,
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: i % 3 === 0 ? ("unhealthy" as const) : ("healthy" as const),
+          latencyMs: 100 + i * 10,
+          result: { statusCode: i % 3 === 0 ? 500 : 200 },
+          timestamp,
+        });
+      }
+
+      mockRunsResult = runs;
+      mockConfigResult = { id: "config-1", strategyId: "http" };
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          targetPoints: 500,
+        },
+        { includeAggregatedResult: true },
+      );
+
+      // Verify bucket interval is roughly 20 minutes for 7-day / 500 points
+      // 7 days = 604,800 seconds / 500 = 1,209.6 seconds (~20 min)
+      expect(result.bucketIntervalSeconds).toBe(1210);
+
+      // All 30 runs should be in buckets
+      const allRunCounts = result.buckets.reduce(
+        (sum, b) => sum + b.runCount,
+        0,
+      );
+      expect(allRunCounts).toBe(30);
+
+      // The most recent run (at endDate - 1 minute) should be in a bucket
+      // This is the critical assertion for the bug we're fixing
+      const lastBucket = result.buckets[result.buckets.length - 1];
+
+      // Last bucket should have some runs
+      expect(lastBucket.runCount).toBeGreaterThan(0);
+
+      // The last bucket's end time should be near endDate
+      const bucketIntervalMs = result.bucketIntervalSeconds * 1000;
+      const lastBucketEnd = new Date(
+        lastBucket.bucketStart.getTime() + bucketIntervalMs,
+      );
+
+      // Last bucket should extend to cover the endDate or be within one interval
+      const timeDiffMs = endDate.getTime() - lastBucketEnd.getTime();
+      expect(timeDiffMs).toBeLessThan(bucketIntervalMs);
+    });
+
+    it("verifies last bucket contains the most recent timestamp", async () => {
+      const startDate = new Date("2026-01-20T21:00:00Z");
+      const endDate = new Date("2026-01-20T22:05:00Z"); // 65 minutes
+
+      // Create runs with known timestamps
+      const runs = [
+        {
+          id: "run-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: {},
+          timestamp: new Date("2026-01-20T21:05:00Z"),
+        },
+        {
+          id: "run-2",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: {},
+          timestamp: new Date("2026-01-20T21:35:00Z"),
+        },
+        // Most recent run - 2 minutes before endDate
+        {
+          id: "run-latest",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          strategyId: "http",
+          status: "unhealthy" as const,
+          latencyMs: 5000,
+          result: { statusCode: 500 },
+          timestamp: new Date("2026-01-20T22:03:00Z"),
+        },
+      ];
+
+      mockRunsResult = runs;
+      mockConfigResult = { id: "config-1", strategyId: "http" };
+
+      // Use 5 target points = 13 minute buckets
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          targetPoints: 5,
+        },
+        { includeAggregatedResult: true },
+      );
+
+      expect(result.buckets.length).toBeGreaterThan(0);
+
+      // All 3 runs should be included
+      const allRunCounts = result.buckets.reduce(
+        (sum, b) => sum + b.runCount,
+        0,
+      );
+      expect(allRunCounts).toBe(3);
+
+      // The last bucket should have the unhealthy run
+      const lastBucket = result.buckets[result.buckets.length - 1];
+      expect(lastBucket.unhealthyCount).toBe(1);
+
+      // Bucket containing 22:03 run should have bucketStart before 22:03
+      expect(lastBucket.bucketStart.getTime()).toBeLessThanOrEqual(
+        new Date("2026-01-20T22:03:00Z").getTime(),
+      );
+    });
+  });
 });

package/src/router.ts

@@ -178,6 +178,10 @@ export const createHealthCheckRouter = (
       return service.getDetailedHistory(input);
     }),
 
+    getRunById: os.getRunById.handler(async ({ input }) => {
+      return service.getRunById(input);
+    }),
+
     getAggregatedHistory: os.getAggregatedHistory.handler(async ({ input }) => {
       return service.getAggregatedHistory(input, {
         includeAggregatedResult: false,

package/src/service-ordering.test.ts

@@ -0,0 +1,316 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import type { InferSelectModel } from "drizzle-orm";
+import { HealthCheckService } from "./service";
+import {
+  healthCheckRuns,
+  systemHealthChecks,
+  healthCheckConfigurations,
+} from "./schema";
+
+/**
+ * Tests for correct data ordering in service methods.
+ * Verifies the Parametric Sort-at-Source standard:
+ * - getSystemHealthOverview returns runs in chronological order (oldest first) for sparklines
+ * - getHistory and getDetailedHistory respect the sortOrder parameter
+ */
+describe("HealthCheckService data ordering", () => {
+  let mockRegistry: ReturnType<typeof createMockRegistry>;
+  let service: HealthCheckService;
+
+  // Use real types from schema to catch schema drift
+  type HealthCheckRun = InferSelectModel<typeof healthCheckRuns>;
+  type SystemHealthCheck = InferSelectModel<typeof systemHealthChecks>;
+  type HealthCheckConfiguration = InferSelectModel<
+    typeof healthCheckConfigurations
+  >;
+
+  // Mock data storage - using Partial to allow minimal test data
+  type MockAssociation = Pick<
+    SystemHealthCheck,
+    "configurationId" | "enabled" | "stateThresholds"
+  > &
+    Pick<HealthCheckConfiguration, "strategyId" | "intervalSeconds"> & {
+      configName: string;
+    };
+  let mockAssociations: MockAssociation[] = [];
+  let mockRuns: Partial<HealthCheckRun>[] = [];
+
+  function createMockRegistry() {
+    return {
+      register: mock(),
+      getStrategies: mock(() => []),
+      getStrategy: mock(() => null),
+    };
+  }
+
+  function createMockDb() {
+    // Create a comprehensive mock that handles all query patterns
+    // The service uses different patterns:
+    // - getHistory/getDetailedHistory: .orderBy().limit().offset()
+    // - getSystemHealthOverview: .orderBy().limit() (no offset)
+    const offsetMock = mock(() => Promise.resolve([...mockRuns]));
+
+    // limitMock needs to be both a thenable (for await) and have .offset()
+    const createLimitResult = () => {
+      const result = Promise.resolve([...mockRuns]);
+      // @ts-expect-error - Adding offset to Promise
+      result.offset = offsetMock;
+      return result;
+    };
+
+    const orderByMock = mock(() => ({
+      limit: mock(createLimitResult),
+    }));
+    const whereMock = mock(() => ({
+      orderBy: orderByMock,
+      limit: mock(createLimitResult),
+    }));
+    const innerJoinMock = mock(() => ({
+      where: mock(() => Promise.resolve([...mockAssociations])),
+    }));
+    const fromMock = mock(() => ({
+      where: whereMock,
+      innerJoin: innerJoinMock,
+      orderBy: orderByMock,
+    }));
+
+    return {
+      select: mock(() => ({ from: fromMock })),
+      $count: mock(() => Promise.resolve(mockRuns.length)),
+    };
+  }
+
+  beforeEach(() => {
+    mockAssociations = [];
+    mockRuns = [];
+    mockRegistry = createMockRegistry();
+  });
+
+  describe("getSystemHealthOverview", () => {
+    it("returns recentRuns in chronological order (oldest first) for sparkline display", async () => {
+      // Setup: Runs that would be returned from DB in DESC order (newest first)
+      const oldRun = {
+        id: "run-old",
+        status: "healthy" as const,
+        timestamp: new Date("2024-01-01T10:00:00Z"),
+      };
+      const midRun = {
+        id: "run-mid",
+        status: "degraded" as const,
+        timestamp: new Date("2024-01-01T11:00:00Z"),
+      };
+      const newRun = {
+        id: "run-new",
+        status: "unhealthy" as const,
+        timestamp: new Date("2024-01-01T12:00:00Z"),
+      };
+
+      mockAssociations = [
+        {
+          configurationId: "config-1",
+          configName: "Test Config",
+          strategyId: "http",
+          intervalSeconds: 60,
+          enabled: true,
+          stateThresholds: null,
+        },
+      ];
+
+      // DB returns DESC order (newest first) - service should reverse for sparkline
+      mockRuns = [newRun, midRun, oldRun];
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getSystemHealthOverview("system-1");
+
+      // Verify recentRuns are in chronological order (oldest first)
+      // This is what sparklines expect: oldest on left, newest on right
+      expect(result.checks).toHaveLength(1);
+      expect(result.checks[0].recentRuns).toHaveLength(3);
+      expect(result.checks[0].recentRuns[0].id).toBe("run-old"); // Oldest first
+      expect(result.checks[0].recentRuns[1].id).toBe("run-mid");
+      expect(result.checks[0].recentRuns[2].id).toBe("run-new"); // Newest last
+    });
+
+    it("returns most recent 25 runs in chronological order", async () => {
+      mockAssociations = [
+        {
+          configurationId: "config-1",
+          configName: "Test Config",
+          strategyId: "http",
+          intervalSeconds: 60,
+          enabled: true,
+          stateThresholds: null,
+        },
+      ];
+
+      // Create 25 runs in DESC order (how DB returns them)
+      mockRuns = Array.from({ length: 25 }, (_, i) => ({
+        id: `run-${24 - i}`, // 24 down to 0 (newest to oldest)
+        status: "healthy" as const,
+        timestamp: new Date(
+          `2024-01-01T${String(24 - i).padStart(2, "0")}:00:00Z`,
+        ),
+      }));
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getSystemHealthOverview("system-1");
+
+      // After service reverses: oldest (run-0) should be first, newest (run-24) last
+      expect(result.checks[0].recentRuns).toHaveLength(25);
+      expect(result.checks[0].recentRuns[0].id).toBe("run-0"); // Oldest first
+      expect(result.checks[0].recentRuns[24].id).toBe("run-24"); // Newest last
+    });
+  });
+
+  describe("getHistory sortOrder parameter", () => {
+    it("respects sortOrder asc - returns runs in chronological order", async () => {
+      // Simulate DB returning runs in ASC order
+      mockRuns = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T11:00:00Z"),
+        },
+        {
+          id: "3",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T12:00:00Z"),
+        },
+      ];
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getHistory({
+        systemId: "sys-1",
+        configurationId: "config-1",
+        sortOrder: "asc",
+        limit: 10,
+      });
+
+      // Verify runs are returned as-is from mock (ASC order)
+      expect(result.runs[0].id).toBe("1"); // Oldest first
+      expect(result.runs[2].id).toBe("3"); // Newest last
+    });
+
+    it("respects sortOrder desc - returns runs in reverse chronological order", async () => {
+      // Simulate DB returning runs in DESC order
+      mockRuns = [
+        {
+          id: "3",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T12:00:00Z"),
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T11:00:00Z"),
+        },
+        {
+          id: "1",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+        },
+      ];
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getHistory({
+        systemId: "sys-1",
+        configurationId: "config-1",
+        sortOrder: "desc",
+        limit: 10,
+      });
+
+      // Verify runs are returned as-is from mock (DESC order)
+      expect(result.runs[0].id).toBe("3"); // Newest first
+      expect(result.runs[2].id).toBe("1"); // Oldest last
+    });
+  });
+
+  describe("getDetailedHistory sortOrder parameter", () => {
+    it("respects sortOrder asc - returns runs in chronological order", async () => {
+      // Simulate DB returning runs in ASC order
+      mockRuns = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+          latencyMs: 100,
+          result: {},
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T11:00:00Z"),
+          latencyMs: 150,
+          result: {},
+        },
+      ];
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getDetailedHistory({
+        systemId: "sys-1",
+        configurationId: "config-1",
+        startDate: new Date("2024-01-01T00:00:00Z"),
+        endDate: new Date("2024-01-02T00:00:00Z"),
+        sortOrder: "asc",
+        limit: 10,
+        offset: 0,
+      });
+
+      // Verify runs are returned in ASC order
+      expect(result.runs[0].id).toBe("1"); // Oldest first
+      expect(result.runs[1].id).toBe("2"); // Newest last
+    });
+
+    it("respects sortOrder desc - returns runs in reverse chronological order", async () => {
+      // Simulate DB returning runs in DESC order
+      mockRuns = [
+        {
+          id: "2",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T11:00:00Z"),
+          latencyMs: 150,
+          result: {},
+        },
+        {
+          id: "1",
+          status: "healthy" as const,
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+          latencyMs: 100,
+          result: {},
+        },
+      ];
+
+      const mockDb = createMockDb();
+      service = new HealthCheckService(mockDb as never, mockRegistry as never);
+
+      const result = await service.getDetailedHistory({
+        systemId: "sys-1",
+        configurationId: "config-1",
+        startDate: new Date("2024-01-01T00:00:00Z"),
+        endDate: new Date("2024-01-02T00:00:00Z"),
+        sortOrder: "desc",
+        limit: 10,
+        offset: 0,
+      });
+
+      // Verify runs are returned in DESC order
+      expect(result.runs[0].id).toBe("2"); // Newest first
+      expect(result.runs[1].id).toBe("1"); // Oldest last
+    });
+  });
+});

package/src/service.ts

@@ -414,7 +414,7 @@ export class HealthCheckService {
     const sparklineLimit = 25;
 
     for (const assoc of associations) {
-      // Get last 25 runs for sparkline
+      // Get last 25 runs for sparkline (newest first, then reverse for chronological display)
       const runs = await this.db
         .select({
           id: healthCheckRuns.id,
@@ -431,15 +431,18 @@ export class HealthCheckService {
         .orderBy(desc(healthCheckRuns.timestamp))
         .limit(sparklineLimit);
 
+      // Reverse to chronological order (oldest first) for sparkline display
+      const chronologicalRuns = runs.toReversed();
+
       // Migrate and extract thresholds
       let thresholds: StateThresholds | undefined;
       if (assoc.stateThresholds) {
         thresholds = await stateThresholds.parse(assoc.stateThresholds);
       }
 
-      // Evaluate current status
+      // Evaluate current status (runs are in DESC order - newest first - as evaluateHealthStatus expects)
       const status = evaluateHealthStatus({
-        runs: runs as Array<{ status: HealthCheckStatus; timestamp: Date }>,
+        runs,
         thresholds,
       });
 
@@ -451,7 +454,7 @@ export class HealthCheckService {
         enabled: assoc.enabled,
         status,
         stateThresholds: thresholds,
-        recentRuns: runs.map((r) => ({
+        recentRuns: chronologicalRuns.map((r) => ({
           id: r.id,
           status: r.status,
           timestamp: r.timestamp,
@@ -464,6 +467,7 @@ export class HealthCheckService {
 
   /**
    * Get paginated health check run history (public - no result data).
+   * @param sortOrder - 'asc' for chronological (oldest first), 'desc' for reverse (newest first)
    */
   async getHistory(props: {
     systemId?: string;
@@ -472,6 +476,7 @@ export class HealthCheckService {
     endDate?: Date;
     limit?: number;
     offset?: number;
+    sortOrder: "asc" | "desc";
   }) {
     const {
       systemId,
@@ -480,6 +485,7 @@ export class HealthCheckService {
       endDate,
       limit = 10,
       offset = 0,
+      sortOrder,
     } = props;
 
     const conditions = [];
@@ -495,16 +501,17 @@ export class HealthCheckService {
     // Get total count using drizzle $count
     const total = await this.db.$count(healthCheckRuns, whereClause);
 
-    // Get paginated runs
+    // Get paginated runs with requested sort order
     let query = this.db.select().from(healthCheckRuns);
     if (whereClause) {
       // @ts-expect-error drizzle-orm type mismatch
       query = query.where(whereClause);
     }
-    const runs = await query
-      .orderBy(desc(healthCheckRuns.timestamp))
-      .limit(limit)
-      .offset(offset);
+    const orderColumn =
+      sortOrder === "desc"
+        ? desc(healthCheckRuns.timestamp)
+        : healthCheckRuns.timestamp;
+    const runs = await query.orderBy(orderColumn).limit(limit).offset(offset);
 
     // Return without result field for public access (latencyMs is public data)
     return {
@@ -523,6 +530,7 @@ export class HealthCheckService {
   /**
    * Get detailed health check run history with full result data.
    * Restricted to users with manage access.
+   * @param sortOrder - 'asc' for chronological (oldest first), 'desc' for reverse (newest first)
    */
   async getDetailedHistory(props: {
     systemId?: string;
@@ -531,6 +539,7 @@ export class HealthCheckService {
     endDate?: Date;
     limit?: number;
     offset?: number;
+    sortOrder: "asc" | "desc";
   }) {
     const {
       systemId,
@@ -539,6 +548,7 @@ export class HealthCheckService {
       endDate,
       limit = 10,
       offset = 0,
+      sortOrder,
     } = props;
 
     const conditions = [];
@@ -556,10 +566,11 @@ export class HealthCheckService {
       // @ts-expect-error drizzle-orm type mismatch
       query = query.where(whereClause);
     }
-    const runs = await query
-      .orderBy(desc(healthCheckRuns.timestamp))
-      .limit(limit)
-      .offset(offset);
+    const orderColumn =
+      sortOrder === "desc"
+        ? desc(healthCheckRuns.timestamp)
+        : healthCheckRuns.timestamp;
+    const runs = await query.orderBy(orderColumn).limit(limit).offset(offset);
 
     // Return with full result data for manage access
     return {
@@ -576,6 +587,32 @@ export class HealthCheckService {
     };
   }
 
+  /**
+   * Get a single health check run by its ID.
+   */
+  async getRunById(props: { runId: string }) {
+    const run = await this.db
+      .select()
+      .from(healthCheckRuns)
+      .where(eq(healthCheckRuns.id, props.runId))
+      .limit(1);
+
+    if (run.length === 0) {
+      return;
+    }
+
+    const r = run[0];
+    return {
+      id: r.id,
+      configurationId: r.configurationId,
+      systemId: r.systemId,
+      status: r.status,
+      result: r.result ?? {},
+      timestamp: r.timestamp,
+      latencyMs: r.latencyMs ?? undefined,
+    };
+  }
+
   /**
    * Get aggregated health check history with dynamically-sized buckets.
    * Queries all three tiers (raw, hourly, daily) and merges with priority.
@@ -718,6 +755,7 @@ export class HealthCheckService {
       sourceBuckets: mergedBuckets,
       targetIntervalMs: bucketIntervalMs,
       rangeStart: startDate,
+      rangeEnd: endDate,
     });
 
     // Convert to output format
@@ -731,6 +769,7 @@ export class HealthCheckService {
 
       const baseBucket = {
         bucketStart: bucket.bucketStart,
+        bucketEnd: new Date(bucket.bucketEndMs),
         bucketIntervalSeconds,
         runCount: bucket.runCount,
         healthyCount: bucket.healthyCount,