@oneuptime/common 11.5.4 → 11.5.5

package/Types/AI/AIInsightEvidence.ts

@@ -0,0 +1,77 @@
+import {
+  PerformanceCodeLocation,
+  PerformanceFinding,
+} from "./CodeFixTaskContext";
+
+/*
+ * The JSON persisted on AIInsight.evidence.
+ *
+ * Evidence is computed DETERMINISTICALLY at detect time and stored verbatim
+ * because ClickHouse retention is short — the stored evidence must outlive
+ * the raw signals it was computed from (the FixPerformance taskContext
+ * precedent: by the time anyone looks, the spans/logs may already be gone).
+ * It is rendered in the dashboard and embedded in triage prompts, so every
+ * field must carry the real numbers and stand on its own.
+ *
+ * Exactly one of the per-type sections is set, matching the insight's
+ * AIInsightType. These shapes are a wire contract — do not rename
+ * fields.
+ */
+
+// Evidence for NewException and ExceptionSpike insights.
+export interface ExceptionInsightEvidence {
+  exceptionMessage?: string | undefined;
+  exceptionType?: string | undefined;
+  // Occurrences in the recent (spike) window.
+  recentOccurrenceCount?: number | undefined;
+  // Average hourly occurrences over the prior baseline window.
+  baselineHourlyAverage?: number | undefined;
+  // recent rate / baseline rate.
+  spikeMultiplier?: number | undefined;
+  // Lifetime occurrence count of the exception.
+  totalOccurrenceCount?: number | undefined;
+  // ISO-8601 — when the exception was first ever seen.
+  firstSeenAt?: string | undefined;
+}
+
+// Evidence for ErrorLogSpike insights.
+export interface LogSpikeInsightEvidence {
+  recentErrorCount: number;
+  baselineHourlyAverage: number;
+  spikeMultiplier: number;
+  windowMinutes: number;
+  topServices: Array<{ serviceName: string; count: number }>;
+}
+
+// Evidence for TraceLatencyRegression insights.
+export interface LatencyInsightEvidence {
+  recentP99Ms: number;
+  baselineP99Ms: number;
+  regressionMultiplier: number;
+  operationName?: string | undefined;
+  sampleTraceId?: string | undefined;
+  // Deterministic span-tree findings drilled from the sample trace.
+  performanceFindings?: Array<PerformanceFinding> | undefined;
+  // code.* attribute locations for stack-trace-style repo resolution.
+  codeLocations?: Array<PerformanceCodeLocation> | undefined;
+}
+
+// Evidence for MetricDrift insights (week-over-week mean comparison).
+export interface MetricDriftInsightEvidence {
+  metricName: string;
+  primaryEntityId?: string | undefined;
+  recentWeekMean: number;
+  priorWeekMean: number;
+  relativeChangePercent: number;
+  recentSampleCount: number;
+  priorSampleCount: number;
+}
+
+export interface AIInsightEvidence {
+  exception?: ExceptionInsightEvidence | undefined;
+  logSpike?: LogSpikeInsightEvidence | undefined;
+  latency?: LatencyInsightEvidence | undefined;
+  metricDrift?: MetricDriftInsightEvidence | undefined;
+}
+
+export default AIInsightEvidence;

package/Types/AI/AIInsightHumanVerdict.ts

@@ -0,0 +1,15 @@
+/*
+ * The one-click human verdict on a AIInsight. This IS the G11
+ * precision measurement: confirm/dismiss rates per insight type tell us how
+ * precise each deterministic detector is in the field. Stored on
+ * AIInsight.humanVerdict, so these strings are a wire contract — do
+ * not rename them.
+ */
+enum AIInsightHumanVerdict {
+  // A human confirmed the insight was real and worth surfacing.
+  Confirmed = "Confirmed",
+  // A human dismissed the insight as noise/not actionable.
+  Dismissed = "Dismissed",
+}
+
+export default AIInsightHumanVerdict;

package/Types/AI/AIInsightSeverity.ts

