Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

39.4 KB
Raw Blame
// Properly typed TypeScript interfaces for Pulse API

import type { Resource, ResourceCapability, ResourcePolicy, ResourceChange } from './resource';
import type { EvidenceEnvelope, LifecycleTransition, OperationalRecord } from './operationalTrust';

/** Client-only binding for RBAC administration; these are not JSON payload fields. */
export interface RBACAdminRequestOptions {
  signal?: AbortSignal;
  expectedOrgID?: string;
  retry?: boolean;
}

export interface ResourceListFacetsPayload {
  byType?: Partial<Record<string, number>>;
  incidentCount?: number;
}

export interface APITokenRecord {
  id: string;
  name: string;
  prefix: string;
  suffix: string;
  createdAt: string;
  lastUsedAt?: string;
  expiresAt?: string;
  scopes?: string[];
  ownerUserId?: string;
}

export interface State {
  // Canonical v6 resource contract.
  // Platform entities (nodes, guests, agents, storage, PBS/PMG, etc.) are modeled in `resources`.
  connectedInfrastructure: ConnectedInfrastructureItem[];
  metrics: Metric[];
  performance: Performance;
  connectionHealth: Record<string, boolean>;
  stats: Stats;
  activeAlerts: Alert[];
  recentlyResolved: ResolvedAlert[];
  lastUpdate: number;
  temperatureMonitoringEnabled?: boolean;
  pveTagColors: Record<string, string>;
  pveTagStyles?: Record<string, PVETagStyle>;
  // Unified resources (canonical resource model)
  resources: Resource[];
  // Distinct capability blobs referenced by Resource.capabilitiesRef; the
  // websocket store expands refs into inline capabilities at ingestion.
  capabilityCatalog?: Record<string, ResourceCapability[]> | null;
  // Distinct non-default policy postures and templated AI-safe summaries
  // referenced by Resource.policyRef / Resource.aiSafeSummaryRef.
  policyCatalog?: Record<string, ResourcePolicy> | null;
  aiSafeSummaryCatalog?: Record<string, string> | null;
}

export interface ResourceStateDelta {
  upserts?: Array<Partial<Resource> & Pick<Resource, 'id'>>;
  removed?: string[];
  order?: string[];
}

export type StateUpdate = Partial<State> & {
  resourceDelta?: ResourceStateDelta;
};

export interface PVETagStyle {
  colors: Record<string, string>;
  caseSensitive: boolean;
}

export interface ConnectedInfrastructureSurface {
  id: string;
  kind: 'agent' | 'availability' | 'docker' | 'kubernetes' | 'proxmox' | 'pbs' | 'pmg' | 'truenas';
  label: string;
  detail?: string;
  controlId?: string;
  action?: 'stop-monitoring' | 'allow-reconnect';
  idLabel?: string;
  idValue?: string;
}

export interface ConnectedInfrastructureItem {
  id: string;
  name: string;
  displayName?: string;
  hostname?: string;
  status: 'active' | 'ignored';
  healthStatus?: string;
  lastSeen?: number;
  removedAt?: number;
  version?: string;
  isOutdatedBinary?: boolean;
  linkedNodeId?: string;
  linkedVmId?: string;
  linkedContainerId?: string;
  commandsEnabled?: boolean;
  scopeAgentId?: string;
  upgradePlatform?: 'linux' | 'macos' | 'freebsd' | 'windows';
  uninstallAgentId?: string;
  uninstallHostname?: string;
  surfaces: ConnectedInfrastructureSurface[];
}

export interface KubernetesNode {
  uid: string;
  name: string;
  ready: boolean;
  unschedulable?: boolean;
  kubeletVersion?: string;
  containerRuntimeVersion?: string;
  osImage?: string;
  kernelVersion?: string;
  architecture?: string;
  capacityCpuCores?: number;
  capacityMemoryBytes?: number;
  capacityPods?: number;
  allocatableCpuCores?: number;
  allocatableMemoryBytes?: number;
  allocatablePods?: number;
  roles?: string[];
}

export interface KubernetesPodContainer {
  name: string;
  image?: string;
  ready: boolean;
  restartCount?: number;
  state?: string;
  reason?: string;
  message?: string;
}

export interface KubernetesPod {
  uid: string;
  name: string;
  namespace: string;
  nodeName?: string;
  phase?: string;
  reason?: string;
  message?: string;
  qosClass?: string;
  createdAt?: number;
  startTime?: number;
  restarts?: number;
  labels?: Record<string, string>;
  ownerKind?: string;
  ownerName?: string;
  containers?: KubernetesPodContainer[];
}

export interface KubernetesDeployment {
  uid: string;
  name: string;
  namespace: string;
  desiredReplicas?: number;
  updatedReplicas?: number;
  readyReplicas?: number;
  availableReplicas?: number;
  labels?: Record<string, string>;
}

