@oneuptime/common 12.0.7 → 12.0.9

package/Types/OnCallDutyPolicy/ScheduleShiftUtil.ts

@@ -49,13 +49,55 @@ export interface CurrentAndNextShift {
 }
 
 /*
- * Two coverage segments are considered part of the same continuous shift when
- * the gap between them is below this threshold. LayerUtil starts each following
- * segment exactly one second after the previous one ends, so anything within a
- * couple of minutes is "touching"; anything larger is a genuine off-hours gap
- * (a restriction window closing, a rotation with no fallback layer, etc.).
+ * Why a schedule currently has (or does not have) somebody on call. The four
+ * states are mutually exclusive and ordered by how early the misconfiguration
+ * happens, so a caller can render the most specific remedy it knows about:
+ *
+ * - NoLayers      the schedule has no layers at all -> "add a layer"
+ * - NoUsers       layers exist but nobody is assigned to any of them, so the
+ *                 engine emits zero events and NOBODY is ever on call. This is
+ *                 a permanent 100% gap, not an off-hours one, and it needs its
+ *                 own remedy ("assign users") — telling someone to widen their
+ *                 active hours here would be wrong.
+ * - UncoveredNow  users are assigned and shifts exist, but none covers `now`
+ * - Covered       somebody is on call at this instant
  */