@@ -0,0 +1,13 @@
+/*
+ * How urgent a AIInsight is, assigned deterministically by the
+ * detector that produced it (e.g. by spike/regression multiplier). Stored
+ * on AIInsight.severity and rendered/filtered in the dashboard, so
+ * these strings are a wire contract — do not rename them.
+ */
+enum AIInsightSeverity {
+  High = "High",
+  Medium = "Medium",
+  Low = "Low",
+}
+
+export default AIInsightSeverity;

package/Types/AI/AIInsightStatus.ts

@@ -0,0 +1,38 @@
+/*
+ * Lifecycle of a AIInsight. Stored on AIInsight.status and
+ * filtered on in the dashboard, so these strings are a wire contract — do
+ * not rename them.
+ *
+ * Detected is the defensive initial state — the scanner routes every newly
+ * created insight to ActionRequired or FixOpened in the same tick, so a row
+ * only stays Detected if routing crashed mid-scan. Resolved and Dismissed
+ * are human actions (the terminal states).
+ */
+enum AIInsightStatus {
+  // Just created by a detector; routed onward in the same scanner tick.
+  Detected = "Detected",
+  // Waiting on a human: no automatic fix was opened for this insight.
+  ActionRequired = "ActionRequired",
+  // An AI fix task was queued for this insight (see fixAiRunId).
+  FixOpened = "FixOpened",
+  // A human marked the insight as handled. Terminal.
+  Resolved = "Resolved",
+  // A human dismissed the insight as noise/not actionable. Terminal.
+  Dismissed = "Dismissed",
+}
+
+export default AIInsightStatus;
+
+export class AIInsightStatusHelper {
+  /*
+   * Terminal = Resolved | Dismissed — the two human end states. The scanner
+   * only refreshes (dedupes into) NON-terminal insights; a terminal insight
+   * is never reopened by a detector.
+   */
+  public static isTerminalStatus(status: AIInsightStatus): boolean {
+    return (
+      status === AIInsightStatus.Resolved ||
+      status === AIInsightStatus.Dismissed
+    );
+  }
+}

package/Types/AI/AIInsightType.ts

@@ -0,0 +1,41 @@
+/*
+ * Which deterministic AI detector produced an insight. Detectors are
+ * statistical sensors over the project's telemetry — no LLM is involved in
+ * detection. These strings are stored on AIInsight.insightType and
+ * rendered/filtered in the dashboard, so they are a wire contract — do not
+ * rename them.
+ */
+enum AIInsightType {
+  /*
+   * A telemetry exception first seen within the last 24 hours that is
+   * already recurring (not resolved, not archived) — a brand-new failure
+   * mode in the code.
+   */
+  NewException = "NewException",
+  /*
+   * An established telemetry exception whose recent hourly occurrence rate
+   * spiked well above its own 24-hour baseline (including dormant
+   * exceptions suddenly waking up).
+   */
+  ExceptionSpike = "ExceptionSpike",
+  /*
+   * The project's Error/Fatal log volume in the last hour spiked well above
+   * its average hourly rate over the prior 24 hours, attributed to the top
+   * contributing services.
+   */
+  ErrorLogSpike = "ErrorLogSpike",
+  /*
+   * A service's recent p99 span latency regressed to a multiple of its own
+   * 24-hour baseline, with span-tree findings drilled from a representative
+   * slow trace.
+   */
+  TraceLatencyRegression = "TraceLatencyRegression",
+  /*
+   * A metric's mean over the last 7 days drifted substantially from its
+   * mean over the prior 7 days (week-over-week comparison per metric name
+   * and entity).
+   */
+  MetricDrift = "MetricDrift",
+}
+
+export default AIInsightType;

package/Types/AI/AIRunAutoGrade.ts

@@ -0,0 +1,18 @@
+/*
+ * The automatic grade assigned to a completed AI investigation when its
+ * incident resolves with a human-recorded root cause (Phase 2 measurement
+ * layer): one constrained LLM call compares the investigation's posted
+ * analysis with Incident.rootCause and stores the verdict on the run
+ * (AIRun.autoGrade). See
+ * Common/Server/Utils/AI/SRE/InvestigationGrader.ts.
+ */
+enum AIRunAutoGrade {
+  // The analysis identified the same root cause the humans recorded.
+  Match = "Match",
+  // Part of the cause, or a closely related cause.
+  Partial = "Partial",
+  // The analysis pointed somewhere else.
+  Mismatch = "Mismatch",
+}
+
+export default AIRunAutoGrade;