export interface Node {
  metricsTarget?: Resource['metricsTarget'];
  id: string;
  name: string;
  displayName?: string;
  instance: string;
  host: string;
  guestURL?: string; // Optional guest-accessible URL (for navigation)
  status: string;
  type: string;
  cpu: number;
  memory: Memory;
  disk: Disk;
  networkIn?: number;
  networkOut?: number;
  diskRead?: number;
  diskWrite?: number;
  networkInterfaces?: HostNetworkInterface[];
  uptime: number;
  loadAverage: number[];
  kernelVersion: string;
  pveVersion: string;
  cpuInfo: CPUInfo;
  /** Typed telemetry from a linked Unified Agent, when this PVE node is hybrid. */
  sensors?: HostSensorSummary;
  /** Client-only projection of the linked agent's reporting lease, not PVE API health. */
  sensorsStale?: boolean;
  temperature?: Temperature; // CPU/NVMe temperatures
  /**
   * The node's primary CPU temperature in Celsius, chosen by the backend
   * (models.PrimaryCPUTemperatureCelsius) and recorded under the same rule in
   * the node's history. Show this value; never recompute it from `temperature`.
   */
  cpuTemperature?: number;
  temperatureMonitoringEnabled?: boolean | null; // Per-node temperature monitoring override
  pendingUpdates?: number; // Number of pending apt updates
  pendingUpdatesCheckedAt?: string; // When updates were last checked
  pendingUpdatesStatus?: 'checked' | 'stale' | 'unavailable' | 'not_checked';
  pendingUpdatesReason?:
    'permission_denied' | 'source_unavailable' | 'check_failed' | 'node_offline';
  lastSeen: string;
  connectionHealth: string;
  isClusterMember?: boolean; // True if part of a cluster
  clusterName?: string; // Name of cluster (empty if standalone)
  linkedAgentId?: string; // ID of Pulse agent running on this node (for merging)
}

export interface GuestNetworkInterface {
  name?: string;
  mac?: string;
  addresses?: string[];
  rxBytes?: number;
  txBytes?: number;
}

export interface VM {
  id: string;
  vmid: number;
  name: string;
  node: string;
  pool?: string;
  instance: string;
  status: string;
  type: string;
  cpu: number;
  cpus: number;
  memory: Memory;
  disk: Disk;
  disks?: Disk[];
  diskStatusReason?: string;
  guestAgentStatus?: string;
  guestAgentExpected?: boolean;
  ipAddresses?: string[];
  osName?: string;
  osVersion?: string;
  agentVersion?: string;
  networkInterfaces?: GuestNetworkInterface[];
  networkIn: number;
  networkOut: number;
  diskRead: number;
  diskWrite: number;
  uptime: number;
  template: boolean;
  lastBackup: number;
  /** A backup of this guest is running right now; lastBackup still points at the latest completed backup. */
  backupInProgress?: boolean;
  tags: string[] | string | null;
  lock: string;
  lastSeen: string;
}

export interface Container {
  id: string;
  vmid: number;
  name: string;
  node: string;
  pool?: string;
  instance: string;
  status: string;
  type: string;
  cpu: number;
  cpus: number;
  memory: Memory;
  disk: Disk;
  disks?: Disk[];
  ipAddresses?: string[];
  osName?: string;
  osVersion?: string;
  agentVersion?: string;
  networkInterfaces?: GuestNetworkInterface[];
  networkIn: number;
  networkOut: number;
  diskRead: number;
  diskWrite: number;
  uptime: number;
  template: boolean;
  lastBackup: number;
  /** A backup of this guest is running right now; lastBackup still points at the latest completed backup. */
  backupInProgress?: boolean;
  tags: string[] | string | null;
  lock: string;
  lastSeen: string;
  // OCI container support (Proxmox VE 9.1+)
  isOci?: boolean; // True if this is an OCI container
  osTemplate?: string; // Template or OCI image used (e.g., "oci:docker.io/library/alpine:latest")
}

export interface DockerRuntime {
  id: string;
  agentId: string;
  hostname: string;
  displayName: string;
  customDisplayName?: string;
  machineId?: string;
  os?: string;
  kernelVersion?: string;
  architecture?: string;
  runtime?: string;
  runtimeVersion?: string;
  dockerVersion?: string;
  collectionMode?: string;
  cpus: number;
  totalMemoryBytes: number;
  uptimeSeconds: number;
  cpuUsagePercent?: number;
  loadAverage?: number[];
  memory?: Memory;
  disks?: Disk[];
  networkInterfaces?: HostNetworkInterface[];
  status: string;
  lastSeen: number;
  intervalSeconds: number;
  agentVersion?: string;
  containers: DockerContainer[];
  services?: DockerService[];
  tasks?: DockerTask[];
  swarm?: DockerSwarmInfo;
  tokenId?: string;
  tokenName?: string;
  tokenHint?: string;
  tokenLastUsedAt?: number;
  revokedTokenId?: string;
  tokenRevokedAt?: number;
  hidden?: boolean;
  pendingUninstall?: boolean;
  command?: DockerRuntimeCommand;
  isLegacy?: boolean;
}

export interface DockerRuntimeCommand {
  id: string;
  type: string;
  status: string;
  message?: string;
  createdAt: number;
  updatedAt: number;
  dispatchedAt?: number;
  acknowledgedAt?: number;
  completedAt?: number;
  failedAt?: number;
  failureReason?: string;
  expiresAt?: number;
}

export interface DockerService {
  id: string;
  name: string;
  stack?: string;
  image?: string;
  mode?: string;
  desiredTasks?: number;
  runningTasks?: number;
  completedTasks?: number;
  labels?: Record<string, string>;
  endpointPorts?: DockerServicePort[];
  updateStatus?: DockerServiceUpdate;
  createdAt?: number;
  updatedAt?: number;
}

export interface DockerServicePort {
  name?: string;
  protocol?: string;
  targetPort?: number;
  publishedPort?: number;
  publishMode?: string;
}