-const CONTIGUITY_TOLERANCE_SECONDS: number = 90;
+export enum ScheduleCoverageStatus {
+  NoLayers = "NoLayers",
+  NoUsers = "NoUsers",
+  UncoveredNow = "UncoveredNow",
+  Covered = "Covered",
+}
+
+export interface ScheduleCoverageState {
+  status: ScheduleCoverageStatus;
+  current: OnCallShift | null;
+  next: OnCallShift | null;
+  gaps: Array<CoverageGap>;
+  // Total uncovered seconds inside [now, windowEnd].
+  uncoveredSeconds: number;
+  /*
+   * Fraction of [now, windowEnd] that somebody is on call for, 0..1. 0 for both
+   * NoLayers and NoUsers; 1 for a schedule with no gaps at all.
+   */
+  coverageRatio: number;
+}
+
+/*
+ * Two coverage segments belong to the same continuous shift when the hole
+ * between them is at or below this threshold. LayerUtil starts each following
+ * segment exactly one second after the previous one ends (Layer.ts advances
+ * with addRemoveSeconds(end, 1)) and the multi-layer priority merge leaves
+ * seams of the same ±1s magnitude, so a few seconds of slack is all that is
+ * needed to absorb the engine's own artifacts.
+ *
+ * This used to be 90 seconds, which silently swallowed genuine sub-minute
+ * coverage holes — a schedule whose layers were misaligned by a minute
+ * reported full coverage. Anything above the engine artifact is a real hole and
+ * is now reported; callers that consider very short holes to be display noise
+ * filter them at the render layer (see getCoverageGaps' minimumGapSeconds).
+ */
+const CONTIGUITY_TOLERANCE_SECONDS: number = 5;
 
 export default class ScheduleShiftUtil {
   /*
@@ -191,6 +233,7 @@ export default class ScheduleShiftUtil {
     shifts: Array<OnCallShift>,
     windowStart: Date,
     windowEnd: Date,
+    options?: { minimumGapSeconds?: number | undefined } | undefined,
   ): Array<CoverageGap> {
     const gaps: Array<CoverageGap> = [];
 
@@ -199,18 +242,24 @@ export default class ScheduleShiftUtil {
     }
 
     /*
-     * A gap only "counts" when it is longer than the contiguity tolerance, so
+     * A hole only "counts" as a gap when it is longer than the threshold, so
      * the one-second boundaries LayerUtil leaves between segments never show up
-     * as spurious coverage holes.
+     * as spurious coverage holes. Callers that treat short holes as display
+     * noise (rather than as a misconfiguration worth reporting) raise
+     * minimumGapSeconds instead of relying on the detector to hide them.
      */
+    const minimumGapSeconds: number =
+      options?.minimumGapSeconds === undefined
+        ? CONTIGUITY_TOLERANCE_SECONDS
+        : options.minimumGapSeconds;
+
     const isRealGap: (start: Date, end: Date) => boolean = (
       start: Date,
       end: Date,
     ): boolean => {
       return (
         OneUptimeDate.isAfter(end, start) &&
-        OneUptimeDate.getDifferenceInSeconds(end, start) >
-          CONTIGUITY_TOLERANCE_SECONDS
+        OneUptimeDate.getDifferenceInSeconds(end, start) > minimumGapSeconds
       );
     };
 
@@ -254,4 +303,100 @@ export default class ScheduleShiftUtil {
 
     return gaps;
   }
+
+  /*
+   * The single source of truth for "does this schedule have anybody on call,
+   * and if not, why not". Every surface that renders coverage derives its state
+   * from here rather than inventing its own condition.
+   *
+   * This exists because the UI used to gate its gap warnings on
+   * `assignedUserCount > 0` — a condition that is exactly INVERTED, since zero
+   * assigned users IS the total-gap state. The one screen that would have said
+   * "nobody is on call" was therefore the one screen that never rendered.
+   * Returning an explicit status makes that class of mistake impossible: a
+   * caller must handle NoUsers, it cannot accidentally fall into "covered".
+   */
+  public static getCoverageState(data: {
+    layerCount: number;
+    assignedUserCount: number;
+    shifts: Array<OnCallShift>;
+    now: Date;
+    windowEnd: Date;
+    minimumGapSeconds?: number | undefined;
+  }): ScheduleCoverageState {
+    const { current, next }: CurrentAndNextShift = this.getCurrentAndNextShift(
+      data.shifts,
+      data.now,
+    );
+
+    const gaps: Array<CoverageGap> = this.getCoverageGaps(
+      data.shifts,
+      data.now,
+      data.windowEnd,
+      { minimumGapSeconds: data.minimumGapSeconds },
+    );
+
+    const uncoveredSeconds: number = gaps.reduce(
+      (total: number, gap: CoverageGap) => {
+        return total + OneUptimeDate.getDifferenceInSeconds(gap.end, gap.start);
+      },
+      0,
+    );
+
+    let status: ScheduleCoverageStatus = ScheduleCoverageStatus.Covered;
+
+    if (data.layerCount <= 0) {
+      status = ScheduleCoverageStatus.NoLayers;
+    } else if (data.assignedUserCount <= 0) {
+      status = ScheduleCoverageStatus.NoUsers;
+    } else if (!current) {
+      status = ScheduleCoverageStatus.UncoveredNow;
+    }
+
+    /*
+     * Test the window's ORDER explicitly rather than inferring it from the sign
+     * of the difference: OneUptimeDate.getDifferenceInSeconds returns an
+     * ABSOLUTE value, so an inverted window (windowEnd before now) yields a
+     * positive windowSeconds. Combined with getCoverageGaps bailing out on such
+     * a window and returning no gaps, the ratio then computed to a confident
+     * 1 — the function whose entire job is to surface missing coverage would
+     * report 100% covered. Fail to 0, never to "everything is fine".
+     */
+    const hasUsableWindow: boolean = OneUptimeDate.isBefore(
+      data.now,
+      data.windowEnd,
+    );
+
+    const windowSeconds: number = hasUsableWindow
+      ? OneUptimeDate.getDifferenceInSeconds(data.windowEnd, data.now)
+      : 0;
+
+    /*
+     * A schedule with no layers, or with layers but nobody assigned to them,
+     * can never put anyone on call — its coverage is 0 by definition, whatever
+     * shifts a caller happened to pass in. Deriving the ratio purely from those
+     * shifts would let a stale set report "100% covered" next to "no layers
+     * configured".
+     */
+    const canEverCover: boolean =
+      status !== ScheduleCoverageStatus.NoLayers &&
+      status !== ScheduleCoverageStatus.NoUsers;
+
+    const coverageRatio: number =
+      !hasUsableWindow || !canEverCover
+        ? 0
+        : Math.min(
+            1,
+            Math.max(0, (windowSeconds - uncoveredSeconds) / windowSeconds),
+          );
+
+    return {
+      status,
+      current,
+      next,
+      gaps,
+      uncoveredSeconds,
+      coverageRatio,
+    };
+  }
 }