package/Types/AI/AIRunEventType.ts

@@ -10,6 +10,11 @@ enum AIRunEventType {
   // A mutating action the user approved was executed (or denied and skipped).
   ActionExecuted = "ActionExecuted",
   ActionDenied = "ActionDenied",
+  /*
+   * A plain progress/log line reported by an external executor (e.g. the
+   * code-fix agent container). The message lives in resultSummary.message.
+   */
+  ProgressLog = "ProgressLog",
   RunCompleted = "RunCompleted",
   RunFailed = "RunFailed",
 }

package/Types/AI/AIRunHumanVerdict.ts

@@ -0,0 +1,17 @@
+/*
+ * The one-click human verdict on a completed AI investigation's posted
+ * analysis (Phase 2 measurement layer). Captured via
+ * POST /ai-investigation/verdict from the investigation panel and stored on
+ * the run (AIRun.humanVerdict).
+ *
+ * The roadmap's "confirmed/edited/rejected" trichotomy is deliberately a
+ * two-button UI: "edited" is not something a human declares up front — it is
+ * detected later by the grading side (comparing the analysis with the final
+ * recorded root cause), so the human control stays a binary confirm/reject.
+ */
+enum AIRunHumanVerdict {
+  Confirmed = "Confirmed",
+  Rejected = "Rejected",
+}
+
+export default AIRunHumanVerdict;

package/Types/AI/AIRunType.ts

@@ -1,6 +1,12 @@
 enum AIRunType {
   Chat = "Chat",
   Investigation = "Investigation",
+  /*
+   * An exception-fix run executed by an external AI agent container: it
+   * claims the run over HTTP, works in the project's code repository and
+   * opens a pull request. Replaces the legacy AIAgentTask substrate.
+   */
+  CodeFix = "CodeFix",
 }
 
 export default AIRunType;

package/Types/AI/CodeFixTaskContext.ts

@@ -0,0 +1,88 @@
+/*
+ * The JSON persisted on AIRun.taskContext for CodeFix recipes whose entire
+ * working context is captured at trigger time rather than referenced by a
+ * subject id (incident/alert) or a telemetry exception.
+ *
+ * First user: the FixPerformance recipe. Its evidence is computed
+ * DETERMINISTICALLY from a trace's span tree when the user clicks "Fix
+ * performance with AI" (see Common/Server/Utils/AI/PerfEvidence/
+ * SpanTreeAnalyzer.ts) and stored here verbatim — ClickHouse span retention
+ * is short, so by the time the agent worker claims the run the spans may
+ * already be gone. The stored findings ARE the task's context.
+ *
+ * These shapes are a wire contract with the agent worker
+ * (/ai-agent-data/get-instrumentation-task-details serves them back) — do
+ * not rename fields.
+ */
+
+export enum PerformanceFindingType {
+  // >=5 near-identical sibling spans under one parent (classic N+1).
+  NPlusOneQuery = "NPlusOneQuery",
+  // A single span whose self time is >=60% of the trace's total duration.
+  DominantSpan = "DominantSpan",
+  /*
+   * >=3 same-name siblings executing strictly one-after-another whose
+   * combined duration is >=50% of their parent — parallelizable work.
+   */
+  SequentialSiblings = "SequentialSiblings",
+}
+
+// One span a finding implicates — enough to name it in evidence and PRs.
+export interface ImplicatedSpan {
+  spanId: string;
+  name: string;
+  durationMs: number;
+}
+
+/*
+ * One deterministic performance finding. `evidence` is the human-readable
+ * proof (real counts, durations, normalized names/statements) — it is
+ * embedded verbatim in the agent prompt and the pull request body, so it
+ * must stand on its own.
+ */
+export interface PerformanceFinding {
+  findingType: PerformanceFindingType;
+  // One-line summary, e.g. 'N+1: 27× "SELECT users" under "GET /orders"'.
+  headline: string;
+  // Multi-line human-readable proof with the real numbers.
+  evidence: string;
+  spanCount: number;
+  combinedDurationMs: number;
+  traceDurationMs: number;
+  percentOfTrace: number;
+  // Only for SequentialSiblings: combined duration as a share of the parent.
+  percentOfParent?: number | undefined;
+  normalizedSpanName: string;
+  parentSpanName?: string | undefined;
+  // Normalized db.statement when the implicated spans carry one.
+  normalizedDbStatement?: string | undefined;
+  dbSystem?: string | undefined;
+  httpUrl?: string | undefined;
+  // Capped sample of the implicated spans (name + duration).
+  implicatedSpans: Array<ImplicatedSpan>;
+}
+
+/*
+ * A code location plucked from the implicated spans' code.* attributes
+ * (code.filepath / code.function / code.lineno and their newer semconv
+ * spellings). Feeds the stack-trace-style repository resolution at
+ * task-details time.
+ */
+export interface PerformanceCodeLocation {
+  filePath: string;
+  functionName?: string | undefined;
+  lineNumber?: number | undefined;
+}
+
+export interface CodeFixTaskContext {
+  // FixPerformance: the analyzed trace.
+  traceId?: string | undefined;
+  // Best-effort service attribution resolved from the trace's spans.
+  serviceName?: string | undefined;
+  // The deterministic span-tree findings — the recipe's entire evidence.
+  performanceFindings?: Array<PerformanceFinding> | undefined;
+  // code.* attribute locations for stack-trace-style repo resolution.
+  codeLocations?: Array<PerformanceCodeLocation> | undefined;
+}
+
+export default CodeFixTaskContext;