export interface DockerServiceUpdate {
  state?: string;
  message?: string;
  completedAt?: number;
}

export interface DockerTask {
  id: string;
  serviceId?: string;
  serviceName?: string;
  slot?: number;
  nodeId?: string;
  nodeName?: string;
  desiredState?: string;
  currentState?: string;
  error?: string;
  message?: string;
  containerId?: string;
  containerName?: string;
  createdAt?: number | string; // Unix timestamp or ISO string
  updatedAt?: number | string; // Unix timestamp or ISO string
  startedAt?: number | string; // Unix timestamp or ISO string
  completedAt?: number | string; // Unix timestamp or ISO string
}

export interface DockerSwarmInfo {
  nodeId?: string;
  nodeRole?: string;
  localState?: string;
  controlAvailable?: boolean;
  clusterId?: string;
  clusterName?: string;
  scope?: string;
  error?: string;
}

export interface DockerContainer {
  id: string;
  name: string;
  image: string;
  imageDigest?: string; // Current image digest (sha256:...)
  state: string;
  status: string;
  health?: string;
  cpuPercent: number;
  memoryUsageBytes: number;
  memoryLimitBytes: number;
  memoryPercent: number;
  uptimeSeconds: number;
  restartCount: number;
  exitCode: number;
  createdAt: number;
  startedAt?: number | null;
  finishedAt?: number | null;
  ports?: DockerContainerPort[];
  labels?: Record<string, string>;
  env?: string[];
  networks?: DockerContainerNetwork[];
  writableLayerBytes?: number;
  rootFilesystemBytes?: number;
  blockIo?: DockerContainerBlockIO;
  mounts?: DockerContainerMount[];
  podman?: PodmanContainerMetadata;
  updateStatus?: DockerContainerUpdateStatus; // Image update detection status
}

// Update status for container images
export interface DockerContainerUpdateStatus {
  updateAvailable: boolean;
  currentDigest?: string;
  latestDigest?: string;
  lastChecked: number;
  error?: string;
}

export interface DockerContainerPort {
  privatePort: number;
  publicPort?: number;
  protocol: string;
  ip?: string;
}

export interface DockerContainerNetwork {
  name: string;
  ipv4?: string;
  ipv6?: string;
}

export interface DockerContainerBlockIO {
  readBytes?: number;
  writeBytes?: number;
  readRateBytesPerSecond?: number;
  writeRateBytesPerSecond?: number;
}

export interface DockerContainerMount {
  type?: string;
  source?: string;
  destination?: string;
  mode?: string;
  rw?: boolean;
  propagation?: string;
  name?: string;
  driver?: string;
}

export interface PodmanContainerMetadata {
  podName?: string;
  podId?: string;
  infra?: boolean;
  composeProject?: string;
  composeService?: string;
  composeWorkdir?: string;
  composeConfigHash?: string;
  autoUpdatePolicy?: string;
  autoUpdateRestart?: string;
  userNamespace?: string;
}

export interface Agent {
  id: string;
  hostname: string;
  displayName: string;
  platform?: string;
  osName?: string;
  osVersion?: string;
  kernelVersion?: string;
  architecture?: string;
  cpuCount?: number;
  cpuUsage?: number;
  loadAverage?: number[];
  memory: Memory;
  disks?: Disk[];
  diskIO?: HostDiskIO[];
  networkInterfaces?: HostNetworkInterface[];
  sensors?: HostSensorSummary;
  raid?: HostRAIDArray[];
  status: string;
  uptimeSeconds?: number;
  lastSeen: number;
  intervalSeconds?: number;
  agentVersion?: string;
  commandsEnabled?: boolean; // Whether AI command execution is enabled on this agent
  appliedConfig?: AgentConfigFingerprint;
  agentUpdate?: AgentUpdateStatus;
  agentModules?: AgentModuleStatus[];
  packageUpdates?: HostPackageUpdateStatus;
  storageCleanup?: HostStorageCleanupStatus;
  tokenId?: string;
  tokenName?: string;
  tokenHint?: string;
  tokenLastUsedAt?: number;
  revokedTokenId?: string;
  tokenRevokedAt?: number;
  tags?: string[];
  isLegacy?: boolean;
  // Linking: When this agent is running on a known PVE entity
  linkedNodeId?: string; // ID of PVE node this agent is running on
  linkedVmId?: string; // ID of VM this agent is running inside
  linkedContainerId?: string; // ID of container this agent is running inside
}

export interface HostPackageUpdateStatus {
  supported: boolean;
  manager?: string;
  inventoryHash?: string;
  pendingCount: number;
  packages?: HostPackageUpdate[];
  checkedAt?: string;
  rebootRequired?: boolean;
  error?: string;
}

export interface HostPackageUpdate {
  name: string;
  installedVersion?: string;
  availableVersion?: string;
}

export interface HostStorageCleanupStatus {
  supported: boolean;
  provider?: string;
  fingerprint?: string;
  reclaimableBytes: number;
  checkedAt?: string;
  error?: string;
}

export interface AgentConfigFingerprint {
  version: string;
  hash: string;
}

export interface AgentUpdateStatus {
  state: 'idle' | 'checking' | 'update-available' | 'updating' | 'error' | 'disabled';
  autoUpdate: boolean;
  updatedFrom?: string;
  availableVersion?: string;
  lastCheckedAt?: string;
  lastAttemptAt?: string;
  lastSuccessAt?: string;
  lastError?: string;
}