package/Types/Permission.ts

@@ -1062,6 +1062,29 @@ enum Permission {
   DeleteProjectOnCallDutyPolicy = "DeleteProjectOnCallDutyPolicy",
   ReadProjectOnCallDutyPolicy = "ReadProjectOnCallDutyPolicy",
 
+  /*
+   * A project user's own on-call notification configuration - the rules that
+   * decide which of their verified methods a page reaches, and after how long.
+   *
+   * Every other permission in this family gates a resource the project owns.
+   * These two gate rows that belong to an individual member, which is why they
+   * exist separately rather than being folded into
+   * Read/EditProjectOnCallDutyPolicy: a policy says "page the on-call engineer",
+   * but whether that page actually arrives is decided by rows only that engineer
+   * could see or write. An unreachable teammate was therefore diagnosable by
+   * nobody but themselves, and the person carrying the incident had no way to
+   * find out before the page went unanswered.
+   *
+   * Read grants VISIBILITY of another member's rules and of the methods those
+   * rules point at - never the delivery token behind a method (see the column
+   * access control on UserWebhook and UserPush). Edit grants repair of the
+   * rules themselves. Neither grants the ability to add a notification method to
+   * somebody else's account; that asymmetry is deliberate and is explained on
+   * UserNotificationRule.
+   */
+  ReadProjectUserNotificationRule = "ReadProjectUserNotificationRule",
+  EditProjectUserNotificationRule = "EditProjectUserNotificationRule",
+
   // Resource Permissions (Team Permission)
   CreateProjectOnCallDutyPolicySchedule = "CreateProjectOnCallDutyPolicySchedule",
   EditProjectOnCallDutyPolicySchedule = "EditProjectOnCallDutyPolicySchedule",
@@ -1255,6 +1278,21 @@ enum Permission {
   EditNetworkSiteLink = "EditNetworkSiteLink",
   ReadNetworkSiteLink = "ReadNetworkSiteLink",
 
+  CreateNetworkDeviceLink = "CreateNetworkDeviceLink",
+  DeleteNetworkDeviceLink = "DeleteNetworkDeviceLink",
+  EditNetworkDeviceLink = "EditNetworkDeviceLink",
+  ReadNetworkDeviceLink = "ReadNetworkDeviceLink",
+
+  CreateNetworkDeviceLinkRule = "CreateNetworkDeviceLinkRule",
+  DeleteNetworkDeviceLinkRule = "DeleteNetworkDeviceLinkRule",
+  EditNetworkDeviceLinkRule = "EditNetworkDeviceLinkRule",
+  ReadNetworkDeviceLinkRule = "ReadNetworkDeviceLinkRule",
+
+  CreateNetworkTopologySuppression = "CreateNetworkTopologySuppression",
+  DeleteNetworkTopologySuppression = "DeleteNetworkTopologySuppression",
+  EditNetworkTopologySuppression = "EditNetworkTopologySuppression",
+  ReadNetworkTopologySuppression = "ReadNetworkTopologySuppression",
+
   CreateNetworkSiteAssignmentRule = "CreateNetworkSiteAssignmentRule",
   DeleteNetworkSiteAssignmentRule = "DeleteNetworkSiteAssignmentRule",
   EditNetworkSiteAssignmentRule = "EditNetworkSiteAssignmentRule",
@@ -5996,6 +6034,41 @@ export class PermissionHelper {
         group: PermissionGroup.OnCallDutyPolicy,
       },
 
+      /*
+       * isRolePermission is false on both of these deliberately, and it is not a
+       * stylistic choice. A true value would file them under
+       * getRolePermissionProps(), which is the list every default project role
+       * is built from - so the ability to read and rewrite a colleague's paging
+       * configuration would arrive silently with an existing role rather than
+       * being handed out on purpose. They are granular permissions an
+       * administrator opts into, held by nobody until somebody grants them.
+       *
+       * isAccessControlPermission is false because the rows these gate carry no
+       * label column; there is nothing for a label-scoped grant to narrow, and
+       * claiming otherwise would offer an administrator a scoping control that
+       * silently does nothing.
+       */
+      {
+        permission: Permission.ReadProjectUserNotificationRule,
+        title: "Read User Notification Rules",
+        description:
+          "This permission can read the on-call notification rules of any user in this project, and see which of their notification methods those rules point at. Delivery addresses are shown in a masked form and delivery credentials are never readable.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.OnCallDutyPolicy,
+      },
+      {
+        permission: Permission.EditProjectUserNotificationRule,
+        title: "Edit User Notification Rules",
+        description:
+          "This permission can create, edit and delete the on-call notification rules of any user in this project, in order to repair a member who would otherwise never be paged. It does not permit adding or changing a user's notification methods.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.OnCallDutyPolicy,
+      },
+
       {
         permission: Permission.CreateProjectOnCallDutyPolicySchedule,
         title: "Create On-Call Duty Policy Schedule",
@@ -7919,6 +7992,126 @@ export class PermissionHelper {
         isRolePermission: false,
         group: PermissionGroup.Monitor,
       },
+      {
+        permission: Permission.CreateNetworkDeviceLink,
+        title: "Create Network Device Link",
+        description:
+          "This permission can create Network Device Link in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkDeviceLink,
+        title: "Delete Network Device Link",
+        description:
+          "This permission can delete Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkDeviceLink,
+        title: "Edit Network Device Link",
+        description:
+          "This permission can edit Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkDeviceLink,
+        title: "Read Network Device Link",
+        description:
+          "This permission can read Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.CreateNetworkDeviceLinkRule,
+        title: "Create Network Device Link Rule",
+        description:
+          "This permission can create Network Device Link Rule in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkDeviceLinkRule,
+        title: "Delete Network Device Link Rule",
+        description:
+          "This permission can delete Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkDeviceLinkRule,
+        title: "Edit Network Device Link Rule",
+        description:
+          "This permission can edit Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkDeviceLinkRule,
+        title: "Read Network Device Link Rule",
+        description:
+          "This permission can read Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.CreateNetworkTopologySuppression,
+        title: "Create Network Topology Suppression",
+        description:
+          "This permission can hide nodes from the Network Topology map in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkTopologySuppression,
+        title: "Delete Network Topology Suppression",
+        description:
+          "This permission can restore hidden nodes to the Network Topology map of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkTopologySuppression,
+        title: "Edit Network Topology Suppression",
+        description:
+          "This permission can edit Network Topology Suppression of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkTopologySuppression,
+        title: "Read Network Topology Suppression",
+        description:
+          "This permission can read Network Topology Suppression of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
       {
         permission: Permission.CreateNetworkSiteAssignmentRule,
         title: "Create Network Site Assignment Rule",

package/Types/SerializableObjectDictionary.ts

@@ -40,46 +40,140 @@ import Phone from "./Phone";
 import Port from "./Port";
 import Version from "./Version";
 
+/*
+ * Every entry is a getter, not a direct reference.
+ *
+ * Three of these classes — Includes, IncludesAll and IncludesNone — import
+ * JSONFunctions so their fromJSON can deserialize the values inside them, and
+ * JSONFunctions imports this dictionary. That is a cycle, and with a plain
+ * object literal the entry a cycle passes through is captured as `undefined`:
+ * whichever of the two modules loads second sees the first only half
+ * initialized. Which of them loads first depends on the whole app's import
+ * graph, so `{"_type":"Includes","value":[...]}` deserialized into a real
+ * Includes in some entry points and stayed a plain object in others — and a
+ * plain object reaching TypeORM is a silently wrong query, not an error.
+ *
+ * A getter defers the lookup to the first property access, by which time every
+ * module has finished initializing.
+ */
 const SerializableObjectDictionary: Dictionary<any> = {
-  [ObjectType.Phone]: Phone,
-  [ObjectType.DateTime]: OneUptimeDate,
-  [ObjectType.ObjectID]: ObjectID,
-  [ObjectType.Name]: Name,
-  [ObjectType.EqualTo]: EqualTo,
-  [ObjectType.EqualToOrNull]: EqualToOrNull,
-  [ObjectType.MonitorSteps]: MonitorSteps,
-  [ObjectType.MonitorStep]: MonitorStep,
-  [ObjectType.MonitorCriteria]: MonitorCriteria,
-  [ObjectType.MonitorCriteriaInstance]: MonitorCriteriaInstance,
-  [ObjectType.NotEqual]: NotEqual,
-  [ObjectType.Email]: Email,
-  [ObjectType.Color]: Color,
-  [ObjectType.Domain]: Domain,
-  [ObjectType.Version]: Version,
-  [ObjectType.Route]: Route,
-  [ObjectType.URL]: URL,
-  [ObjectType.IP]: IP,
-  [ObjectType.Search]: Search,
-  [ObjectType.MultiSearch]: MultiSearch,
-  [ObjectType.GreaterThan]: GreaterThan,
-  [ObjectType.GreaterThanOrEqual]: GreaterThanOrEqual,
-  [ObjectType.LessThan]: LessThan,
-  [ObjectType.LessThanOrEqual]: LessThanOrEqual,
-  [ObjectType.LessThanOrNull]: LessThanOrNull,
-  [ObjectType.GreaterThanOrNull]: GreaterThanOrNull,
-  [ObjectType.Port]: Port,
-  [ObjectType.Hostname]: Hostname,
-  [ObjectType.HashedString]: HashedString,
-  [ObjectType.InBetween]: InBetween,
-  [ObjectType.Includes]: Includes,
-  [ObjectType.IncludesAll]: IncludesAll,
-  [ObjectType.IncludesNone]: IncludesNone,
-  [ObjectType.StartsWith]: StartsWith,
-  [ObjectType.EndsWith]: EndsWith,
-  [ObjectType.NotContains]: NotContains,
-  [ObjectType.NotNull]: NotNull,
-  [ObjectType.IsNull]: IsNull,
-  [ObjectType.Recurring]: Recurring,
+  get [ObjectType.Phone](): any {
+    return Phone;
+  },
+  get [ObjectType.DateTime](): any {
+    return OneUptimeDate;
+  },
+  get [ObjectType.ObjectID](): any {
+    return ObjectID;
+  },
+  get [ObjectType.Name](): any {
+    return Name;
+  },
+  get [ObjectType.EqualTo](): any {
+    return EqualTo;
+  },
+  get [ObjectType.EqualToOrNull](): any {
+    return EqualToOrNull;
+  },
+  get [ObjectType.MonitorSteps](): any {
+    return MonitorSteps;
+  },
+  get [ObjectType.MonitorStep](): any {
+    return MonitorStep;
+  },
+  get [ObjectType.MonitorCriteria](): any {
+    return MonitorCriteria;
+  },
+  get [ObjectType.MonitorCriteriaInstance](): any {
+    return MonitorCriteriaInstance;
+  },
+  get [ObjectType.NotEqual](): any {
+    return NotEqual;
+  },
+  get [ObjectType.Email](): any {
+    return Email;
+  },
+  get [ObjectType.Color](): any {
+    return Color;
+  },
+  get [ObjectType.Domain](): any {
+    return Domain;
+  },
+  get [ObjectType.Version](): any {
+    return Version;
+  },
+  get [ObjectType.Route](): any {
+    return Route;
+  },
+  get [ObjectType.URL](): any {
+    return URL;
+  },
+  get [ObjectType.IP](): any {
+    return IP;
+  },
+  get [ObjectType.Search](): any {
+    return Search;
+  },
+  get [ObjectType.MultiSearch](): any {
+    return MultiSearch;
+  },
+  get [ObjectType.GreaterThan](): any {
+    return GreaterThan;
+  },
+  get [ObjectType.GreaterThanOrEqual](): any {
+    return GreaterThanOrEqual;
+  },
+  get [ObjectType.LessThan](): any {
+    return LessThan;
+  },
+  get [ObjectType.LessThanOrEqual](): any {
+    return LessThanOrEqual;
+  },
+  get [ObjectType.LessThanOrNull](): any {
+    return LessThanOrNull;
+  },
+  get [ObjectType.GreaterThanOrNull](): any {
+    return GreaterThanOrNull;
+  },
+  get [ObjectType.Port](): any {
+    return Port;
+  },
+  get [ObjectType.Hostname](): any {
+    return Hostname;
+  },
+  get [ObjectType.HashedString](): any {
+    return HashedString;
+  },
+  get [ObjectType.InBetween](): any {
+    return InBetween;
+  },
+  get [ObjectType.Includes](): any {
+    return Includes;
+  },
+  get [ObjectType.IncludesAll](): any {
+    return IncludesAll;
+  },
+  get [ObjectType.IncludesNone](): any {
+    return IncludesNone;
+  },
+  get [ObjectType.StartsWith](): any {
+    return StartsWith;
+  },
+  get [ObjectType.EndsWith](): any {
+    return EndsWith;
+  },
+  get [ObjectType.NotContains](): any {
+    return NotContains;
+  },
+  get [ObjectType.NotNull](): any {
+    return NotNull;
+  },
+  get [ObjectType.IsNull](): any {
+    return IsNull;
+  },
+  get [ObjectType.Recurring](): any {
+    return Recurring;
+  },
 };
 
 export default SerializableObjectDictionary;

package/Types/Telemetry/EntityRelationshipType.ts

@@ -23,7 +23,7 @@ enum EntityRelationshipType {
    * this is NOT inferred from one resource's entity set — caller and
    * callee never share a resource. It is derived from parent/child span
    * pairs that cross a service boundary (see the
-   * TelemetryEntity:ComputeServiceDependencies worker cron).
+   * InventoryItem:ComputeServiceDependencies worker cron).
    */
   DependsOn = "depends-on",
 }

package/Types/Telemetry/EntitySource.ts

@@ -0,0 +1,40 @@
+/*
+ * How a `InventoryItem` registry row came to exist. The registry started
+ * as a forward-only catalog populated purely from OTLP resource attributes;
+ * two later sources join it, and the three differ in exactly one way that
+ * matters — who owns the row's lifecycle.
+ *
+ * That ownership is what `PruneStaleEntities` keys on. It reaps rows whose
+ * `lastSeenAt` has aged past their type's TTL, which is only a correct
+ * staleness signal when something is actively re-bumping `lastSeenAt`. Two
+ * of the three sources have nothing doing that, so the prune sweep is
+ * scoped to `Discovered` alone — see the guard there.
+ */
+enum EntitySource {
+  /**
+   * Derived from telemetry resource attributes at ingest and re-bumped on
+   * every reconcile window for as long as the entity keeps emitting. Silence
+   * past the type's TTL genuinely means gone, so these are TTL-pruned.
+   */
+  Discovered = "discovered",
+
+  /**
+   * Mirrored from a OneUptime inventory table (NetworkDevice, CloudResource,
+   * IoTDevice, ...). These are collected by pollers rather than OTLP, so no
+   * ingest path bumps `lastSeenAt` — the owning row IS the liveness signal,
+   * and the mirror is kept in step by that table's create/delete hooks. TTL
+   * pruning one of these would delete the registry row for a device that is
+   * still very much registered.
+   */
+  Inventory = "inventory",
+
+  /**
+   * Created by a user for something that emits no telemetry at all — a
+   * third-party API, a vendor-managed database, an appliance. Nothing will
+   * ever bump `lastSeenAt`, so these are never TTL-pruned; they live until
+   * the user deletes them.
+   */
+  Manual = "manual",
+}
+
+export default EntitySource;