package/Types/AI/CodeFixTaskType.ts

@@ -0,0 +1,132 @@
+/*
+ * Which task recipe a CodeFix AIRun executes. The agent worker dispatches on
+ * this value (returned as `taskType` by /ai-agent-task/get-pending-task), so
+ * these strings are a wire contract — do not rename them.
+ *
+ * A null AIRun.codeFixTaskType column means FixException: every CodeFix run
+ * created before the column existed was an exception fix. Server responses
+ * normalize null to FixException so clients never see the legacy null.
+ */
+enum CodeFixTaskType {
+  // Analyze an exception's stack trace and open a PR that fixes the bug.
+  FixException = "FixException",
+  // Write a failing-then-passing regression test that reproduces the exception.
+  WriteRegressionTest = "WriteRegressionTest",
+  /*
+   * Add the observability an INCONCLUSIVE AI investigation was missing
+   * (structured logs, spans, metric counters on the implicated code paths).
+   * NOT user-triggerable from the exception page — it has its own automatic
+   * trigger: an inconclusive investigation on a project that opted in via
+   * Project.enableInstrumentationFixTasks (see Common/Server/Utils/AI/
+   * AI/InstrumentationTaskTrigger.ts). Its subject is the triggering
+   * incident/alert, NOT a telemetry exception.
+   */
+  ImproveInstrumentation = "ImproveInstrumentation",
+  /*
+   * Fix a deterministically-detected performance pattern in a trace (N+1
+   * queries, one dominant slow span, sequential-that-could-be-parallel
+   * siblings). Human-triggered from the trace view (POST /ai-investigation/
+   * create-performance-fix-task), NOT from the exception page: it has no
+   * subject row at all — its entire context (the SpanTreeAnalyzer findings)
+   * is captured at trigger time into AIRun.taskContext (see
+   * Common/Server/Utils/AI/SRE/FixPerformanceTaskTrigger.ts).
+   */
+  FixPerformance = "FixPerformance",
+  /*
+   * Fix the root cause a completed AI investigation identified. Human-
+   * triggered from the investigation panel (POST /ai-investigation/
+   * create-fix-task), NOT from the exception page: its subject is the
+   * investigated incident/alert, and its context is the posted analysis (see
+   * Common/Server/Utils/AI/SRE/FixFromIncidentTaskTrigger.ts).
+   */
+  FixFromIncident = "FixFromIncident",
+}
+
+export default CodeFixTaskType;
+
+/*
+ * What a queued run of a recipe must CARRY to be executable — the claim
+ * guard and the task-details endpoint both group recipes by this, so a new
+ * recipe declares its context kind exactly once.
+ */
+export enum CodeFixContextKind {
+  // Executes against AIRun.triggeredByTelemetryExceptionId.
+  TelemetryException = "TelemetryException",
+  // Executes against AIRun.triggeredByIncidentId / triggeredByAlertId.
+  IncidentOrAlertSubject = "IncidentOrAlertSubject",
+  /*
+   * Executes against evidence captured at trigger time into
+   * AIRun.taskContext (FixPerformance: traceId + span-tree findings) — no
+   * subject row exists at all.
+   */
+  TaskContext = "TaskContext",
+}
+
+export class CodeFixTaskTypeHelper {
+  /*
+   * The recipes a user may start today FROM THE EXCEPTION PAGE. Recipes
+   * outside this list exist as enum values so the worker/UI can already
+   * dispatch on them, but creation via the exception-page endpoint is
+   * server-rejected. ImproveInstrumentation, FixFromIncident and
+   * FixPerformance stay off this list by design — they are not
+   * exception-triggered at all: ImproveInstrumentation's trigger is an
+   * inconclusive AI investigation on an opted-in project,
+   * FixFromIncident is user-triggered from the investigation panel
+   * (POST /ai-investigation/create-fix-task), and FixPerformance is
+   * user-triggered from the trace view
+   * (POST /ai-investigation/create-performance-fix-task).
+   */
+  public static getUserTriggerableTaskTypes(): Array<CodeFixTaskType> {
+    return [CodeFixTaskType.FixException, CodeFixTaskType.WriteRegressionTest];
+  }
+
+  public static isUserTriggerable(taskType: CodeFixTaskType): boolean {
+    return this.getUserTriggerableTaskTypes().includes(taskType);
+  }
+
+  /*
+   * Which context record a queued run of this recipe must carry to be
+   * executable. The claim guard rejects runs missing their kind's record,
+   * and the task-details endpoint dispatches its response shape on it.
+   * Unlisted (and legacy-null-normalized) recipes are exception-based —
+   * the safe default, since an exception-less claim of one is unexecutable.
+   */
+  public static getContextKind(taskType: CodeFixTaskType): CodeFixContextKind {
+    switch (taskType) {
+      case CodeFixTaskType.ImproveInstrumentation:
+      case CodeFixTaskType.FixFromIncident:
+        return CodeFixContextKind.IncidentOrAlertSubject;
+      case CodeFixTaskType.FixPerformance:
+        return CodeFixContextKind.TaskContext;
+      default:
+        return CodeFixContextKind.TelemetryException;
+    }
+  }
+
+  /*
+   * Whether the recipe executes against a telemetry exception
+   * (AIRun.triggeredByTelemetryExceptionId). Kept as sugar over
+   * getContextKind — the claim guard and the task-details endpoint now
+   * dispatch on the full context kind.
+   */
+  public static requiresTelemetryException(taskType: CodeFixTaskType): boolean {
+    return (
+      this.getContextKind(taskType) === CodeFixContextKind.TelemetryException
+    );
+  }
+
+  public static isValidTaskType(value: string): value is CodeFixTaskType {
+    return Object.values(CodeFixTaskType).includes(value as CodeFixTaskType);
+  }
+
+  // Null means FixException: rows created before the column existed.
+  public static fromDatabaseValue(
+    value: CodeFixTaskType | string | null | undefined,
+  ): CodeFixTaskType {
+    if (value && this.isValidTaskType(value.toString())) {
+      return value as CodeFixTaskType;
+    }
+
+    return CodeFixTaskType.FixException;
+  }
+}

