@oneuptime/common 12.0.32 → 12.0.34

package/Types/Monitor/ServiceAlertTemplates.ts

@@ -105,16 +105,19 @@ export interface ServiceAlertTemplate {
 }
 
 /*
- * `EvaluateOverTimeType` names the window collapse, and its two members used
- * here do NOT mean what their names suggest — worth stating once, here, rather
- * than being rediscovered per template:
+ * `EvaluateOverTimeType` names the window collapse. The two members these
+ * templates use are worth stating once, here, rather than being rediscovered
+ * per template:
  *
  *   AnyValue  -> ANY bucket in the rolling window breaching is a breach.
  *                Right for spikes.
- *   AllValues -> EVERY bucket must breach. Right for sustained pressure, and
- *                what the comparators actually do for every member that is not
- *                `AnyValue` (they fall through to `.every()`; there is no
- *                averaging on this code path despite `Average` existing).
+ *   AllValues -> EVERY bucket must breach. Right for sustained pressure.
+ *
+ * The reducing members (`Average`, `Sum`, `MaximumValue`, `MunimumValue`) do
+ * now collapse the window to one sample before the comparison —
+ * `CompareCriteria.reduceWindow` — so they mean what they say. `AllValues` is
+ * still the right default here: a reduced window hides the shape, and a metric
+ * that spends half the window fine is not under sustained pressure.
  *
  * A window with no samples at all never reaches the comparator — the
  * evaluator's no-data guard returns "not breaching" under the default
@@ -129,6 +132,34 @@ export interface ServiceAlertTemplate {
  */
 const SUSTAINED: EvaluateOverTimeType = EvaluateOverTimeType.AllValues;
 