export interface AgentModuleStatus {
  name: string;
  enabled: boolean;
  state: 'disabled' | 'starting' | 'retrying' | 'running';
  lastError?: string;
  updatedAt: string;
}

export interface HostNetworkInterface {
  name: string;
  mac?: string;
  addresses?: string[];
  rxBytes?: number;
  txBytes?: number;
  speedMbps?: number;
}

export interface HostSensorSummary {
  temperatureCelsius?: Record<string, number>;
  fanRpm?: Record<string, number>;
  powerWatts?: Record<string, number>;
  additional?: Record<string, number>;
  custom?: HostCustomSensorMetric[];
  native?: HostNativeSensor[];
  gpu?: HostGPUSensor[];
  thermalState?: HostThermalState;
  smart?: HostDiskSMART[]; // S.M.A.R.T. disk data
}

/**
 * One lm-sensors temperature or fan input from the host agent's inventory.
 * `id` is the host-scoped "<chip>/<channel>" source key (e.g.
 * "applesmc-isa-0300/temp1"), not a physical-device identity; `label` is the
 * chip's original feature name and is not unique. `invalid` marks an
 * implausible reading, and `value` is absent when the chip gave no number.
 */
export interface HostNativeSensor {
  id: string;
  chip: string;
  adapter?: string;
  channel: string;
  label: string;
  kind: 'temperature' | 'fan';
  unit: 'celsius' | 'rpm';
  value?: number;
  status: 'ok' | 'invalid';
}

export interface HostCustomSensorMetric {
  id: string;
  name: string;
  group?: string;
  subgroup?: string;
  kind?: 'number' | 'boolean' | 'timestamp' | string;
  unit?: string;
  value?: number;
  status: 'ok' | 'warning' | 'critical' | 'error' | string;
  observedAt: string;
  eventAt?: string;
  error?: string;
  alertOnError?: boolean;
  stale?: boolean;
}

export interface HostGPUSensor {
  id?: string;
  name?: string;
  temperatureCelsius?: number;
  utilizationPercent?: number;
  memoryUsedBytes?: number;
  memoryTotalBytes?: number;
}

export interface HostThermalState {
  source?: string;
  pressure?: 'nominal' | 'constrained' | 'unknown' | string;
  thermalWarningLevel?: number;
  performanceWarningLevel?: number;
  cpuPowerStatus?: number;
  limitsPercent?: Record<string, number>;
}

export interface HostDiskSMART {
  device: string; // Device name (e.g., sda)
  model?: string; // Disk model
  serial?: string; // Serial number
  wwn?: string; // World Wide Name
  type?: string; // Transport type: sata, sas, nvme
  temperature: number; // Temperature in Celsius
  health?: string; // PASSED, FAILED, UNKNOWN
  standby?: boolean; // True if disk was in standby
  // A non-available temperature state marks the value as last known, such as
  // a host agent that stopped reporting.
  collection?: import('./resource').PhysicalDiskCollectionStatus;
}

export interface HostRAIDArray {
  device: string;
  name?: string;
  level: string;
  state: string;
  totalDevices: number;
  activeDevices: number;
  workingDevices: number;
  failedDevices: number;
  spareDevices: number;
  uuid?: string;
  devices?: HostRAIDDevice[];
  rebuildPercent?: number;
  rebuildSpeed?: string;
}

export interface HostRAIDDevice {
  device: string;
  state: string;
  slot: number;
}

export interface HostDiskIO {
  device: string;
  readBytes?: number;
  writeBytes?: number;
  readOps?: number;
  writeOps?: number;
  readTimeMs?: number;
  writeTimeMs?: number;
  ioTimeMs?: number;
}

export interface AgentLookupIdentity {
  id: string;
  hostname: string;
  displayName?: string;
  status: string;
  connected: boolean;
  lastSeen: number;
  agentVersion?: string;
}

export interface AgentLookupResponse {
  success: boolean;
  agent?: AgentLookupIdentity;
}

export interface ReplicationJob {
  id: string;
  instance: string;
  jobId: string;
  jobNumber?: number;
  guest?: string;
  guestId?: number;
  guestName?: string;
  guestType?: string;
  guestNode?: string;
  sourceNode?: string;
  sourceStorage?: string;
  targetNode?: string;
  targetStorage?: string;
  schedule?: string;
  type?: string;
  enabled: boolean;
  state?: string;
  status?: string;
  lastSyncStatus?: string;
  // The Go model serializes *time.Time fields as RFC3339 strings; the
  // *Unix companions carry the same instants as epoch seconds.
  lastSyncTime?: number | string;
  lastSyncUnix?: number;
  lastSyncDurationSeconds?: number;
  lastSyncDurationHuman?: string;
  nextSyncTime?: number | string;
  nextSyncUnix?: number;
  durationSeconds?: number;
  durationHuman?: string;
  failCount?: number;
  error?: string;
  comment?: string;
  removeJob?: string;
  rateLimitMbps?: number;
  polledAt?: number;
}

export interface ReplicationJobsResponse {
  data: ReplicationJob[];
  meta: { total: number };
}

export interface BackupTask {
  id: string;
  node: string;
  instance: string;
  type: string;
  vmid: number;
  status: string;
  startTime: string;
  endTime?: string;
  size?: number;
  error?: string;
}