package/Types/AI/FixPullRequestCiStatus.ts

@@ -0,0 +1,132 @@
+import CodeFixTaskType from "./CodeFixTaskType";
+
+/*
+ * The rolled-up CI conclusion recorded on an AI fix pull request
+ * (AIAgentTaskPullRequest.ciStatus) — B4 Tier 1: verification via the
+ * customer's OWN CI on the draft PRs. We read check-run conclusions through
+ * the GitHub App; we never re-run or gate the customer's CI.
+ *
+ * G9 honesty rule: only Green and ExpectedFailureObserved ever count as
+ * "CI-verified". NoCiConfigured (and a null column — not yet polled) read as
+ * unverified, never verified — a repo without CI verifies nothing.
+ */
+enum FixPullRequestCiStatus {
+  // Check runs exist and at least one has not completed yet.
+  Pending = "Pending",
+  // Every check run completed and none failed.
+  Green = "Green",
+  // Every check run completed and at least one failed.
+  Red = "Red",
+  /*
+   * A WriteRegressionTest PR whose checks concluded RED: the PR's whole
+   * point is a test that SHOULD FAIL until the bug is fixed, so a failing
+   * check is the desired signal, not a defect. Honest caveat: at check-run
+   * granularity we cannot tell WHICH job failed — a repo whose lint breaks
+   * on the PR also reads as expected-failure. Job-level discrimination
+   * (inspecting check names) is a tracked Tier 1 residual in the roadmap.
+   */
+  ExpectedFailureObserved = "ExpectedFailureObserved",
+  /*
+   * The PR's head branch has zero check runs — the repository runs no CI on
+   * this PR. Per G9 this is "unverified", never "verified".
+   */
+  NoCiConfigured = "NoCiConfigured",
+}
+
+export default FixPullRequestCiStatus;
+
+// Counts of one PR's check runs, as read from GitHub.
+export interface FixPullRequestCiCheckRunCounts {
+  total: number;
+  completed: number;
+  failed: number;
+  pending: number;
+}
+
+export class FixPullRequestCiStatusHelper {
+  /*
+   * Roll one PR's check-run counts into a single conclusion. The order is
+   * deliberate:
+   *   1. no check runs at all      -> NoCiConfigured (nothing ran; G9: unverified)
+   *   2. any run still pending     -> Pending (we report only FINAL
+   *      conclusions — a failure observed while other checks still run is
+   *      not yet the branch's conclusion)
+   *   3. any completed run failed  -> Red
+   *   4. otherwise                 -> Green
+   */
+  public static rollUpConclusion(
+    counts: FixPullRequestCiCheckRunCounts,
+  ): FixPullRequestCiStatus {
+    if (counts.total === 0) {
+      return FixPullRequestCiStatus.NoCiConfigured;
+    }
+
+    if (counts.pending > 0) {
+      return FixPullRequestCiStatus.Pending;
+    }
+
+    if (counts.failed > 0) {
+      return FixPullRequestCiStatus.Red;
+    }
+
+    return FixPullRequestCiStatus.Green;
+  }
+
+  /*
+   * The SHOULD-FAIL rule: a WriteRegressionTest PR exists to prove a bug
+   * with a test that fails until the bug is fixed, so a RED conclusion on
+   * such a PR is the expected outcome and is recorded as
+   * ExpectedFailureObserved. Every other conclusion, and every other task
+   * type, passes through unchanged. (Caveat documented on the enum member:
+   * we cannot tell which job failed — a broken lint also reads as
+   * expected-failure until job-level discrimination ships.)
+   */
+  public static applyTaskType(data: {
+    conclusion: FixPullRequestCiStatus;
+    taskType: CodeFixTaskType;
+  }): FixPullRequestCiStatus {
+    if (
+      data.conclusion === FixPullRequestCiStatus.Red &&
+      data.taskType === CodeFixTaskType.WriteRegressionTest
+    ) {
+      return FixPullRequestCiStatus.ExpectedFailureObserved;
+    }
+
+    return data.conclusion;
+  }
+
+  /*
+   * The G9 verification predicate, defined ONCE: a PR counts as CI-verified
+   * only on Green or ExpectedFailureObserved. NoCiConfigured, Pending, Red
+   * and null all read as unverified.
+   */
+  public static isVerified(
+    status: FixPullRequestCiStatus | undefined | null,
+  ): boolean {
+    return (
+      status === FixPullRequestCiStatus.Green ||
+      status === FixPullRequestCiStatus.ExpectedFailureObserved
+    );
+  }
+
+  // Human-readable line for the run's glass-box ProgressLog trail.
+  public static describeForProgressLog(data: {
+    ciStatus: FixPullRequestCiStatus;
+    counts: FixPullRequestCiCheckRunCounts;
+  }): string {
+    switch (data.ciStatus) {
+      case FixPullRequestCiStatus.Green:
+        return `CI on the fix PR: Green (${data.counts.completed}/${data.counts.total} checks passed)`;
+      case FixPullRequestCiStatus.Red:
+        return `CI on the fix PR: Red (${data.counts.failed}/${data.counts.total} checks failed)`;
+      case FixPullRequestCiStatus.ExpectedFailureObserved:
+        return `Regression-test PR: expected failure observed (${data.counts.failed}/${data.counts.total} checks failed — a failing check is the desired signal for a should-fail test)`;
+      case FixPullRequestCiStatus.Pending:
+        return `CI on the fix PR: Pending (${data.counts.completed}/${data.counts.total} checks completed)`;
+      case FixPullRequestCiStatus.NoCiConfigured:
+        return "CI on the fix PR: no check runs found — the repository runs no CI on this branch, so the fix is unverified";
+      default:
+        return `CI on the fix PR: ${data.ciStatus}`;
+    }
+  }
+}

