@skyhook-io/radar-app 1.16.3 → 1.17.1

package/src/components/cnpg/operations/model.ts

@@ -0,0 +1,499 @@
+import type { CNPGClusterHA } from '@skyhook-io/k8s-ui'
+import type { CNPGClusterFacts, CNPGRuntimeResponse } from '../../../api/cnpg'
+import { formatGrant } from '@skyhook-io/k8s-ui'
+
+// Follow-through for CloudNativePG actions. A successful POST only means the
+// write was accepted; the operator acts on it later. A tracked operation is
+// bound to the Radar API base, context, Cluster UID and target it was
+// requested for, carries a baseline taken before the write, and is judged by
+// a per-kind observer against what the cluster reports now. Missing telemetry
+// is "unobservable", never "stalled": stalled needs evidence that nothing is
+// moving.
+
+export type CNPGOpState = 'requested' | 'observed' | 'progressing' | 'completed' | 'failed' | 'stalled' | 'superseded' | 'unobservable'
+
+export const CNPG_OP_TERMINAL: ReadonlySet<CNPGOpState> = new Set(['completed', 'failed', 'superseded'])
+
+export interface CNPGOpStep {
+  label: string
+  /** true done, false not yet, null not observable with the caller's access. */
+  done: boolean | null
+}
+
+export interface CNPGTrackedOperation {
+  id: string
+  kind: string
+  label: string
+  /**
+   * The Radar API base the request went to. Every in-cluster Radar reports
+   * the context "in-cluster", so in Radar Hub this is what tells two
+   * clusters apart.
+   */
+  apiBase: string
+  context: string
+  namespace: string
+  cluster: string
+  /** Absent when the requester could not read the Cluster identity. */
+  clusterUID?: string
+  target?: { name: string; uid?: string }
+  startedAt: number
+  baseline: Record<string, unknown>
+  state: CNPGOpState
+  detail?: string
+  steps?: CNPGOpStep[]
+  /** When the observer last saw its progress key change. */
+  lastProgressAt: number
+  /** Last assessment in this tab, including an assessment with unavailable evidence. */
+  lastCheckedAt?: number
+  progressKey?: string
+  /** A related object to open, e.g. the Backup. */
+  link?: { kind: string; group: string; name: string }
+  finishedAt?: number
+}
+
+/** Everything an observer may look at. Any source can be missing. */
+export interface CNPGObservation {
+  now: number
+  /** The Cluster's UID now, from whichever source read it. */
+  clusterUID?: string
+  /** The first live identity check after mounting is still in flight. */
+  identityPending?: boolean
+  /** The latest fetch of a source polled for the Cluster identity failed. */
+  identityReadFailed?: boolean
+  facts?: CNPGClusterFacts
+  /** The Cluster object from the workspace (status.conditions, readyInstances). */
+  cluster?: any
+  ha?: CNPGClusterHA
+  runtime?: CNPGRuntimeResponse
+  /** Backups of the namespace, or undefined when they are not readable. */
+  backups?: any[]
+  /**
+   * When each source was last fetched successfully and whether its latest
+   * fetch failed. A source without a record here, not fetched successfully
+   * since the operation started, or whose refresh failed is withheld from
+   * its observer. Cluster-scoped sources also carry the UID they read, so
+   * facts from a replaced Cluster cannot certify the operation's outcome.
+   */
+  freshness?: Partial<Record<CNPGObservedSource, { updatedAt: number; failed: boolean; clusterUID?: string }>>
+}
+
+export type CNPGObservedSource = 'clusterUID' | 'facts' | 'cluster' | 'ha' | 'runtime' | 'backups'
+
+/** The observation with every stale or failed source removed. */
+export function freshObservation(op: CNPGTrackedOperation, obs: CNPGObservation): CNPGObservation {
+  const out: CNPGObservation = { ...obs }
+  for (const source of CNPG_OBSERVED_SOURCES) {
+    const f = obs.freshness?.[source]
+    const differentCluster = op.clusterUID && source !== 'clusterUID' && source !== 'backups' && f?.clusterUID !== op.clusterUID
+    if (!f || f.failed || f.updatedAt < op.startedAt || differentCluster) out[source] = undefined
+  }
+  return out
+}
+
+const CNPG_OBSERVED_SOURCES: readonly CNPGObservedSource[] = ['clusterUID', 'facts', 'cluster', 'ha', 'runtime', 'backups']
+
+export interface CNPGObserverResult {
+  state: Exclude<CNPGOpState, 'superseded' | 'stalled'>
+  detail?: string
+  steps?: CNPGOpStep[]
+  /** Changes whenever the operation moves; drives stall detection. */
+  progressKey?: string
+  /** Nothing will ever report more: stop following now. */
+  final?: boolean
+}
+
+export type CNPGOperationObserver = (op: CNPGTrackedOperation, obs: CNPGObservation) => CNPGObserverResult
+
+const observers = new Map<string, CNPGOperationObserver>()
+
+/** Plug in the observer for a new operation kind. */
+export function registerCNPGOperationObserver(kind: string, observer: CNPGOperationObserver) {
+  observers.set(kind, observer)
+}
+
+/** No progress for this long, with telemetry present, reads as stalled. */
+export const CNPG_OP_STALL_MS = 10 * 60_000
+
+/** An operation Radar cannot observe is followed this long, then left alone. */
+export const CNPG_OP_UNOBSERVABLE_MS = 15 * 60_000
+
+/**
+ * Just after a request the sources an observer needs may not have been re-read
+ * yet; until one fails, or this long has passed, that is waiting, not
+ * "cannot be followed".
+ */
+export const CNPG_OP_FIRST_READ_MS = 20_000
+
+/** Whether the tracker should still poll for this operation. */
+export function cnpgOperationFollowed(op: CNPGTrackedOperation): boolean {
+  return !CNPG_OP_TERMINAL.has(op.state) && !op.finishedAt
+}
+
+/** Advance one operation against an observation. Pure. */
+export function advanceCNPGOperation(op: CNPGTrackedOperation, obs: CNPGObservation): CNPGTrackedOperation {
+  if (CNPG_OP_TERMINAL.has(op.state)) return op
+  op = { ...op, lastCheckedAt: obs.now }
+  const current = freshObservation(op, obs)
+  if (op.clusterUID && current.clusterUID && current.clusterUID !== op.clusterUID) {
+    return { ...op, state: 'superseded', detail: 'The Cluster was deleted and recreated; this operation no longer applies to it', finishedAt: obs.now }
+  }
+  if (op.clusterUID && !current.clusterUID) {
+    const identity = obs.freshness?.clusterUID
+    const expired = obs.now - op.startedAt > CNPG_OP_UNOBSERVABLE_MS
+    const unread = !identity || identity.updatedAt < op.startedAt
+    // An identity from before the request cannot hold "waiting" while the
+    // reads that would replace it fail.
+    const failed = !!identity?.failed || (unread && !!obs.identityReadFailed)
+    if (!expired && !failed && unread) {
+      return { ...op, state: 'requested', detail: 'Waiting for the first read since the request' }
+    }
+    return {
+      ...op,
+      state: 'unobservable',
+      detail: 'The Cluster identity has not been verified since this operation was requested',
+      finishedAt: !obs.identityPending && expired ? obs.now : undefined,
+    }
+  }
+  const observer = observers.get(op.kind)
+  if (!observer) return { ...op, state: 'unobservable', detail: 'Radar has no way to follow this operation' }
+  const res = observer(op, current)
+  const moved = res.progressKey !== undefined && res.progressKey !== op.progressKey
+  const lastProgressAt = moved ? obs.now : op.lastProgressAt
+  let state: CNPGOpState = res.state
+  let detail = res.detail
+  if (state === 'unobservable' && !res.final && obs.now - op.startedAt < CNPG_OP_FIRST_READ_MS && !Object.values(obs.freshness ?? {}).some((f) => f?.failed)) {
+    state = 'requested'
+    detail = 'Waiting for the first read since the request'
+  }
+  if ((state === 'progressing' || state === 'observed' || state === 'requested') && res.progressKey !== undefined && obs.now - lastProgressAt > CNPG_OP_STALL_MS) {
+    state = 'stalled'
+    detail = `No progress for ${Math.round((obs.now - lastProgressAt) / 60_000)} min${res.detail ? ` · ${res.detail}` : ''}`
+  }
+  const givenUp = state === 'unobservable' && (res.final || obs.now - op.startedAt > CNPG_OP_UNOBSERVABLE_MS)
+  return {
+    ...op,
+    state,
+    detail,
+    steps: res.steps ?? op.steps,
+    progressKey: res.progressKey ?? op.progressKey,
+    lastProgressAt,
+    finishedAt: CNPG_OP_TERMINAL.has(state) || givenUp ? obs.now : undefined,
+  }
+}
+
+/**
+ * A newer operation of a kind that changes the same thing makes an older,
+ * unfinished one moot: its expectation will never be met.
+ */
+const CONFLICTS: Record<string, string[]> = {
+  switchover: ['switchover', 'hibernate', 'rehydrate'],
+  restart: ['restart', 'hibernate', 'fence'],
+  restartInstance: ['hibernate', 'restart', 'fence'],
+  fence: ['fence', 'unfence', 'hibernate'],
+  unfence: ['fence', 'unfence', 'hibernate'],
+  hibernate: ['hibernate', 'rehydrate'],
+  rehydrate: ['hibernate', 'rehydrate'],
+  setMaintenance: ['setMaintenance', 'unsetMaintenance'],
+  unsetMaintenance: ['setMaintenance', 'unsetMaintenance'],
+}
+
+export function supersedeFor(existing: CNPGTrackedOperation[], next: CNPGTrackedOperation): CNPGTrackedOperation[] {
+  return existing.map((op) => {
+    if (CNPG_OP_TERMINAL.has(op.state)) return op
+    if (op.apiBase !== next.apiBase || op.context !== next.context || op.namespace !== next.namespace || op.cluster !== next.cluster) return op
+    if (!(CONFLICTS[op.kind] ?? []).includes(next.kind)) return op
+    if (op.kind === 'restartInstance' && next.kind === 'fence' && !fencedBy(next, op.target?.name)) return op
+    return { ...op, state: 'superseded', detail: `Superseded by ${next.label}`, finishedAt: next.startedAt }
+  })
+}
+
+// A fence of all instances records every instance it fenced.
+function fencedBy(fence: CNPGTrackedOperation, pod: string | undefined): boolean {
+  return !!pod && ((fence.baseline.instances as string[] | undefined) ?? []).includes(pod)
+}
+
+// ---------------------------------------------------------------------------
+// Evidence helpers
+
+function haInstance(obs: CNPGObservation, pod: string) {
+  return obs.ha?.pods.state === 'ok' ? obs.ha.instances.find((i) => i.pod === pod) : undefined
+}
+
+function runtimeInstance(obs: CNPGObservation, pod: string) {
+  return obs.runtime?.instances.find((i) => i.pod === pod)
+}
+
+/**
+ * Whether `pod` restarted after `since`: the Pod was recreated, its postgres
+ * container started again, or PostgreSQL's own start time moved (an in-place
+ * restart keeps the container). null when none of those is readable.
+ */
+export function restartedSince(obs: CNPGObservation, pod: string, since: number, baselineUID?: string): boolean | null {
+  let known = false
+  const h = haInstance(obs, pod)
+  if (h) {
+    known = true
+    if (baselineUID && h.podUID !== baselineUID) return true
+    if (h.podCreatedAt && Date.parse(h.podCreatedAt) > since) return true
+    if (h.postgresStartedAt && Date.parse(h.postgresStartedAt) > since) return true
+  } else if (obs.ha?.pods.state === 'ok') {
+    known = true
+  }
+  const r = runtimeInstance(obs, pod)
+  const pm = r?.metrics.postmasterStartTime
+  if (pm !== undefined) {
+    known = true
+    if (pm * 1000 > since) return true
+  }
+  return known ? false : null
+}
+
+function readyNow(obs: CNPGObservation, pod: string): boolean | null {
+  const h = haInstance(obs, pod)
+  if (h) return h.ready
+  const f = obs.facts?.instances.find((i) => i.pod === pod)
+  return f && f.podReadable ? f.ready : null
+}
+
+/**
+ * Whether `pod` streams from the primary, from its own report or the
+ * primary's pg_stat_replication. With the proxy allowed, an instance that does
+ * not answer yet (restarting) is "not yet"; without it the answer is unknown.
+ */
+function streamingStandby(obs: CNPGObservation, pod: string): boolean | null {
+  if (!obs.runtime || obs.runtime.permission.proxy === 'denied') return null
+  const own = runtimeInstance(obs, pod)?.status
+  if (own && (own.state === 'ok' || own.state === 'partial') && own.roleDetail) return own.roleDetail === 'streaming'
+  const primaryName = obs.facts?.currentPrimary
+  const primary = obs.runtime.instances.find((i) => (primaryName ? i.pod === primaryName : i.role === 'primary'))?.status
+  if (primary && (primary.state === 'ok' || primary.state === 'partial')) {
+    if (!primary.replication) return null
+    return primary.replication.some((r) => r.applicationName === pod && r.state === 'streaming')
+  }
+  return own?.state === 'denied' ? null : false
+}
+
+function condition(cluster: any, type: string): { status?: string; reason?: string; message?: string } | undefined {
+  return (cluster?.status?.conditions ?? []).find((c: any) => c?.type === type)
+}
+
+/**
+ * Completed only when every step is seen done. A step Radar cannot see keeps
+ * the operation unobservable rather than completed — or stalled.
+ */
+export function summarizeSteps(steps: CNPGOpStep[]): CNPGObserverResult['state'] {
+  const done = steps.filter((s) => s.done === true).length
+  const pending = steps.filter((s) => s.done === false).length
+  if (done === steps.length) return 'completed'
+  if (pending > 0) return done > 0 ? 'progressing' : 'requested'
+  return 'unobservable'
+}
+
+function key(steps: CNPGOpStep[], extra = ''): string {
+  return steps.map((s) => (s.done === true ? '1' : s.done === false ? '0' : '?')).join('') + extra
+}
+
+// ---------------------------------------------------------------------------
+// Built-in observers
+
+registerCNPGOperationObserver('switchover', (op, obs) => {
+  const target = op.target?.name ?? ''
+  const oldPrimary = String(op.baseline.currentPrimary ?? '')
+  const f = obs.facts
+  if (!f) return { state: 'unobservable', detail: 'The Cluster is not readable' }
+  if (f.currentPrimary && f.currentPrimary !== target && f.currentPrimary !== oldPrimary) {
+    return { state: 'failed', detail: `${f.currentPrimary} became primary instead of ${target}` }
+  }
+  const promoted = f.currentPrimary === target
+  const requested = promoted || f.targetPrimary === target
+  if (!requested && f.targetPrimary === oldPrimary && f.phase === 'Cluster in healthy state' && obs.now - op.startedAt > 60_000) {
+    return { state: 'failed', detail: `The operator kept ${oldPrimary} as primary${f.phaseReason ? `: ${f.phaseReason}` : ''}` }
+  }
+  const rejoined = promoted ? streamingStandby(obs, oldPrimary) : false
+  const rw = obs.ha?.rwEndpoints
+  const steps: CNPGOpStep[] = [
+    { label: `Operator accepted ${target} as target`, done: requested },
+    { label: `${target} is the primary`, done: promoted },
+    { label: `${oldPrimary} is back as a streaming standby`, done: rejoined },
+  ]
+  // Clients reach the new primary only through the read-write Service; when
+  // its endpoints are not readable that step stays unverified, so the
+  // switchover can end "unobservable" but never "completed".
+  const rwReadable = rw?.state === 'ok'
+  steps.push({
+    label: rwReadable ? `Read-write Service points at ${target}` : `Read-write Service points at ${target} (endpoints not readable)`,
+    done: rwReadable ? promoted && rw.pods.includes(target) && !rw.pods.includes(oldPrimary) : null,
+  })
+  steps.push({ label: 'Cluster reports a healthy state again', done: promoted && f.phase === 'Cluster in healthy state' })
+  let state = summarizeSteps(steps)
+  if (requested && !promoted) state = 'observed'
+  const rwUnverified = `the read-write Service is unverified${rw?.grant ? ` (needs ${formatGrant(rw.grant)})` : rw?.reason ? ` (${rw.reason})` : ''}`
+  const detail =
+    rejoined === null && promoted
+      ? `Primary changed; whether ${oldPrimary} rejoined needs runtime access (get pods/proxy)${rwReadable ? '' : `; ${rwUnverified}`}`
+      : f.phase && f.phase !== 'Cluster in healthy state'
+        ? f.phase + (f.phaseReason ? `: ${f.phaseReason}` : '')
+        : !rwReadable && promoted
+          ? `Primary changed; ${rwUnverified}`
+          : undefined
+  return { state, steps, detail, progressKey: key(steps, f.phase ?? '') }
+})
+
+function restartObserver(podsOf: (op: CNPGTrackedOperation, obs: CNPGObservation) => string[]): CNPGOperationObserver {
+  return (op, obs) => {
+    const pods = podsOf(op, obs)
+    if (pods.length === 0) return { state: 'unobservable', detail: 'No instances to follow' }
+    const uids = (op.baseline.podUIDs ?? {}) as Record<string, string>
+    const steps: CNPGOpStep[] = pods.map((p) => {
+      const restarted = restartedSince(obs, p, op.startedAt, uids[p])
+      const ready = restarted ? readyNow(obs, p) : false
+      return { label: `${p} restarted and ready`, done: restarted === null ? null : restarted ? ready : false }
+    })
+    const done = steps.filter((s) => s.done).length
+    const state = summarizeSteps(steps)
+    const detail =
+      state === 'unobservable'
+        ? 'Restart or readiness evidence is not readable with your access'
+        : `${done} of ${pods.length} restarted${obs.facts?.phase && obs.facts.phase !== 'Cluster in healthy state' ? ` · ${obs.facts.phase}` : ''}`
+    return { state, steps, detail, progressKey: key(steps) }
+  }
+}
+
+registerCNPGOperationObserver(
+  'restart',
+  restartObserver((op) => {
+    const fenced = new Set((op.baseline.fenced as string[] | undefined) ?? [])
+    return ((op.baseline.instances as string[]) ?? []).filter((p) => !fenced.has(p))
+  }),
+)
+registerCNPGOperationObserver(
+  'restartInstance',
+  restartObserver((op) => (op.target ? [op.target.name] : [])),
+)
+
+registerCNPGOperationObserver('destroyInstance', (op, obs) => {
+  const f = obs.facts
+  if (!f) return { state: 'unobservable', detail: 'The Cluster is not readable' }
+  const destroyed = op.target?.name ?? ''
+  const before = new Set((op.baseline.instances as string[]) ?? [])
+  const gone = !f.instances.some((i) => i.pod === destroyed && (!op.target?.uid || i.podUID === op.target.uid))
+  const replacement = f.instances.find((i) => !before.has(i.pod))
+  const replacementReady = replacement ? readyNow(obs, replacement.pod) : false
+  const steps: CNPGOpStep[] = [
+    { label: `${destroyed} removed`, done: gone },
+    { label: replacement ? `Replacement ${replacement.pod} ready` : 'Operator created a replacement instance', done: replacement ? replacementReady : false },
+    {
+      label: replacement ? `${replacement.pod} streaming from the primary` : 'Replacement streaming from the primary',
+      done: !replacement ? false : replacementReady === null ? null : replacementReady ? streamingStandby(obs, replacement.pod) : false,
+    },
+    { label: 'Cluster reports a healthy state again', done: gone && !!replacement && f.phase === 'Cluster in healthy state' },
+  ]
+  const detail = f.phase && f.phase !== 'Cluster in healthy state' ? f.phase + (f.phaseReason ? `: ${f.phaseReason}` : '') : undefined
+  return { state: summarizeSteps(steps), steps, detail, progressKey: key(steps, `${replacement?.pod ?? ''}${f.phase ?? ''}`) }
+})
+
+registerCNPGOperationObserver('reload', () => ({
+  state: 'unobservable',
+  final: true,
+  detail: 'Requested. Nothing in the cluster reports when a configuration reload completes; check the instance logs for "received SIGHUP".',
+}))
+
+// CloudNativePG reports no shutdown signal for a fenced instance: /pg/status
+// never carries isFenced, and a masked status error (mightBeUnavailable) also
+// arrives without WAL positions. So the fence being recorded is the last thing
+// Radar can verify; the shutdown itself stays unverified.
+registerCNPGOperationObserver('fence', (op, obs) => {
+  const pods = ((op.baseline.instances as string[]) ?? [])
+  const f = obs.facts
+  const recorded = (p: string): boolean | null => (f ? f.fencedInstances.all || f.fencedInstances.instances.includes(p) : null)
+  const steps: CNPGOpStep[] = pods.flatMap((p) => [
+    { label: `${p}: fence recorded on the Cluster`, done: recorded(p) },
+    { label: `${p}: PostgreSQL stopped (CloudNativePG reports no signal for this)`, done: null },
+  ])
+  const allRecorded = pods.length > 0 && pods.every((p) => recorded(p) === true)
+  return {
+    state: allRecorded ? 'unobservable' : summarizeSteps(steps.filter((_, i) => i % 2 === 0)),
+    steps,
+    final: allRecorded,
+    detail: allRecorded
+      ? 'Fence recorded. The operator stops PostgreSQL on a fenced instance, but nothing in the cluster confirms the shutdown; the instance logs show it.'
+      : 'Waiting for the fence to be recorded on the Cluster',
+    progressKey: key(steps),
+  }
+})
+
+registerCNPGOperationObserver('unfence', (op, obs) => {
+  const pods = ((op.baseline.instances as string[]) ?? [])
+  const primary = obs.facts?.currentPrimary
+  const steps: CNPGOpStep[] = pods.flatMap((p) => {
+    const ready = readyNow(obs, p)
+    const out: CNPGOpStep[] = [{ label: `${p}: ready again`, done: ready }]
+    if (p !== primary) out.push({ label: `${p}: streaming from the primary`, done: ready === null ? null : ready ? streamingStandby(obs, p) : false })
+    return out
+  })
+  return { state: summarizeSteps(steps), steps, progressKey: key(steps) }
+})
+
+registerCNPGOperationObserver('hibernate', (_op, obs) => {
+  const c = condition(obs.cluster, 'cnpg.io/hibernation')
+  if (!obs.cluster) return { state: 'unobservable', detail: 'The Cluster is not readable' }
+  const steps: CNPGOpStep[] = [
+    { label: 'Hibernation condition true', done: c?.status === 'True' },
+    { label: 'Instance Pods removed', done: obs.ha?.pods.state === 'ok' ? obs.ha.instances.length === 0 : null },
+  ]
+  return { state: summarizeSteps(steps), steps, detail: c?.message, progressKey: key(steps, c?.reason ?? '') }
+})
+
+registerCNPGOperationObserver('rehydrate', (_op, obs) => {
+  const c = condition(obs.cluster, 'cnpg.io/hibernation')
+  if (!obs.cluster) return { state: 'unobservable', detail: 'The Cluster is not readable' }
+  const desired = obs.cluster?.spec?.instances
+  const ready = obs.cluster?.status?.readyInstances ?? 0
+  const steps: CNPGOpStep[] = [
+    { label: 'Hibernation condition cleared', done: !c || c.status !== 'True' },
+    { label: `All ${desired ?? ''} instances ready`.replace('  ', ' '), done: typeof desired === 'number' ? ready >= desired : null },
+  ]
+  return { state: summarizeSteps(steps), steps, detail: `${ready}/${desired ?? '?'} ready`, progressKey: key(steps, String(ready)) }
+})
+
+function backupObserver(op: CNPGTrackedOperation, obs: CNPGObservation): CNPGObserverResult {
+  if (!op.clusterUID) return { state: 'unobservable', detail: 'The source Cluster identity was not recorded for this backup' }
+  const name = op.target?.name
+  if (!name) return { state: 'unobservable', detail: 'No Backup name recorded' }
+  if (!obs.backups) return { state: 'unobservable', detail: 'Backups are not readable with your access' }
+  const b = obs.backups.find((x) => x?.metadata?.name === name && x?.metadata?.namespace === op.namespace)
+  if (!b) {
+    return obs.now - op.startedAt > 60_000
+      ? { state: 'unobservable', detail: `Backup ${name} is not visible (deleted, or outside the backups Radar keeps)`, progressKey: 'absent' }
+      : { state: 'requested', detail: `Waiting for Backup ${name} to appear`, progressKey: 'absent' }
+  }
+  const phase: string | undefined = b.status?.phase
+  switch (phase) {
+    case 'completed':
+      return { state: 'completed', detail: `Backup ${name} completed` }
+    case 'failed':
+    case 'walArchivingFailing':
+      return { state: 'failed', detail: `Backup ${name} ${phase}${b.status?.error ? `: ${b.status.error}` : ''}` }
+    case undefined:
+    case '':
+      return { state: 'observed', detail: `Backup ${name} created; the operator has not picked it up yet`, progressKey: 'new' }
+    default:
+      // The phase holds for as long as the data takes to copy, so an
+      // unchanged phase is no evidence of a stall.
+      return { state: 'progressing', detail: `Backup ${name}: ${phase}` }
+  }
+}
+registerCNPGOperationObserver('backup', backupObserver)
+registerCNPGOperationObserver('run', backupObserver)
+
+function maintenanceObserver(want: boolean): CNPGOperationObserver {
+  return (_op, obs) => {
+    const m = obs.facts?.maintenance ?? obs.ha?.maintenance
+    if (!m) return { state: 'unobservable', detail: 'The Cluster is not readable' }
+    return m.inProgress === want
+      ? { state: 'completed', detail: want ? 'Maintenance window is in progress' : 'Maintenance window lifted' }
+      : { state: 'requested', detail: 'Waiting for the Cluster spec to reflect it', progressKey: String(m.inProgress) }
+  }
+}
+registerCNPGOperationObserver('setMaintenance', maintenanceObserver(true))
+registerCNPGOperationObserver('unsetMaintenance', maintenanceObserver(false))