export interface StorageBackup {
  id: string;
  storage: string;
  node: string;
  instance: string;
  type: string;
  vmid: number;
  time: string;
  ctime: number;
  size: number;
  format: string;
  notes?: string;
  protected: boolean;
  volid: string;
  isPBS: boolean;
  verified: boolean;
  verification?: string;
  /** Partial artifact a still-running backup is writing; not a completed backup. */
  inProgress?: boolean;
}

export interface GuestSnapshot {
  id: string;
  name: string;
  node: string;
  instance: string;
  type: string;
  vmid: number;
  time: string;
  description?: string;
  parent?: string;
  vmstate: boolean;
  sizeBytes?: number;
}

export interface PBSBackup {
  id: string;
  instance: string;
  datastore: string;
  namespace: string;
  backupType: string;
  vmid: string;
  backupTime: string;
  size: number;
  protected: boolean;
  verified: boolean;
  /** Incomplete snapshot with no manifest; never a completed backup. */
  inProgress?: boolean;
  /** Whether the collector successfully observed PBS's current running-task set. */
  writeActivityObserved?: boolean;
  /** Whether a running backup or sync task currently accounts for this incomplete snapshot. */
  writeActive?: boolean;
  verificationRaw?: unknown;
  comment?: string;
  files: string[];
  owner?: string;
}

export interface PBSBackupsPayload {
  backups: PBSBackup[];
}

export interface PBSBackupsResponse {
  data: PBSBackupsPayload;
  meta: {
    totalBackups: number;
  };
}

export interface PVEBackupsPayload {
  backupTasks: BackupTask[];
  storageBackups: StorageBackup[];
  guestSnapshots: GuestSnapshot[];
}

export interface PVEBackupsResponse {
  data: PVEBackupsPayload;
  meta: {
    totalBackupTasks: number;
    totalStorageBackups: number;
    totalGuestSnapshots: number;
  };
}

export interface Storage {
  id: string;
  name: string;
  node: string;
  instance: string;
  type: string;
  status: string;
  total: number;
  used: number;
  free: number;
  usage: number;
  content: string;
  shared: boolean;
  enabled: boolean;
  active: boolean;
  // RFC3339 timestamp of the last poll that delivered this entry; absent = never seen
  lastSeen?: string;
  // Added for deduplication in storage view
  nodes?: string[];
  nodeIds?: string[];
  nodeCount?: number;
  pbsNames?: string[];
  pool?: string;
  // Canonical platform key (e.g. `vmware-vsphere`, `truenas`, `proxmox-pve`)
  // set by source adapters that know what platform owns the storage
  // record. Storage filter chips and platform-page source filters
  // resolve against this when present, so on-disk `type` like `vsan`
  // or `vmfs` does not silently bucket VMware datastores under their
  // technology label instead of the canonical platform.
  platform?: string;
  // ZFS pool status
  zfsPool?: ZFSPool;
}

export interface CephCluster {
  id: string;
  instance: string;
  name: string;
  fsid?: string;
  health: string;
  healthMessage?: string;
  totalBytes: number;
  usedBytes: number;
  availableBytes: number;
  usagePercent: number;
  numMons: number;
  numMgrs: number;
  numOsds: number;
  numOsdsUp: number;
  numOsdsIn: number;
  numPGs: number;
  pools?: CephPool[];
  services?: CephServiceStatus[];
  lastUpdated: number;
}

export interface CephPool {
  id: number;
  name: string;
  storedBytes: number;
  availableBytes: number;
  objects: number;
  percentUsed: number;
}

export interface CephServiceStatus {
  type: string;
  running: number;
  total: number;
  message?: string;
}

export interface ZFSPool {
  name: string;
  state: string; // ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL
  status: string; // Healthy, Degraded, Faulted, etc.
  scan: string; // Current scan status (scrub, resilver, none)
  scanDetails?: ZFSScan;
  readErrors: number;
  writeErrors: number;
  checksumErrors: number;
  devices: ZFSDevice[];
  datasets?: ZFSDataset[];
}

export interface ZFSDataset {
  name: string;
  type?: 'filesystem' | 'volume' | string;
  mountpoint?: string;
  usedBytes?: number;
  availableBytes?: number;
  referencedBytes?: number;
}

export interface ZFSScan {
  function?: string;
  state?: string;
  percentage?: number;
  errors?: number;
  bytesExamined?: number;
  bytesToProcess?: number;
  totalSecondsRemaining?: number;
  startedAt?: string;
  endedAt?: string;
}

export interface ZFSDevice {
  name: string;
  type: string; // disk, mirror, raidz, raidz2, raidz3, spare, log, cache
  role?: string;
  parent?: string;
  guid?: string;
  disk?: string;
  path?: string;
  state: string; // ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL
  readErrors: number;
  writeErrors: number;
  checksumErrors: number;
  missing?: boolean;
  message?: string;
}

export interface PBSInstance {
  id: string;
  name: string;
  host: string;
  nodeName?: string; // Hostname the PBS node reports about itself
  guestURL?: string; // Optional guest-accessible URL (for navigation)
  status: string;
  version: string;
  cpu: number;
  memory: number;
  memoryUsed: number;
  memoryTotal: number;
  uptime: number;
  datastores: PBSDatastore[];
  backupJobs: PBSBackupJob[];
  syncJobs: PBSSyncJob[];
  verifyJobs: PBSVerifyJob[];
  pruneJobs: PBSPruneJob[];
  garbageJobs: PBSGarbageJob[];
  jobHealthEvidence?: PBSJobHealthEvidence[];
  connectionHealth: string;
  lastSeen: string;
}

