@oneuptime/common 13.0.4 → 13.0.6

package/Types/ServiceLevelObjective/SloHistoryMetricName.ts

@@ -0,0 +1,25 @@
+/**
+ * The `SloHistory.metricName` values the SLO evaluation worker writes on
+ * every run — one ClickHouse row per series per evaluation.
+ *
+ * These strings are PERSISTED: 400 days of history rows already carry them,
+ * and the dashboard SLO widget, the SLO charts and the overview's burn-down
+ * all select rows by them. Renaming a member's value would silently orphan
+ * every existing row (charts would read "no history" for a year), so the
+ * values are frozen — add a member for a new series, never edit one.
+ *
+ * They used to be three separately typed string literals in the worker, the
+ * charts page and the widget helper. Common/Tests/Utils/Slo/SloHistoryMetricName.test.ts
+ * pins the worker's writes and the widget's reads to these values.
+ *
+ * Not to be confused with SloMetricType, which names the `oneuptime.slo.*`
+ * telemetry metrics posted alongside (a different table, a different
+ * retention and a different consumer).
+ */
+enum SloHistoryMetricName {
+  SliPercent = "sli.percent",
+  ErrorBudgetRemainingPercent = "error.budget.remaining.percent",
+  BurnRate = "burn.rate",
+}
+
+export default SloHistoryMetricName;

package/Types/ServiceLevelObjective/SloMetricType.ts

@@ -0,0 +1,49 @@
+/*
+ * Metric names an SLO evaluation posts, next to the SloHistory row it already
+ * writes, so an SLO can be charted, alerted on and dashboarded like any other
+ * metric - the same way monitors post `oneuptime.monitor.*`.
+ *
+ * The values are stored verbatim as metric names in ClickHouse. Renaming one
+ * orphans every data point already written under the old name, so treat them
+ * as a public, append-only contract.
+ *
+ * Rows carry `sloId`, `projectId` and `sloName` attributes plus the SLO's
+ * labels, with primaryEntityId = the SLO id.
+ */
+enum SloMetricType {
+  // Current SLI over the compliance window. Unit "%", aggregated with Avg.
+  SliPercent = "oneuptime.slo.sli.percent",
+
+  /*
+   * The objective the SLI is measured against. Unit "%", aggregated with Avg.
+   * The only series the Paused / Misconfigured guard paths also post
+   * (SloMetricUtil.saveSloGuardMetrics): it is configuration, not a reading,
+   * and it keeps the SLO in the dashboard template's sloName picker.
+   */
+  TargetPercent = "oneuptime.slo.target.percent",
+
+  /*
+   * Share of the error budget still unspent; negative once the budget is
+   * exhausted. Unit "%", aggregated with Avg.
+   */
+  ErrorBudgetRemainingPercent = "oneuptime.slo.error.budget.remaining.percent",
+
+  // Error budget still unspent, in seconds. Unit "seconds", aggregated with Avg.
+  ErrorBudgetRemainingSeconds = "oneuptime.slo.error.budget.remaining.seconds",
+
+  /*
+   * How fast the budget is being consumed (1 = exhausted exactly at the end of
+   * the window). Unit "x", aggregated with Max so a short spike is not averaged
+   * away.
+   */
+  BurnRate = "oneuptime.slo.burn.rate",
+
+  /*
+   * Healthy = 0, AtRisk = 1, BudgetExhausted = 2. Not emitted on the Paused /
+   * Misconfigured guard paths, which have no measurement behind them. Unit "",
+   * aggregated with Max so the worst state in a bucket wins.
+   */
+  Status = "oneuptime.slo.status",
+}
+
+export default SloMetricType;

package/Types/StatusPage/StatusPageSubscriberNotificationEventType.ts