package/src/components/cnpg/operations/presentation.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { advanceCNPGOperation, type CNPGTrackedOperation } from './model'
+import { cnpgOperationHandoff, cnpgOperationsForCluster, latestCNPGOperation } from './presentation'
+
+const operation: CNPGTrackedOperation = {
+  id: 'local',
+  kind: 'reload',
+  label: 'Reload configuration',
+  apiBase: '/api',
+  context: 'kind-db',
+  namespace: 'db',
+  cluster: 'pg',
+  clusterUID: 'uid',
+  startedAt: Date.parse('2026-10-07T00:00:00Z'),
+  lastProgressAt: 0,
+  state: 'requested',
+  baseline: { secret: 'must not be copied' },
+}
+
+describe('local operation presentation', () => {
+  it('keeps completed predecessor operations out of the header, count and handoff list', () => {
+    const completed = { ...operation, state: 'completed' as const, finishedAt: operation.startedAt + 1000 }
+    const subject = { apiBase: '/api', context: 'kind-db', namespace: 'db', name: 'pg', uid: 'replacement' }
+    expect(cnpgOperationsForCluster([completed], subject)).toEqual([])
+    const current = { ...completed, id: 'replacement-restore', clusterUID: 'replacement', startedAt: completed.startedAt + 2000 }
+    expect(cnpgOperationsForCluster([completed, current], subject)).toEqual([current])
+    expect(latestCNPGOperation([completed, current], subject)).toBe(current)
+  })
+
+  it('never joins a record across contexts, namespaces or a recreated Cluster', () => {
+    const subject = { apiBase: '/api', context: 'kind-db', namespace: 'db', name: 'pg', uid: 'uid' }
+    expect(latestCNPGOperation([operation], subject)).toBe(operation)
+    for (const changed of [{ apiBase: '/c/other/api' }, { context: 'prod' }, { namespace: 'elsewhere' }, { uid: 'new-uid' }]) {
+      expect(latestCNPGOperation([operation], { ...subject, ...changed })).toBeUndefined()
+    }
+    expect(
+      latestCNPGOperation([operation, { ...operation, id: 'newer', startedAt: operation.startedAt + 1000 }], subject)
+        ?.id,
+    ).toBe('newer')
+  })
+
+  it('keeps Radar Hub clusters apart although every in-cluster Radar reports the same context', () => {
+    const hub = { ...operation, context: 'in-cluster', apiBase: '/c/east/api' }
+    const west = { apiBase: '/c/west/api', context: 'in-cluster', namespace: 'db', name: 'pg', uid: 'uid' }
+    expect(cnpgOperationsForCluster([hub], west)).toEqual([])
+    expect(cnpgOperationsForCluster([hub], { ...west, apiBase: '/c/east/api' })).toEqual([hub])
+    const unstamped = { ...hub } as Partial<CNPGTrackedOperation>
+    delete unstamped.apiBase
+    expect(cnpgOperationsForCluster([unstamped as CNPGTrackedOperation], { ...west, apiBase: '/c/east/api' })).toEqual([])
+  })
+
+  it('records a check even when the result is unobservable; terminal records retain their assessment time', () => {
+    const checked = advanceCNPGOperation(operation, { now: operation.startedAt + 1000, freshness: { clusterUID: { updatedAt: 0, failed: true } } })
+    expect(checked.state).toBe('unobservable')
+    expect(checked.lastCheckedAt).toBe(operation.startedAt + 1000)
+    const terminal = { ...checked, state: 'completed' as const }
+    expect(advanceCNPGOperation(terminal, { now: operation.startedAt + 2000 })).toBe(terminal)
+  })
+
+  it('copies verification intent and a pinned live link without the private baseline', () => {
+    const text = cnpgOperationHandoff(
+      {
+        ...operation,
+        steps: [
+          { label: 'Verify uploads', done: null },
+          { label: 'Backup finished', done: false },
+        ],
+      },
+      'https://radar.example/c/db/cnpg/clusters/db/pg?ctx=kind-db',
+    )
+    expect(text).toContain('Context: kind-db')
+    expect(text).toContain('Cluster UID: uid')
+    expect(text).toContain('[unknown] Verify uploads')
+    expect(text).toContain('[pending] Backup finished')
+    expect(text).toContain('not a shared operation history')
+    expect(text).toContain('/c/db/cnpg/clusters/db/pg?ctx=kind-db')
+    expect(text).not.toContain('must not be copied')
+    expect(text).toContain('not yet checked')
+  })
+})