package/Types/BaseDatabase/AggregationIntervalUtil.ts

@@ -92,6 +92,73 @@ export class AggregationIntervalUtil {
         return 1000 * 60;
     }
   }
+
+  /*
+   * Floor a timestamp DOWN to the start of its aggregation bucket, matching
+   * the server's `toStartOfInterval(time, INTERVAL 1 <interval>)` grid. This
+   * lets a chart align its query window to the bucket grid so the leading
+   * edge lands on a real bucket boundary instead of mid-bucket — a
+   * mid-bucket start renders as an empty gap before the first plotted point
+   * (the first bucket is partial and its timestamp falls before the axis
+   * origin).
+   *
+   * Only Minute/Hour/Day are aligned: for those the fixed-ms epoch grid is
+   * an EXACT match for ClickHouse's UTC bucketing (epoch-day == UTC
+   * midnight), and these are the windows where the leading gap is actually
+   * visible. Week/Month/Year snap to calendar boundaries (Monday / 1st /
+   * Jan-1) server-side, which a fixed-ms grid can't reproduce, so those (and
+   * `Total`) are returned UNCHANGED rather than risk shifting the gap for
+   * long windows — their pre-existing behavior is preserved.
+   */
+  public static floorDateToIntervalGrid(
+    date: Date,
+    interval: AggregationInterval,
+  ): Date {
+    const ms: number = OneUptimeDate.fromString(date).getTime();
+    const alignableIntervals: Array<AggregationInterval> = [
+      AggregationInterval.Minute,
+      AggregationInterval.Hour,
+      AggregationInterval.Day,
+    ];
+    if (!alignableIntervals.includes(interval)) {
+      return new Date(ms);
+    }
+    const bucketMs: number = this.getAggregationIntervalMs(interval);
+    if (!Number.isFinite(bucketMs) || bucketMs <= 0) {
+      return new Date(ms);
+    }
+    return new Date(Math.floor(ms / bucketMs) * bucketMs);
+  }
+
+  /*
+   * Align a query window to the aggregation-bucket grid. The bucket size is
+   * derived from the RAW window and returned alongside the aligned dates so
+   * the caller can PIN it (AggregateBy.aggregationInterval): flooring the
+   * start slightly widens the window, and without pinning that could bump a
+   * window sitting exactly on a tier threshold (e.g. a 3h window) into the
+   * next-coarser interval and change the whole chart's resolution. The start
+   * is floored DOWN so the first bucket is complete and lands on the axis
+   * origin (removing the leading gap); the end is left untouched so the
+   * latest, still-in-progress bucket and its live data continue to show.
+   */
+  public static getIntervalAlignedWindow(data: {
+    startDate: Date;
+    endDate: Date;
+  }): {
+    startDate: Date;
+    endDate: Date;
+    interval: AggregationInterval;
+  } {
+    const interval: AggregationInterval = this.getAggregationIntervalForWindow({
+      startDate: data.startDate,
+      endDate: data.endDate,
+    });
+    return {
+      startDate: this.floorDateToIntervalGrid(data.startDate, interval),
+      endDate: OneUptimeDate.fromString(data.endDate),
+      interval,
+    };
+  }
 }
 
 export default AggregationIntervalUtil;