@@ -13,20 +13,24 @@ enum StatusPageSubscriberNotificationEventType {
   SubscriberIncidentCreated = "Subscriber Incident Created",
   SubscriberIncidentStateChanged = "Subscriber Incident State Changed",
   SubscriberIncidentNoteCreated = "Subscriber Incident Note Created",
+  SubscriberIncidentNoteUpdated = "Subscriber Incident Note Updated",
   SubscriberIncidentPostmortemPublished = "Subscriber Incident Postmortem Published",
 
   // Incident Episode related events
   SubscriberEpisodeCreated = "Subscriber Episode Created",
   SubscriberEpisodeStateChanged = "Subscriber Episode State Changed",
   SubscriberEpisodeNoteCreated = "Subscriber Episode Note Created",
+  SubscriberEpisodeNoteUpdated = "Subscriber Episode Note Updated",
 
   // Announcement related events
   SubscriberAnnouncementCreated = "Subscriber Announcement Created",
+  SubscriberAnnouncementUpdated = "Subscriber Announcement Updated",
 
   // Scheduled Maintenance related events
   SubscriberScheduledMaintenanceCreated = "Subscriber Scheduled Maintenance Created",
   SubscriberScheduledMaintenanceStateChanged = "Subscriber Scheduled Maintenance State Changed",
   SubscriberScheduledMaintenanceNoteCreated = "Subscriber Scheduled Maintenance Note Created",
+  SubscriberScheduledMaintenanceNoteUpdated = "Subscriber Scheduled Maintenance Note Updated",
 
   // Recurring report events
   SubscriberReport = "Subscriber Report",

package/Types/StatusPage/SubscriberNotificationTemplateVariables.ts

@@ -0,0 +1,331 @@
+import BadDataException from "../Exception/BadDataException";
+import StatusPageSubscriberNotificationEventType from "./StatusPageSubscriberNotificationEventType";
+
+export interface SubscriberNotificationTemplateVariable {
+  name: string;
+  description: string;
+}
+
+/*
+ * The variables a custom status page subscriber notification template can use
+ * for each event type, as {{variableName}}.
+ *
+ * This is a promise to template authors: the worker that sends an event must
+ * pass every one of these to the template, on every channel, or the
+ * placeholder renders as an empty string. The worker tests hold each worker to
+ * this list, and the dashboard's variable reference is tested against it.
+ *
+ * Kept free of database dependencies so both of those can import it.
+ */
+export default class SubscriberNotificationTemplateVariables {
+  public static getAvailableVariablesForEventType(
+    eventType: StatusPageSubscriberNotificationEventType,
+  ): Array<SubscriberNotificationTemplateVariable> {
+    /*
+     * Messages about the subscription itself (confirm, welcome, manage) and
+     * the uptime report are not about any resource, so they only get the
+     * status page variables. Everything that reports an event also gets the
+     * resources it affects on the receiving status page.
+     */
+    const statusPageVariables: Array<SubscriberNotificationTemplateVariable> = [
+      { name: "statusPageName", description: "Name of the status page" },
+      { name: "statusPageUrl", description: "URL of the status page" },
+      {
+        name: "unsubscribeUrl",
+        description: "URL to unsubscribe from notifications",
+      },
+    ];
+
+    const commonVariables: Array<SubscriberNotificationTemplateVariable> = [
+      ...statusPageVariables,
+      { name: "resourcesAffected", description: "List of affected resources" },
+    ];
+
+    switch (eventType) {
+      case StatusPageSubscriberNotificationEventType.SubscriberSubscriptionConfirmation:
+        return [
+          ...statusPageVariables,
+          {
+            name: "confirmationUrl",
+            description:
+              "URL the subscriber opens to confirm their subscription",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberSubscribed:
+        return [...statusPageVariables];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberManageSubscription:
+        return [
+          ...statusPageVariables,
+          {
+            name: "manageSubscriptionUrl",
+            description:
+              "URL the subscriber uses to manage or cancel their subscription",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberIncidentCreated:
+        return [
+          ...commonVariables,
+          { name: "incidentTitle", description: "Title of the incident" },
+          {
+            name: "incidentDescription",
+            description: "Description of the incident",
+          },
+          { name: "incidentSeverity", description: "Severity of the incident" },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberIncidentStateChanged:
+        return [
+          ...commonVariables,
+          { name: "incidentTitle", description: "Title of the incident" },
+          {
+            name: "incidentDescription",
+            description: "Description of the incident",
+          },
+          { name: "incidentSeverity", description: "Severity of the incident" },
+          {
+            name: "incidentState",
+            description: "Current state of the incident",
+          },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteCreated:
+      case StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteUpdated:
+        return [
+          ...commonVariables,
+          { name: "incidentTitle", description: "Title of the incident" },
+          { name: "incidentSeverity", description: "Severity of the incident" },
+          {
+            name: "incidentState",
+            description: "Current state of the incident",
+          },
+          { name: "postedAt", description: "When the note was posted" },
+          { name: "note", description: "Content of the note" },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberIncidentPostmortemPublished:
+        return [
+          ...commonVariables,
+          { name: "incidentTitle", description: "Title of the incident" },
+          { name: "incidentSeverity", description: "Severity of the incident" },
+          {
+            name: "postmortemNote",
+            description: "Content of the postmortem note",
+          },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberAnnouncementCreated:
+      case StatusPageSubscriberNotificationEventType.SubscriberAnnouncementUpdated:
+        return [
+          ...commonVariables,
+          {
+            name: "announcementTitle",
+            description: "Title of the announcement",
+          },
+          {
+            name: "announcementDescription",
+            description: "Description of the announcement",
+          },
+          {
+            name: "detailsUrl",
+            description: "URL to view announcement details",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberScheduledMaintenanceCreated:
+        return [
+          ...commonVariables,
+          {
+            name: "scheduledMaintenanceTitle",
+            description: "Title of the scheduled maintenance",
+          },
+          {
+            name: "scheduledMaintenanceDescription",
+            description: "Description of the scheduled maintenance",
+          },
+          {
+            name: "scheduledStartTime",
+            description: "When the maintenance is scheduled to start",
+          },
+          {
+            name: "scheduledEndTime",
+            description: "When the maintenance is scheduled to end",
+          },
+          {
+            name: "detailsUrl",
+            description: "URL to view scheduled maintenance details",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberScheduledMaintenanceStateChanged:
+        return [
+          ...commonVariables,
+          {
+            name: "scheduledMaintenanceTitle",
+            description: "Title of the scheduled maintenance",
+          },
+          {
+            name: "scheduledMaintenanceDescription",
+            description: "Description of the scheduled maintenance",
+          },
+          {
+            name: "scheduledMaintenanceState",
+            description: "Current state of the scheduled maintenance",
+          },
+          {
+            name: "detailsUrl",
+            description: "URL to view scheduled maintenance details",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberScheduledMaintenanceNoteCreated:
+      case StatusPageSubscriberNotificationEventType.SubscriberScheduledMaintenanceNoteUpdated:
+        return [
+          ...commonVariables,
+          {
+            name: "scheduledMaintenanceTitle",
+            description: "Title of the scheduled maintenance",
+          },
+          {
+            name: "scheduledMaintenanceDescription",
+            description: "Description of the scheduled maintenance",
+          },
+          {
+            name: "scheduledMaintenanceState",
+            description: "Current state of the scheduled maintenance",
+          },
+          { name: "postedAt", description: "When the note was posted" },
+          { name: "note", description: "Content of the note" },
+          {
+            name: "detailsUrl",
+            description: "URL to view scheduled maintenance details",
+          },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberEpisodeCreated:
+        return [
+          ...commonVariables,
+          { name: "episodeTitle", description: "Title of the incident" },
+          {
+            name: "episodeDescription",
+            description: "Description of the incident",
+          },
+          { name: "episodeSeverity", description: "Severity of the incident" },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberEpisodeStateChanged:
+        return [
+          ...commonVariables,
+          { name: "episodeTitle", description: "Title of the incident" },
+          { name: "episodeSeverity", description: "Severity of the incident" },
+          {
+            name: "episodeState",
+            description: "Current state of the incident",
+          },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberEpisodeNoteCreated:
+      case StatusPageSubscriberNotificationEventType.SubscriberEpisodeNoteUpdated:
+        return [
+          ...commonVariables,
+          { name: "episodeTitle", description: "Title of the incident" },
+          { name: "episodeSeverity", description: "Severity of the incident" },
+          { name: "note", description: "Content of the note" },
+          { name: "detailsUrl", description: "URL to view incident details" },
+        ];
+
+      case StatusPageSubscriberNotificationEventType.SubscriberReport:
+        /*
+         * The report template is rendered through the full Handlebars engine
+         * with the structured `report` object, so the per-resource fields are
+         * accessed inside {{#each report.resources}} rather than as flat
+         * scalars. The entries below document the top-level paths.
+         */
+        return [
+          ...statusPageVariables,
+          {
+            name: "report.reportDates",
+            description: "The reporting period as a range",
+          },
+          {
+            name: "report.reportPeriodName",
+            description:
+              'How a sentence refers to the period - "the last 30 days", "July 2026"',
+          },
+          {
+            name: "report.reportStartDate",
+            description: "First day of the reporting period",
+          },
+          {
+            name: "report.reportEndDate",
+            description: "Last day of the reporting period",
+          },
+          {
+            name: "report.reportTimezone",
+            description: "The timezone the reporting period was resolved in",
+          },
+          {
+            name: "report.averageUptimePercent",
+            description: "Average uptime across all resources",
+          },
+          {
+            name: "report.totalDowntimeInHoursAndMinutes",
+            description: "Total downtime in the period",
+          },
+          {
+            name: "report.totalIncidents",
+            description: "Total number of incidents in the period",
+          },
+          {
+            name: "report.totalResources",
+            description: "Number of resources on the status page",
+          },
+          {
+            name: "report.resources",
+            description:
+              "Array of per-resource rows (resourceName, uptimePercentAsString, downtimeInHoursAndMinutes, totalIncidentCount, groupName, groupPath) to loop over with {{#each}}",
+          },
+          {
+            name: "report.hasGroups",
+            description:
+              "true when the status page organises its resources into groups",
+          },
+          {
+            name: "report.rows",
+            description:
+              "The status page's group hierarchy flattened into render order (isGroup, name, depth, indentInPixels, uptimePercentAsString, downtimeInHoursAndMinutes, totalIncidentCount, totalResources) to loop over with {{#each}}",
+          },
+          {
+            name: "report.groups",
+            description:
+              "The group hierarchy as a nested tree (groupName, groupPath, depth, uptimePercentAsString, downtimeInHoursAndMinutes, totalIncidentCount, totalResources, resources, subGroups)",
+          },
+          {
+            name: "report.ungroupedResources",
+            description: "Per-resource rows for resources that are in no group",
+          },
+        ];
+
+      default:
+        throw new BadDataException(`Unknown event type: ${eventType}`);
+    }
+  }
+
+  public static getVariableNamesForEventType(
+    eventType: StatusPageSubscriberNotificationEventType,
+  ): Array<string> {
+    return this.getAvailableVariablesForEventType(eventType).map(
+      (variable: SubscriberNotificationTemplateVariable): string => {
+        return variable.name;
+      },
+    );
+  }
+}

package/Types/StatusPage/SubscriberNotificationTrigger.ts

@@ -0,0 +1,12 @@
+/*
+ * What a subscriber notification about an announcement or a public note is
+ * telling people: that it was just posted, or that something already posted
+ * has been edited. The two share one send path and differ only in wording,
+ * template and the status columns they track.
+ */
+enum SubscriberNotificationTrigger {
+  Created = "Created",
+  Updated = "Updated",
+}
+
+export default SubscriberNotificationTrigger;

package/Types/StatusPage/SubscriberUpdateNotification.ts

@@ -0,0 +1,89 @@
+import { JSONObject } from "../JSON";
+import StatusPageSubscriberNotificationStatus from "./StatusPageSubscriberNotificationStatus";
+
+/*
+ * Status page subscribers hear about an announcement or a public note once,
+ * when it is posted. Editing it afterwards used to change what the status page
+ * showed without telling anyone, so a corrected maintenance window or a
+ * revised customer update reached only the people who happened to reload the
+ * page.
+ *
+ * Whether an edit is worth a notification is the editor's call - a typo fix is
+ * not, a new date is - so it is asked per edit rather than stored as a setting
+ * on the item. The choice travels with the update request as a misc data prop
+ * (it is not a column: a stored "notify on the next edit" flag would either
+ * stick and notify on every later typo fix, or have to be reset behind the
+ * caller's back). The service turns it into a Pending update notification
+ * status, and a worker job sends it.
+ *
+ * Everything here is shared by the dashboard, which sets the flag, and the
+ * server, which reads it, so the two cannot drift apart.
+ */
+export default class SubscriberUpdateNotification {
+  // The misc data prop an update request carries to ask for a notification.
+  public static readonly miscDataKey: string = "notifySubscribersOfUpdate";
+
+  public static readonly queuedMessage: string =
+    "Subscribers will be notified about this update shortly.";
+
+  public static readonly resendQueuedMessage: string =
+    "Update notification queued for resending.";
+
+  public static readonly sentMessage: string =
+    "Update notifications sent successfully to all subscribers.";
+
+  public static readonly notYetNotifiedMessage: string =
+    "Subscribers have not been notified about the original post yet. That notification will carry the latest content, so no separate update notification was sent.";
+
+  public static readonly formFieldTitle: string =
+    "Notify subscribers about this update";
+
+  /*
+   * Only a real yes counts. The flag arrives over JSON, so accept the string
+   * form a hand-written API request might send, and nothing looser: a stray
+   * "false" or 1 must never page every subscriber of a status page.
+   */
+  public static isRequested(
+    miscDataProps: JSONObject | undefined | null,
+  ): boolean {
+    if (!miscDataProps || typeof miscDataProps !== "object") {
+      return false;
+    }
+
+    const value: unknown = miscDataProps[this.miscDataKey];
+
+    return value === true || value === "true";
+  }
+
+  public static getMiscDataProps(): JSONObject {
+    return {
+      [this.miscDataKey]: true,
+    };
+  }
+
+  /*
+   * Returns why an update notification should not be sent given where the
+   * original ("posted") notification is, or null when it may go out.
+   *
+   * While the original is still Pending or InProgress, subscribers have not
+   * heard of the item at all. The original notification reads the item when it
+   * is sent, so it already carries this edit - a second "updated" message
+   * about something they were never told about would only confuse them.
+   *
+   * Every settled state lets the update through: Success is the normal case,
+   * and Skipped or Failed mean subscribers were not told originally, which the
+   * editor is now explicitly asking to do.
+   */
+  public static getSkipReasonForOriginalNotificationStatus(
+    originalStatus: StatusPageSubscriberNotificationStatus | undefined | null,
+  ): string | null {
+    if (
+      originalStatus === StatusPageSubscriberNotificationStatus.Pending ||
+      originalStatus === StatusPageSubscriberNotificationStatus.InProgress
+    ) {
+      return this.notYetNotifiedMessage;
+    }
+
+    return null;
+  }
+}

package/Types/Telemetry/EntityType.ts

@@ -72,6 +72,20 @@ enum EntityType {
   DockerSwarmService = "docker.swarm.service",
   DockerSwarmTask = "docker.swarm.task",
   TelemetrySdk = "telemetry.sdk",
+  /*
+   * Dependency types, discovered from the CLIENT / PRODUCER spans of an
+   * instrumented service rather than from a resource of their own. They are
+   * the far end of a call nothing on the other side reported: a PostgreSQL
+   * or Redis a service queries (`db.system.name` / `db.system`), or an HTTP /
+   * gRPC / messaging endpoint it talks to (`server.address`, `peer.service`,
+   * `messaging.system`). OneUptime-defined — semconv describes these only as
+   * span attributes, never as entities. Discovered (heartbeat-bumped by the
+   * ComputeServiceDependencies cron), so they age out like any other
+   * discovered row. Deliberately distinct from the manual ExternalService /
+   * ExternalDatabase types below, which nothing ever observes.
+   */
+  Database = "database",
+  RemoteService = "remote.service",
   /*
    * Inventory-mirrored types. Unlike everything above, these are never
    * derived from an OTLP resource — the estate they describe is collected

package/Types/Telemetry/ExceptionSpanScope.ts

@@ -0,0 +1,83 @@
+/*
+ * Scope a span query to the spans that raised one exception group.
+ *
+ * Spans carry no fingerprint of their own; an exception group's occurrences
+ * (ExceptionInstance rows) record the (traceId, spanId) they were raised in.
+ * The server compiles this scope to
+ *
+ *   (traceId, spanId) IN (
+ *     SELECT traceId, spanId FROM <exception occurrences>
+ *     WHERE projectId = <the query's project>
+ *       AND fingerprint = <fingerprint>
+ *       [AND primaryEntityId = <service>]
+ *   )
+ *
+ * so the span list, its count, the histogram and the facets all describe
+ * exactly the spans behind the exception's occurrences — with no cap on how
+ * many occurrences there are. It only ever narrows a query: authorization
+ * still runs on the span query's own projectId and primaryEntityId.
+ */
+
+// The synthetic query key the span list endpoint reads.
+export const EXCEPTION_SPAN_SCOPE_QUERY_KEY: string = "exceptionScope";
+
+// Fingerprints are SHA-256 hex today; the cap only rejects junk.
+export const EXCEPTION_SPAN_SCOPE_MAX_FINGERPRINT_LENGTH: number = 512;
+
+export interface ExceptionSpanScope {
+  fingerprint: string;
+  // The exception group's service; a fingerprint is only unique per service.
+  primaryEntityId?: string | undefined;
+}
+
+const UUID_PATTERN: RegExp =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/*
+ * Validate an untrusted scope (request body, deserialized query). Returns
+ * null for anything malformed so callers can decide how to fail; a blank or
+ * oversized fingerprint, or a service id that is not a UUID, is malformed.
+ */
+export function parseExceptionSpanScope(
+  value: unknown,
+): ExceptionSpanScope | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const record: Record<string, unknown> = value as Record<string, unknown>;
+  const fingerprint: unknown = record["fingerprint"];
+
+  if (typeof fingerprint !== "string") {
+    return null;
+  }
+
+  const trimmedFingerprint: string = fingerprint.trim();
+
+  if (
+    trimmedFingerprint.length === 0 ||
+    trimmedFingerprint.length > EXCEPTION_SPAN_SCOPE_MAX_FINGERPRINT_LENGTH
+  ) {
+    return null;
+  }
+
+  const rawEntityId: unknown = record["primaryEntityId"];
+
+  if (rawEntityId === undefined || rawEntityId === null || rawEntityId === "") {
+    return { fingerprint: trimmedFingerprint };
+  }
+
+  const primaryEntityId: string =
+    typeof rawEntityId === "string"
+      ? rawEntityId.trim()
+      : typeof rawEntityId === "object" &&
+          typeof (rawEntityId as Record<string, unknown>)["value"] === "string"
+        ? ((rawEntityId as Record<string, unknown>)["value"] as string).trim()
+        : "";
+
+  if (!UUID_PATTERN.test(primaryEntityId)) {
+    return null;
+  }
+
+  return { fingerprint: trimmedFingerprint, primaryEntityId };
+}

package/Types/Telemetry/LockedFilterDetail.ts

@@ -0,0 +1,25 @@
+/*
+ * The search syntax a LOCKED telemetry filter chip shows in its tooltip, or
+ * why it has none.
+ *
+ * A resource page (a Kubernetes cluster, a Docker host, a RUM application,
+ * an incident's stored query, ...) pins the telemetry explorers it embeds to
+ * its own scope. The viewer shows that scope as a grey chip with a lock icon
+ * — "Cluster: production" — and a reader who wants the same slice on the
+ * main explorer page needs the search-bar text that reproduces it.
+ *
+ * The chip builders in the Dashboard fill one of these per locked chip: the
+ * search token when the explorer's grammar can spell the filter, otherwise
+ * the reason it cannot. Display-only: nothing here changes the query.
+ */
+
+export interface LockedFilterDetail {
+  /**
+   * Search-bar text that reproduces this filter on the explorer for the same
+   * signal, e.g. `@resource.k8s.cluster.name:prod-eks-01`. Absent when the
+   * grammar cannot express the filter.
+   */
+  searchToken?: string | undefined;
+  /** Why `searchToken` is absent, when it is — shown in place of the syntax. */
+  searchTokenUnavailableReason?: string | undefined;
+}