package/src/components/cnpg/operations/presentation.ts

@@ -0,0 +1,84 @@
+import type { HealthLevel } from '@skyhook-io/k8s-ui'
+import type { CNPGOpState, CNPGTrackedOperation } from './model'
+
+export const CNPG_OP_STATE_TEXT: Record<CNPGOpState, string> = {
+  requested: 'requested',
+  observed: 'observed by the operator',
+  progressing: 'in progress',
+  completed: 'completed',
+  failed: 'failed',
+  stalled: 'stalled',
+  superseded: 'superseded',
+  unobservable: 'cannot be followed',
+}
+
+export const CNPG_OP_STATE_TONE: Record<CNPGOpState, HealthLevel> = {
+  requested: 'neutral',
+  observed: 'neutral',
+  progressing: 'neutral',
+  completed: 'healthy',
+  failed: 'unhealthy',
+  stalled: 'degraded',
+  superseded: 'unknown',
+  unobservable: 'unknown',
+}
+
+export const CNPG_OP_STATE_SEVERITY: Record<CNPGOpState, 'success' | 'error' | 'warning' | 'info' | 'neutral'> = {
+  requested: 'info',
+  observed: 'info',
+  progressing: 'info',
+  completed: 'success',
+  failed: 'error',
+  stalled: 'warning',
+  superseded: 'neutral',
+  unobservable: 'neutral',
+}
+
+export interface CNPGOperationSubject {
+  apiBase: string
+  context: string
+  namespace: string
+  name: string
+}
+
+export function cnpgOperationsForCluster(
+  ops: CNPGTrackedOperation[],
+  subject: CNPGOperationSubject & { uid?: string },
+): CNPGTrackedOperation[] {
+  return ops.filter(
+    (op) =>
+      op.apiBase === subject.apiBase &&
+      op.context === subject.context &&
+      op.namespace === subject.namespace &&
+      op.cluster === subject.name &&
+      (subject.uid === undefined || !op.clusterUID || op.clusterUID === subject.uid),
+  )
+}
+
+export function latestCNPGOperation(
+  ops: CNPGTrackedOperation[],
+  subject: CNPGOperationSubject & { uid: string },
+): CNPGTrackedOperation | undefined {
+  return cnpgOperationsForCluster(ops, subject).reduce<CNPGTrackedOperation | undefined>(
+    (latest, op) => (!latest || op.startedAt > latest.startedAt ? op : latest),
+    undefined,
+  )
+}
+
+export function cnpgOperationHandoff(op: CNPGTrackedOperation, liveURL: string): string {
+  return [
+    `CloudNativePG: ${op.namespace}/${op.cluster}`,
+    `Context: ${op.context}`,
+    `Cluster UID: ${op.clusterUID || 'not recorded; confirm the live identity'}`,
+    `Action: ${op.label}`,
+    `Requested: ${new Date(op.startedAt).toISOString()}`,
+    `State in this tab: ${CNPG_OP_STATE_TEXT[op.state]}`,
+    `Last checked: ${op.lastCheckedAt ? new Date(op.lastCheckedAt).toISOString() : 'not yet checked'}`,
+    ...(op.detail ? [`Observation: ${op.detail}`] : []),
+    ...(op.steps?.map(
+      (step) => `[${step.done === true ? 'observed' : step.done === false ? 'pending' : 'unknown'}] ${step.label}`,
+    ) ?? []),
+    `Live Cluster: ${liveURL}`,
+    'This is a local observation record, not a shared operation history. Open the link to inspect current Kubernetes facts and verify the remaining steps.',
+  ].join('\n')
+}