export interface PMGInstance {
  id: string;
  name: string;
  host: string;
  guestURL?: string; // Optional guest-accessible URL (for navigation)
  status: string;
  version: string;
  nodes?: PMGNodeStatus[];
  mailStats?: PMGMailStats;
  mailCount?: PMGMailCountPoint[];
  spamDistribution?: PMGSpamBucket[];
  quarantine?: PMGQuarantineTotals;
  relayDomains?: PMGRelayDomain[];
  domainStats?: PMGDomainStat[];
  domainStatsAsOf?: string;
  connectionHealth: string;
  lastSeen: string;
  lastUpdated: string;
}

export interface PMGRelayDomain {
  domain: string;
  comment?: string;
}

export interface PMGDomainStat {
  domain: string;
  mailCount: number;
  spamCount: number;
  virusCount: number;
  bytes?: number;
}

export interface PMGNodeStatus {
  name: string;
  status: string;
  role?: string;
  uptime?: number;
  loadAvg?: string;
  queueStatus?: PMGQueueStatus;
}

export interface PMGMailStats {
  timeframe: string;
  countTotal: number;
  countIn: number;
  countOut: number;
  spamIn: number;
  spamOut: number;
  virusIn: number;
  virusOut: number;
  bouncesIn: number;
  bouncesOut: number;
  bytesIn: number;
  bytesOut: number;
  greylistCount: number;
  junkIn: number;
  averageProcessTimeMs: number;
  rblRejects: number;
  pregreetRejects: number;
  updatedAt: string;
}

export interface PMGMailCountPoint {
  timestamp: string;
  count: number;
  countIn: number;
  countOut: number;
  spamIn: number;
  spamOut: number;
  virusIn: number;
  virusOut: number;
  rblRejects: number;
  pregreet: number;
  bouncesIn: number;
  bouncesOut: number;
  greylist: number;
  index: number;
  timeframe: string;
  windowStart?: string;
  windowEnd?: string;
}

export interface PMGSpamBucket {
  score: string;
  count: number;
}

export interface PMGQuarantineTotals {
  spam: number;
  virus: number;
  attachment?: number;
  blacklisted?: number;
}

export interface PMGQueueStatus {
  active: number;
  deferred: number;
  hold: number;
  incoming: number;
  total: number;
  oldestAge: number;
  updatedAt: string;
}

export interface PBSDatastore {
  name: string;
  total: number;
  used: number;
  free: number;
  usage: number;
  status: string;
  error: string;
  namespaces: PBSNamespace[];
  deduplicationFactor?: number;
}

export interface PBSNamespace {
  path: string;
  parent: string;
  depth: number;
}

export interface PBSBackupJob {
  id: string;
  store: string;
  type: string;
  vmid?: string;
  lastBackup: string;
  nextRun?: string;
  status: string;
  error?: string;
}

export interface PBSSyncJob {
  id: string;
  store: string;
  remote: string;
  status: string;
  lastSync: string;
  nextRun?: string;
  error?: string;
}

export interface PBSVerifyJob {
  id: string;
  store: string;
  status: string;
  lastVerify: string;
  nextRun?: string;
  error?: string;
}

export interface PBSPruneJob {
  id: string;
  store: string;
  status: string;
  lastPrune: string;
  nextRun?: string;
  error?: string;
}

export interface PBSGarbageJob {
  id: string;
  store: string;
  status: string;
  lastGarbage: string;
  nextRun?: string;
  removedBytes?: number;
  error?: string;
}

export interface PBSJobHealthFreshness {
  observedAt: string;
  lastRunEndTime?: string;
  nextRun?: string;
  ageSeconds?: number;
  state?: string;
}

export interface PBSJobHealthEvidence {
  id: string;
  family: string;
  store?: string;
  remote?: string;
  namespace?: string;
  schedule?: string;
  comment?: string;
  enabled?: boolean;
  'last-run-state'?: string;
  'last-run-upid'?: string;
  'last-run-endtime'?: number;
  'next-run'?: number;
  upid?: string;
  'worker-type'?: string;
  'worker-id'?: string;
  'task-status'?: string;
  'task-starttime'?: number;
  'task-endtime'?: number;
  confidence: string;
  evidenceSource?: string;
  evidenceScope?: string;
  freshness?: PBSJobHealthFreshness;
  posture?: string;
  postureReason?: string;
  error?: string;
}

/** Server-owned provenance of the selected guest-memory reading. */
export interface MemoryObservation {
  /** current, last-known or unavailable. Unrecognised/absent states are unknown. */
  state: string;
  source: string;
  /** Original source time, never the refreshed resource LastSeen. */
  observedAt?: string;
}

export interface Memory {
  total: number;
  used: number;
  free: number;
  /** Reclaimable buff/cache (available - truly free); used + cache + free ≈ total. */
  cache?: number;
  /** Total is known, but no cache-aware source can establish current usage. */
  usageUnavailable?: boolean;
  observation?: MemoryObservation;
  usage: number;
  balloon?: number;
  swapUsed?: number;
  swapTotal?: number;
}

// Models both the legacy state payload (models.Disk, numerics always present,
// filesystem under `type`) and the unified resources facet (DiskInfo, every
// field omitempty so zero values arrive absent, filesystem under `filesystem`).
// Consumers must default absent numerics rather than assume presence (#1663).
export interface Disk {
  total?: number;
  used?: number;
  free?: number;
  usage?: number;
  mountpoint?: string;
  type?: string;
  filesystem?: string;
  device?: string;
}