+/*
+ * The resource attribute that identifies ONE process of a service.
+ *
+ * Every metric template here except the two request-latency percentiles
+ * thresholds a property of a single process — a heap, an event loop, a
+ * goroutine count, a thread pool. Without a group-by the ClickHouse
+ * aggregation collapses every replica of the service into one number, so an
+ * `Avg` template on three replicas at 95/20/20 reads 45 and stays green while
+ * one of them OOM-kills, and a `Max` template fires on the worst replica with
+ * no way to say which. Grouping fixes both at once: the worker emits one
+ * series per instance and the alert carries that instance in `seriesLabels`,
+ * which `SeriesLabelDisplay` renders into the title and the description block.
+ *
+ * `service.instance.id` is OPTIONAL in the resource semantic conventions, and
+ * this degrades safely when it is absent: the query returns one series whose
+ * label value is the empty string (ClickHouse `attributes[k]` on a missing key
+ * yields ""), `MetricSeriesFingerprint.extractSeriesLabels` keeps the key so
+ * the fingerprint stays stable across evaluations, and
+ * `SeriesLabelDisplay.getDisplayLabels` drops empty values rather than
+ * rendering "Instance: ". A service that does not report it therefore gets
+ * exactly today's single-series behaviour, not silence.
+ *
+ * The `resource.` prefix is the one OtelMetricsIngestService stamps onto OTel
+ * resource attributes (`prefixKeysWithString: "resource"`), the same spelling
+ * KubernetesAlertTemplates uses for `resource.k8s.pod.name`.
+ */
+const PER_INSTANCE_GROUP_BY: Array<string> = ["resource.service.instance.id"];
+
 interface CountCriteriaArgs {
   args: ServiceAlertTemplateArgs;
   checkOn: CheckOn.SpanCount | CheckOn.ExceptionCount;
@@ -201,7 +232,17 @@ function buildCriteriaPair(data: {
         checkOn: data.checkOn,
         filterType: data.unhealthyFilterType,
         value: data.threshold,
-        metricMonitorOptions: metricMonitorOptions,
+        /*
+         * A copy per filter, not the shared object. `MetricMonitorCriteria`
+         * writes its `AnyValue` default straight back through this reference
+         * when `metricAggregationType` is unset, and the criteria form spreads
+         * and re-assigns it on edit — either of which, on a shared object,
+         * changes the healthy criteria as a side effect of touching the
+         * unhealthy one.
+         */
+        metricMonitorOptions: metricMonitorOptions
+          ? { ...metricMonitorOptions }
+          : undefined,
       },
     ],
     incidents: [
@@ -242,7 +283,10 @@ function buildCriteriaPair(data: {
         checkOn: data.checkOn,
         filterType: data.healthyFilterType,
         value: data.threshold,
-        metricMonitorOptions: metricMonitorOptions,
+        // A copy per filter — see the unhealthy filter above.
+        metricMonitorOptions: metricMonitorOptions
+          ? { ...metricMonitorOptions }
+          : undefined,
       },
     ],
     incidents: [],
@@ -316,6 +360,7 @@ function buildQueryConfig(data: {
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string> | undefined;
   legendUnit?: string | undefined;
+  groupByAttributeKeys?: Array<string> | undefined;
 }): MetricQueryConfigData {
   return {
     metricAliasData: {
@@ -332,6 +377,14 @@ function buildQueryConfig(data: {
         aggegationType: data.aggregationType,
         aggregateBy: {},
       },
+      /*
+       * Omitted entirely rather than written as [] when there is nothing to
+       * group by, so an ungrouped template serializes to exactly the shape it
+       * did before this parameter existed.
+       */
+      ...(data.groupByAttributeKeys && data.groupByAttributeKeys.length > 0
+        ? { groupByAttributeKeys: data.groupByAttributeKeys }
+        : {}),
     },
   };
 }
@@ -356,6 +409,13 @@ function buildMetricTemplate(data: {
   rollingTime?: RollingTime | undefined;
   unhealthyFilterType?: FilterType | undefined;
   healthyFilterType?: FilterType | undefined;
+  /*
+   * Defaults to per-instance. Pass `[]` only for a metric that is a property
+   * of the SERVICE rather than of one process — the request latency
+   * percentiles are the only two here, and grouping them would quietly change
+   * "the service's p95" into "some replica's p95", which is a different alert.
+   */
+  groupByAttributeKeys?: Array<string> | undefined;
   incidentDescription: string;
 }): ServiceAlertTemplate {
   return {
@@ -388,6 +448,8 @@ function buildMetricTemplate(data: {
               aggregationType: data.aggregationType,
               attributes: data.attributes,
               legendUnit: data.legendUnit,
+              groupByAttributeKeys:
+                data.groupByAttributeKeys || PER_INSTANCE_GROUP_BY,
             }),
           ],
           formulaConfigs: [],
@@ -443,6 +505,7 @@ function buildRatioTemplate(data: {
   denominatorAlias: string;
   resultAlias: string;
   thresholdPercent: number;
+  groupByAttributeKeys?: Array<string> | undefined;
   incidentDescription: string;
 }): ServiceAlertTemplate {
   return {
@@ -494,6 +557,18 @@ function buildRatioTemplate(data: {
               title: `${data.name} (used)`,
               aggregationType: MetricsAggregationType.Sum,
               attributes: data.numeratorAttributes,
+              /*
+               * The SAME key set on both queries. The worker splits every
+               * query on the UNION of their keys, so the split itself cannot
+               * go wrong from setting only one side — but
+               * `MetricMonitorCriteria.buildContext` reads
+               * `groupByAttributeKeys` off a SINGLE query config when it
+               * builds the alert's "Grouped By" root-cause block, and a
+               * one-sided setting renders that block empty for whichever side
+               * it read.
+               */
+              groupByAttributeKeys:
+                data.groupByAttributeKeys || PER_INSTANCE_GROUP_BY,
             }),
             buildQueryConfig({
               metricName: data.denominatorMetricName,
@@ -501,6 +576,8 @@ function buildRatioTemplate(data: {
               title: `${data.name} (limit)`,
               aggregationType: MetricsAggregationType.Sum,
               attributes: data.denominatorAttributes,
+              groupByAttributeKeys:
+                data.groupByAttributeKeys || PER_INSTANCE_GROUP_BY,
             }),
           ],
           formulaConfigs: [formulaConfig],
@@ -760,6 +837,14 @@ const latencyP95Template: ServiceAlertTemplate = buildMetricTemplate({
   metricAlias: "service_latency_p95",
   aggregationType: MetricsAggregationType.P95,
   legendUnit: "ms",
+  /*
+   * Not grouped, unlike every other metric template here. A request latency
+   * percentile is a property of the SERVICE — it is the number the SLO is
+   * written against — and splitting it per instance would turn "the service's
+   * p95 is above a second" into "one replica's p95 is above a second", which
+   * fires on a single slow pod and means something else.
+   */
+  groupByAttributeKeys: [],
   threshold: 1000,
   thresholdLabel: "1,000 ms",
   incidentDescription:
@@ -777,6 +862,8 @@ const latencyP99Template: ServiceAlertTemplate = buildMetricTemplate({
   metricAlias: "service_latency_p99",
   aggregationType: MetricsAggregationType.P99,
   legendUnit: "ms",
+  // Service-level, not per instance — see latencyP95Template.
+  groupByAttributeKeys: [],
   threshold: 2500,
   thresholdLabel: "2,500 ms",
   incidentDescription:
@@ -1147,7 +1234,7 @@ const pythonTemplates: Array<ServiceAlertTemplate> = [
     id: "service-python-rss-memory",
     name: "Resident Memory High",
     description:
-      "Alert when resident memory stays above 1 GB per worker — the signal that precedes an OOM kill. Needs the system-metrics instrumentation enabled.",
+      "Alert when a worker's resident memory stays above 1 GB — the signal that precedes an OOM kill. Needs the system-metrics instrumentation enabled. Reads process.runtime.cpython.memory with type=rss; newer opentelemetry-python releases report this as process.memory.usage, which the language-agnostic Process Memory High template already covers.",
     category: "Python Runtime",
     severity: "Warning",
     language: "python",
@@ -1166,7 +1253,7 @@ const pythonTemplates: Array<ServiceAlertTemplate> = [
     id: "service-python-thread-growth",
     name: "Thread Count Growth",
     description:
-      "Alert when thread count stays above 200, which usually means a leaked executor or an unclosed client pool. Needs the system-metrics instrumentation enabled.",
+      "Alert when thread count stays above 200, which usually means a leaked executor or an unclosed client pool. Needs the system-metrics instrumentation enabled. Reads process.runtime.cpython.thread_count; newer opentelemetry-python releases report this as process.thread.count — retarget the created monitor in one edit if your SDK emits that instead.",
     category: "Python Runtime",
     severity: "Warning",
     language: "python",

package/Types/Monitor/SnmpMonitor/NetworkDeviceAlertPack.ts

@@ -26,7 +26,7 @@ const PACK: Array<NetworkDeviceAlertPackItem> = [
   {
     name: "Device unreachable",
     description:
-      "The device stopped answering SNMP — likely down or unreachable.",
+      "The device stopped answering ping and SNMP — likely down or unreachable.",
     filters: [
       {
         checkOn: CheckOn.SnmpIsOnline,
@@ -37,6 +37,27 @@ const PACK: Array<NetworkDeviceAlertPackItem> = [
     createIncidents: true,
     createAlerts: false,
   },
+  /*
+   * An alert, not an incident: the device is still answering ping, so it is
+   * not down - but its SNMP walk is failing, which means no interfaces, no
+   * inventory and no health OIDs until someone fixes the credentials, the
+   * agent or the ACL. Never fires on a device that is only pinged: the
+   * criterion is not evaluated at all when no walk ran.
+   */
+  {
+    name: "SNMP walk failing",
+    description:
+      "The device answers ping but its SNMP walk is failing — check the credentials, the SNMP agent, or an ACL.",
+    filters: [
+      {
+        checkOn: CheckOn.SnmpWalkIsSucceeding,
+        filterType: FilterType.False,
+        value: undefined,
+      },
+    ],
+    createIncidents: false,
+    createAlerts: true,
+  },
   {
     name: "Interface down",
     description:

package/Types/Monitor/SqlConnectionConfig.ts

@@ -0,0 +1,31 @@
+import SqlDatabaseType from "./SqlDatabaseType";
+
+/*
+ * The connection half of a SQL-speaking monitor's configuration.
+ *
+ * Extracted so the SQL Query monitor and the Database Health monitor can
+ * share one implementation of the fiddly parts - TLS options, and especially
+ * the SQL Server integrated-authentication path, which has to detect the
+ * host's ODBC driver and build a connection string by hand. Duplicating that
+ * for a second monitor type would guarantee the two drift.
+ *
+ * Both MonitorStepSqlMonitor and MonitorStepDatabaseMonitor extend this, so
+ * anything that only needs to CONNECT should take this type rather than
+ * either step type.
+ */
+export default interface SqlConnectionConfig {
+  databaseType: SqlDatabaseType;
+  host: string;
+  port: number;
+  databaseName: string;
+  username: string;
+  // Raw password OR a {{monitorSecrets.name}} reference resolved server-side.
+  password: string;
+  /*
+   * Microsoft SQL Server only: authenticate as the identity the probe runs
+   * as (SSPI on Windows, Kerberos elsewhere).
+   */
+  useWindowsIntegratedAuthentication: boolean;
+  useSsl: boolean;
+  rejectUnauthorizedSsl: boolean;
+}

package/Types/Monitor/UptimeHistoryLabels.ts

@@ -0,0 +1,56 @@
+/*
+ * Every string the day-by-day uptime history speaks: the accessible names on
+ * the strip itself, and the chrome of the dialog a day opens.
+ *
+ * These live in one interface, rather than one per component, because a
+ * caller who translates the strip must also translate the dialog it opens -
+ * splitting them is how you end up with a French status page whose bars
+ * announce themselves in French and whose dialog is in English.
+ *
+ * Every field has an English default (DefaultUptimeHistoryLabels), so the
+ * dashboard - which is English-only, like the tooltip next to it - passes
+ * nothing.
+ */
+export default interface UptimeHistoryLabels {
+  /* Names the strip. {{total}} is the number of days it covers. */
+  graphLabel: string;
+  /* A day with data. {{date}}, {{uptime}}. */
+  dayLabel: string;
+  /* A day with data and incidents. {{date}}, {{uptime}}, {{total}}. */
+  dayLabelWithIncidents: string;
+  /* A day with no timeline rows at all. {{date}}. */
+  dayLabelNoData: string;
+  /* No timeline rows, but incidents. {{date}}, {{total}}. */
+  dayLabelNoDataWithIncidents: string;
+
+  /* Dialog + tooltip body. */
+  uptime: string;
+  noMonitoringData: string;
+  incidents: string;
+  noIncidents: string;
+  noIncidentsDescription: string;
+  /* Dialog subtitle when the day carried exactly one incident. */
+  oneIncidentOnThisDay: string;
+  /* Dialog subtitle for two or more. {{total}}. */
+  incidentsOnThisDay: string;
+  /* Prefixes an incident's declaration time: "Declared Mar 03 2026, 14:12". */
+  declared: string;
+  close: string;
+}
+
+export const DefaultUptimeHistoryLabels: UptimeHistoryLabels = {
+  graphLabel: "Uptime history for the last {{total}} days",
+  dayLabel: "{{date}}: {{uptime}}% uptime",
+  dayLabelWithIncidents: "{{date}}: {{uptime}}% uptime, {{total}} incidents",
+  dayLabelNoData: "{{date}}: no data",
+  dayLabelNoDataWithIncidents: "{{date}}: no data, {{total}} incidents",
+  uptime: "Uptime",
+  noMonitoringData: "No monitoring data for this day",
+  incidents: "Incidents",
+  noIncidents: "No incidents",
+  noIncidentsDescription: "No incidents were reported on this day.",
+  oneIncidentOnThisDay: "1 incident reported on this day",
+  incidentsOnThisDay: "{{total}} incidents reported on this day",
+  declared: "Declared",
+  close: "Close",
+};

package/Types/NetworkDevice/NetworkAlertPolicyScope.ts

@@ -0,0 +1,343 @@
+/*
+ * WHICH devices a Network Alert Policy covers.
+ *
+ * A policy says "devices like THESE get a Network Device monitor cloned from
+ * THIS template" once, and the engine keeps one monitor per matching device
+ * from then on. The "like these" half is this object: a set of site ids, a
+ * set of device-role ids and a set of label ids, stored as one jsonb column
+ * on the policy row rather than as three join tables.
+ *
+ * jsonb, not join tables, on purpose. The scope is read whole every time the
+ * engine asks "does this device match?" and never queried the other way
+ * round ("which policies name site X?" is answered by scanning the project's
+ * handful of policies, not by an index), so three link tables would buy
+ * nothing but three more CRUD surfaces and three more cascade rules to get
+ * right. It also lets the dashboard post the whole picker state as one field.
+ *
+ * The matching rule is the one every filter in this product uses:
+ *
+ *   - AND across kinds: a device must satisfy the site list AND the role list
+ *     AND the label list.
+ *   - OR within a kind: "in site A or site B", "carrying label X or label Y".
+ *   - An EMPTY kind matches everything. Leaving the sites list empty means
+ *     "any site (including no site)", not "no site".
+ *
+ * So `{}` — every list empty — is the widest possible scope: every device in
+ * the project. That is a legitimate and common policy ("everything gets a
+ * reachability monitor"), but it is also the one that provisions the most
+ * billable monitors, which is why `isUnscoped` exists as a named question
+ * rather than a `length === 0` check scattered over the callers: the settings
+ * table, the confirm dialog and the engine all need to say "ALL devices" in
+ * the same breath.
+ *
+ * Everything that reads a scope goes through `normalize` first. The column is
+ * jsonb, so a row can hold whatever a client — or a hand-edited API call — put
+ * in it: a lone string where an array was expected, nulls, duplicated ids,
+ * blank strings from an empty picker. Tolerating all of that in one place
+ * means the engine never throws over one bad row and never double-counts a
+ * device because a site id was listed twice.
+ */
+export interface NetworkAlertPolicyScope {
+  siteIds?: Array<string>;
+  networkDeviceRoleIds?: Array<string>;
+  labelIds?: Array<string>;
+}
+
+/*
+ * The slice of a NetworkDevice the matcher looks at. Kept to plain ids so
+ * the engine can feed it rows selected with three columns and a label join,
+ * and so a test can build one in a line.
+ */
+export interface NetworkAlertPolicyScopeDevice {
+  siteId?: string | null;
+  networkDeviceRoleId?: string | null;
+  labelIds?: Array<string>;
+}
+
+/*
+ * Display names for `describe`, keyed by id. Every map is optional and every
+ * lookup may miss: the settings table renders before its lookups resolve,
+ * and a scope can name a site that has since been deleted. A missing name
+ * falls back to a count ("in 2 sites"), never to the raw id.
+ */
+export interface NetworkAlertPolicyScopeNames {
+  sites?: Record<string, string>;
+  roles?: Record<string, string>;
+  labels?: Record<string, string>;
+}
+
+/*
+ * A normalized scope: every list present, deduplicated, and holding only
+ * non-blank strings. What `normalize` returns and what every other method
+ * works on internally.
+ */
+interface NormalizedNetworkAlertPolicyScope {
+  siteIds: Array<string>;
+  networkDeviceRoleIds: Array<string>;
+  labelIds: Array<string>;
+}
+
+/*
+ * One kind of id, for `describe`. `singular`/`plural` are the nouns; how the
+ * clause hangs off "Devices" is decided by the caller — sites are somewhere
+ * ("in"), roles and labels are something a device has ("with").
+ */
+interface ScopeKindDescription {
+  ids: Array<string>;
+  names: Record<string, string> | undefined;
+  singular: string;
+  plural: string;
+}
+
+export class NetworkAlertPolicyScopeUtil {
+  /*
+   * The canonical form of whatever was stored or posted.
+   *
+   * Accepts anything: `undefined`, `null`, a non-object, an object whose
+   * lists are missing, `null`, lone strings, or arrays holding nulls,
+   * numbers, blanks and duplicates. Returns three arrays of unique, trimmed,
+   * non-empty strings — and nothing else, so a stray property on the stored
+   * JSON never round-trips back into the column.
+   */
+  public static normalize(raw: unknown): NetworkAlertPolicyScope {
+    const source: Record<string, unknown> =
+      raw && typeof raw === "object" && !Array.isArray(raw)
+        ? (raw as Record<string, unknown>)
+        : {};
+
+    return {
+      siteIds: NetworkAlertPolicyScopeUtil.readIdList(source["siteIds"]),
+      networkDeviceRoleIds: NetworkAlertPolicyScopeUtil.readIdList(
+        source["networkDeviceRoleIds"],
+      ),
+      labelIds: NetworkAlertPolicyScopeUtil.readIdList(source["labelIds"]),
+    };
+  }
+
+  /*
+   * True when the scope names nothing at all — every device in the project.
+   *
+   * Runs through `normalize` first, so a scope of `{ siteIds: [""] }` or
+   * `{ siteIds: null }` reads as unscoped too: a blank picker is an empty
+   * picker, and the alternative — a scope that matches nothing because it
+   * holds one blank id — would be a policy that silently does nothing.
+   */
+  public static isUnscoped(
+    scope: NetworkAlertPolicyScope | null | undefined,
+  ): boolean {
+    const normalized: NormalizedNetworkAlertPolicyScope =
+      NetworkAlertPolicyScopeUtil.normalize(
+        scope,
+      ) as NormalizedNetworkAlertPolicyScope;
+
+    return (
+      normalized.siteIds.length === 0 &&
+      normalized.networkDeviceRoleIds.length === 0 &&
+      normalized.labelIds.length === 0
+    );
+  }
+
+  /*
+   * The matching rule itself: AND across kinds, OR within a kind, an empty
+   * kind matches everything.
+   *
+   * A device with no site never matches a scope that lists sites, and a
+   * device with no labels never matches a scope that lists labels — "in site
+   * A" cannot be true of a device that is nowhere. The converse is the
+   * empty-kind rule: a scope that lists no sites is satisfied by a device
+   * with no site.
+   */
+  public static matchesDevice(
+    scope: NetworkAlertPolicyScope | null | undefined,
+    device: NetworkAlertPolicyScopeDevice,
+  ): boolean {
+    const normalized: NormalizedNetworkAlertPolicyScope =
+      NetworkAlertPolicyScopeUtil.normalize(
+        scope,
+      ) as NormalizedNetworkAlertPolicyScope;
+
+    if (
+      normalized.siteIds.length > 0 &&
+      !NetworkAlertPolicyScopeUtil.listHasId(normalized.siteIds, device.siteId)
+    ) {
+      return false;
+    }
+
+    if (
+      normalized.networkDeviceRoleIds.length > 0 &&
+      !NetworkAlertPolicyScopeUtil.listHasId(
+        normalized.networkDeviceRoleIds,
+        device.networkDeviceRoleId,
+      )
+    ) {
+      return false;
+    }
+
+    if (normalized.labelIds.length > 0) {
+      const deviceLabelIds: Array<string> =
+        NetworkAlertPolicyScopeUtil.readIdList(device.labelIds);
+
+      const hasAnyLabel: boolean = deviceLabelIds.some(
+        (labelId: string): boolean => {
+          return normalized.labelIds.includes(labelId);
+        },
+      );
+
+      if (!hasAnyLabel) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /*
+   * A sentence for the settings table.
+   *
+   *   {}                                    -> "All devices"
+   *   { siteIds: [a, b] }                   -> "Devices in 2 sites"
+   *   { siteIds: [a], roles: [switch] }     -> "Devices in site Warehouse with role Switch"
+   *   { roles: [switch], labels: [prod] }   -> "Devices with role Switch and label Production"
+   *
+   * A single id whose name is known is named; anything else is counted. The
+   * count, never the id: an operator reading "in site 7f3c..." learns
+   * nothing, and "in 1 site" at least tells them to open the policy.
+   *
+   * "All devices" is deliberately blunt. It is the row that provisions a
+   * monitor for everything, and the wording should make somebody scanning
+   * the table stop on it.
+   */
+  public static describe(
+    scope: NetworkAlertPolicyScope | null | undefined,
+    names: NetworkAlertPolicyScopeNames = {},
+  ): string {
+    const normalized: NormalizedNetworkAlertPolicyScope =
+      NetworkAlertPolicyScopeUtil.normalize(
+        scope,
+      ) as NormalizedNetworkAlertPolicyScope;
+
+    if (NetworkAlertPolicyScopeUtil.isUnscoped(normalized)) {
+      return "All devices";
+    }
+
+    let sentence: string = "Devices";
+
+    if (normalized.siteIds.length > 0) {
+      sentence += ` in ${NetworkAlertPolicyScopeUtil.describeKind({
+        ids: normalized.siteIds,
+        names: names.sites,
+        singular: "site",
+        plural: "sites",
+      })}`;
+    }
+
+    const withClauses: Array<string> = [];
+
+    if (normalized.networkDeviceRoleIds.length > 0) {
+      withClauses.push(
+        NetworkAlertPolicyScopeUtil.describeKind({
+          ids: normalized.networkDeviceRoleIds,
+          names: names.roles,
+          singular: "role",
+          plural: "roles",
+        }),
+      );
+    }
+
+    if (normalized.labelIds.length > 0) {
+      withClauses.push(
+        NetworkAlertPolicyScopeUtil.describeKind({
+          ids: normalized.labelIds,
+          names: names.labels,
+          singular: "label",
+          plural: "labels",
+        }),
+      );
+    }
+
+    if (withClauses.length > 0) {
+      sentence += ` with ${withClauses.join(" and ")}`;
+    }
+
+    return sentence;
+  }
+
+  // "site Warehouse" when there is one id and a name for it; "2 sites" else.
+  private static describeKind(kind: ScopeKindDescription): string {
+    if (kind.ids.length === 1) {
+      const name: string = (kind.names?.[kind.ids[0] as string] || "").trim();
+
+      if (name) {
+        return `${kind.singular} ${name}`;
+      }
+    }
+
+    return `${kind.ids.length} ${
+      kind.ids.length === 1 ? kind.singular : kind.plural
+    }`;
+  }
+
+  /*
+   * One id list, cleaned. A lone string is one id (a client that sent
+   * `siteIds: "abc"` meant `["abc"]`); anything that is not a string or an
+   * array yields nothing. Inside an array only non-blank strings and
+   * ObjectID-shaped objects (which carry their id under `_id` / `id`) count,
+   * trimmed and deduplicated in first-seen order so the stored form is
+   * stable across saves.
+   */
+  private static readIdList(raw: unknown): Array<string> {
+    const candidates: Array<unknown> = Array.isArray(raw)
+      ? raw
+      : raw === undefined || raw === null
+        ? []
+        : [raw];
+
+    const ids: Array<string> = [];
+
+    for (const candidate of candidates) {
+      const id: string | null = NetworkAlertPolicyScopeUtil.readId(candidate);
+
+      if (id && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+
+    return ids;
+  }
+
+  private static readId(value: unknown): string | null {
+    if (typeof value === "string") {
+      const trimmed: string = value.trim();
+
+      return trimmed || null;
+    }
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const relation: { _id?: unknown; id?: unknown } = value as {
+        _id?: unknown;
+        id?: unknown;
+      };
+
+      const relationId: unknown = relation._id || relation.id;
+
+      if (typeof relationId === "string") {
+        const trimmed: string = relationId.trim();
+
+        return trimmed || null;
+      }
+    }
+
+    return null;
+  }
+
+  private static listHasId(
+    list: Array<string>,
+    id: string | null | undefined,
+  ): boolean {
+    const normalizedId: string | null = NetworkAlertPolicyScopeUtil.readId(id);
+
+    return normalizedId !== null && list.includes(normalizedId);
+  }
+}
+
+export default NetworkAlertPolicyScope;