export interface SMARTAttributes {
  powerOnHours?: number;
  powerCycles?: number;
  reallocatedSectors?: number;
  pendingSectors?: number;
  offlineUncorrectable?: number;
  udmaCrcErrors?: number;
  percentageUsed?: number;
  availableSpare?: number;
  mediaErrors?: number;
  unsafeShutdowns?: number;
}

export interface PhysicalDisk {
  id: string;
  node: string;
  instance: string;
  devPath: string;
  device?: string;
  model: string;
  serial: string;
  wwn: string;
  type: 'nvme' | 'sata' | 'sas' | string;
  controller?: string;
  target?: string;
  size: number;
  health: 'PASSED' | 'FAILED' | 'UNKNOWN' | string;
  wearout: number; // 0-100, 100 is best, -1 when the controller doesn't report it
  temperature: number;
  rpm: number;
  used: string;
  lastChecked: string;
  smartAttributes?: SMARTAttributes;
  io?: {
    device?: string;
    readBytes?: number;
    writeBytes?: number;
    readOps?: number;
    writeOps?: number;
    readTimeMs?: number;
    writeTimeMs?: number;
    ioTimeMs?: number;
  };
  collection?: import('./resource').PhysicalDiskCollectionStatus;
}

export interface CPUInfo {
  model: string;
  cores: number;
  sockets: number;
  mhz: string;
}

export interface Temperature {
  cpuPackage?: number; // CPU package temperature (primary metric)
  cpuMax?: number; // Highest core temperature
  cpuMin?: number; // Minimum recorded CPU temperature (since monitoring started)
  cpuMaxRecord?: number; // Maximum recorded CPU temperature (since monitoring started)
  minRecorded?: string; // When minimum temperature was recorded
  maxRecorded?: string; // When maximum temperature was recorded
  cores?: CoreTemp[]; // Individual core temperatures
  gpu?: GPUTemp[]; // GPU temperatures
  nvme?: NVMeTemp[]; // NVMe drive temperatures
  available: boolean; // Whether any temperature data is available
  hasCPU?: boolean; // Whether CPU temperature data is available
  hasGPU?: boolean; // Whether GPU temperature data is available
  hasNVMe?: boolean; // Whether NVMe temperature data is available
  legacySensorsFormat?: boolean; // SSH payload was raw `sensors -j` (pre-rc.6 node setup); SMART disk temps cannot arrive until the setup script is re-run
  lastUpdate: string; // When this data was collected
}

export interface CoreTemp {
  core: number;
  temp: number;
}

export interface GPUTemp {
  device: string; // GPU device identifier (e.g., "amdgpu-pci-0400")
  edge?: number; // Edge temperature
  junction?: number; // Junction/hotspot temperature
  mem?: number; // Memory temperature
}

export interface NVMeTemp {
  device: string;
  temp: number;
}

export interface Metric {
  timestamp: string;
  type: string;
  id: string;
  values: Record<string, number | string | boolean>;
}

export interface Performance {
  apiCallDuration: Record<string, number>;
  lastPollDuration: number;
  pollingStartTime: string;
  totalApiCalls: number;
  failedApiCalls: number;
  cacheHits?: number;
  cacheMisses?: number;
}

export interface Stats {
  startTime: string;
  uptime: number;
  pollingCycles: number;
  webSocketClients: number;
  version: string;
}

// Alert types
export type AlertFailureClass =
  | 'runtime'
  | 'network-path'
  | 'application-response'
  | 'certificate'
  | 'dependency'
  | 'evidence-coverage';

export interface AlertCorrelationObservation {
  alertId: string;
  resourceId: string;
  resourceName: string;
  failureClass: AlertFailureClass;
  level: 'info' | 'warning' | 'critical';
  observedAt: string;
  evidenceIds?: string[];
}

export interface AlertCorrelation {
  key: string;
  kind: 'shared-system' | 'infrastructure-incident';
  role: 'primary' | 'supporting';
  reason: string;
  failureClass?: AlertFailureClass;
  inference?: 'supported-cause' | 'observation-set';
  primaryAlertId?: string;
  primaryResourceId?: string;
  affectedResourceIds?: string[];
  observations?: AlertCorrelationObservation[];
}

export interface Alert {
  id: string;
  type: string;
  level: 'info' | 'warning' | 'critical';
  resourceId: string;
  canonicalSpecId?: string;
  canonicalKind?: string;
  canonicalState?: string;
  resourceName: string;
  node: string;
  nodeDisplayName?: string;
  instance: string;
  message: string;
  /** The message without its subject, for rows that already name the resource. */
  summary?: string;
  value: number;
  threshold: number;
  startTime: string;
  lastSeen?: string;
  acknowledged: boolean;
  ackTime?: string;
  ackUser?: string;
  correlation?: AlertCorrelation;
  metadata?: Record<string, unknown>;
  /**
   * Live evaluation behind an open threshold alert. `value`, `message` and
   * `lastSeen` keep the last reading that met the trigger; this is the
   * reading being evaluated now and why the alert has not cleared.
   */
  metricStatus?: MetricAlertStatus;
  operationalRecord?: OperationalRecord;
  latestTransition?: LifecycleTransition;
  transitions?: LifecycleTransition[];
  evidence?: EvidenceEnvelope[];
  // Set only on a closed alert whose condition did not clear, such as a node
  // metric handed to its Pulse agent. Absent for an ordinary recovery.
  resolution?: AlertResolution;
}

// Why an alert closed without recovering (alerts.AlertResolution).
export interface AlertResolution {
  reason: 'moved_to_agent' | (string & {});
  successorResourceId?: string;
  successorName?: string;
  // The alert engine's one-line account; carried on state snapshots only.
  summary?: string;
}

export interface ResolvedAlert extends Alert {
  resolvedTime: string;
}

export type MetricAlertPhase = 'breaching' | 'latched' | 'recovering';

export interface MetricAlertStatus {
  phase: MetricAlertPhase;
  /** Value compared with the rule (the average for a rolling-average rule). */
  value: number;
  /** Latest sample when the rule evaluates a rolling average. */
  rawValue?: number;
  evaluationWindowSeconds?: number;
  unit?: string;
  observedAt: string;
  /** Dates Alert.value, not the newer held/recovering observation; absent when unknown. */
  lastBreachAt?: string;
  /** Opens at or above this value. */
  trigger: number;
  /** Clears after staying at or below this value for recoveryDelaySeconds. */
  recovery: number;
  recoveryDelaySeconds?: number;
  recoveryStartedAt?: string;
  recoveryElapsedSeconds?: number;
}

// One entry from the append-only alert event log
// (GET /api/alerts/events): a lifecycle transition or a notification
// decision, including suppressions with the mechanism that held them.
export interface AlertEvent {
  id: number;
  occurredAt: string;
  type: string;
  alertId: string;
  resourceId?: string;
  resourceName?: string;
  alertType?: string;
  level?: string;
  reason?: string;
  message?: string;
  details?: Record<string, string>;
}

// Read-only projection of notification delivery policy for one active alert,
// from GET /api/alerts/delivery-diagnosis.
export interface AlertDeliveryDiagnosis {
  alertIdentifier: string;
  alertId: string;
  trackingKey: string;
  status: 'would_send' | 'deferred' | 'suppressed';
  reason: string;
  message: string;
  alertType: string;
  level: 'info' | 'warning' | 'critical';
  resourceId?: string;
  resourceName?: string;
  node?: string;
  notificationsEnabled: boolean;
  activationState: string;
  cooldownMinutes: number;
  maxAlertsHour: number;
  recentAlertsInHour: number;
  flappingActive: boolean;
  flappingHistoryInWindow: number;
  flappingThreshold: number;
  flappingWindowSeconds: number;
  lastNotified?: string;
  nextEligibleAt?: string;
  quietHoursReplayAt?: string;
  suppressedUntil?: string;
}

export interface IncidentEvent {
  source?: string;
  evidence?: ResourceChange;
  id: string;
  type: string;
  timestamp: string;
  summary: string;
  details?: Record<string, unknown>;
}

export interface IncidentHistoryCoverage {
  source: string;
  observedSince: string;
  observedBefore: string;
  changeLimit: number;
  hasMoreChanges: boolean;
  hasMoreIncidents: boolean;
}

export interface Incident {
  history?: IncidentHistoryCoverage;
  id: string;
  alertIdentifier: string;
  alertType: string;
  level: string;
  resourceId: string;
  resourceName: string;
  resourceType?: string;
  node?: string;
  instance?: string;
  message?: string;
  status: string;
  openedAt: string;
  closedAt?: string;
  acknowledged: boolean;
  ackUser?: string;
  ackTime?: string;
  events?: IncidentEvent[];
}

// WebSocket message types
export type WSMessage =
  | { type: 'initialState'; data: State }
  | { type: 'rawData'; data: StateUpdate }
  | {
      type: 'stateTooLarge';
      data: {
        supersedes: 'initialState' | 'rawData';
        bytes?: number;
        maxBytes: number;
        resourceCount: number;
        hydrateFrom: '/api/state';
      };
    }
  | { type: 'error'; error: string }
  | { type: 'ping'; data?: unknown }
  | { type: 'pong'; data?: unknown }
  | { type: 'welcome'; data?: unknown }
  | { type: 'alert'; data: Alert }
  | { type: 'alertResolved'; data: { alertIdentifier: string } }
  | { type: 'settingsUpdate'; data: { theme?: string } }
  | {
      type: 'update:progress';
      data: {
        phase: string;
        progress: number;
        message: string;
      };
    }
  | {
      type: 'node_auto_registered';
      data: {
        type: string;
        source?: string;
        host: string;
        name: string;
        tokenId: string;
        hasToken: boolean;
        verifySSL?: boolean;
        status?: string;
      };
    }
  | { type: 'node_deleted'; data: { nodeType: string } }
  | { type: 'nodes_changed'; data?: unknown }
  | {
      type: 'discovery_update';
      data: {
        servers: Array<{
          ip: string;
          port: number;
          type: string;
          version: string;
          hostname?: string;
          release?: string;
        }>;
        errors?: string[];
        timestamp?: number;
        immediate?: boolean;
        scanning?: boolean;
        cached?: boolean;
      };
    }
  | {
      type: 'discovery_started';
      data?: {
        subnet?: string;
        timestamp?: number;
        scanning?: boolean;
      };
    }
  | {
      type: 'discovery_complete';
      data?: {
        timestamp?: number;
        scanning?: boolean;
      };
    };