@skyhook-io/radar-app 1.8.13 → 1.9.0

package/src/api/timelineSource.ts

@@ -2,7 +2,7 @@
 //
 // Radar's timeline can be backed by two stores:
 //   - 'local'    — the in-process event store the Radar binary keeps (default,
-//                  OSS standalone). Fetched via GET {apiBase}/changes.
+//                  OSS standalone). Fetched via GET {apiBase}/timeline/events.
 //   - 'retained' — a longer-horizon history store answered upstream of Radar
 //                  (relative to apiBase) as GET {apiBase}/timeline/events and
 //                  GET {apiBase}/timeline/overview. This is an extension point:
@@ -12,10 +12,10 @@
 //
 // Both sources expose the same `useEvents(query)` hook shape so the timeline
 // wrappers stay source-agnostic: pick the source from context, call useEvents.
-import { useMemo } from 'react'
-import { useQuery, keepPreviousData } from '@tanstack/react-query'
-import { quantizeBaseWindow } from '@skyhook-io/k8s-ui'
-import { useChanges, apiFetch, ApiError, type UseChangesOptions } from './client'
+import { useEffect, useMemo, useState } from 'react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { LIVE_TICK_MS } from '@skyhook-io/k8s-ui'
+import { apiFetch, mergeDeltaEvents, ApiError, type UseChangesOptions } from './client'
 import { apiUrl, getApiBase } from './config'
 import type { TimelineEvent, TimeRange } from '../types'
 
@@ -29,15 +29,14 @@ export type TimelineQuery = UseChangesOptions & {
   // [from,to] client-side.
   fromMs?: number
   toMs?: number
-  // LIVE mode: the [from,to] window slides every tick. Quantize the BASE fetch
-  // window to fixed steps so the react-query key only changes every few minutes;
-  // the precise sliding window is still applied by the client-side filter, and
-  // the trailing seam is covered by the live poll. Ignored by the local source.
-  sliding?: boolean
 }
 
 export interface TimelineSourceCapabilities {
   mode: 'local' | 'retained'
+  // The server's per-request row ceiling for this source — the number the
+  // truncation copy must cite (the local binary pages at 10k, a retained
+  // backend at 50k).
+  ringLimit: number
   // Only meaningful for 'retained': the maximum lookback the retained backend
   // serves. Clamps EVERY derived range (rangeSpanMs, not just 'all'), the
   // from-edge of an explicit [from,to] window, and the scrubber's selectable
@@ -101,11 +100,29 @@ export interface TimelineOverviewResult {
 export interface TimelineEventsResult {
   data: TimelineEvent[] | undefined
   isLoading: boolean
+  // Broad "is loading" signal: any fetch for the requested data is in flight,
+  // INCLUDING routine background polls (every ~10s on the retained source).
+  // Do not drive user-visible loaders from this — they would flicker on every
+  // poll; use isLoading (true only with no data at all) for loaders. Period
+  // changes re-window the loaded ring client-side in both sources, so they
+  // never fetch and never signal either flag; the one exception is a frozen
+  // [from,to] selection reaching below a truncated ring, which fetches its
+  // own window once and signals both flags while it does.
   isFetching: boolean
   isError: boolean
+  // The failure behind isError, when one is available. Surfaced so the UI can
+  // show the server's actionable message (e.g. the retained row-cap "narrow the
+  // from/to range") instead of a generic "failed to load".
+  error?: Error | null
   refetch: () => void
   // Present only for sources that report coverage (retained).
   coverage?: TimelineCoverageRecord[]
+  // The load serving the data was row-capped, so the OLDEST part of what it
+  // asked for is not loaded — the ring load when the ring serves, the window
+  // load when a frozen selection fetched its own window. Hosts must surface
+  // this — rendering a truncated result without a note reads as "nothing
+  // older happened".
+  truncated?: boolean
 }
 
 export interface TimelineSource {
@@ -122,57 +139,17 @@ export interface TimelineSourceConfig {
 }
 
 // ============================================================================
-// Local source — thin wrapper over the existing useChanges behavior. Zero
-// behavioral change for OSS standalone.
+// Local source — the same ring-and-delta hook as retained, pointed at the
+// Radar binary's own /timeline/events endpoint. One mechanism, two depths.
 // ============================================================================
 
-// Full ring size to pull when the host bounds the local list by the shared
-// scrubber selection — matches the swimlane's ring fetch so both views cover the
-// same window.
+// The local binary's per-request row ceiling (its /timeline/events pages at
+// 10k, matching the default in-process ring size).
 const LOCAL_RING_LIMIT = 10000
 
-function useLocalEvents(query: TimelineQuery): TimelineEventsResult {
-  // Without a window the dropdown-driven `since` fetch is untouched. When the
-  // host drives an explicit [from,to] window (the shared scrubber selection),
-  // the private range dropdown is bypassed: the local /changes endpoint is
-  // `since`-based and can't express a frozen past window, so load the whole ring
-  // and bound it to the selection client-side (applyClientFilters), exactly as
-  // the swimlane derives its view from the loaded ring.
-  const windowed = query.fromMs != null || query.toMs != null
-  // deltaSync on every full-ring pull (timeRange 'all' — the swimlane's direct
-  // query and the list's windowed one): SSE-driven refetches then transfer only
-  // what arrived since the last full load. Dropdown-ranged (`since`) queries
-  // stay plain — they're small and their range moves with the clock.
-  const { data, isLoading, isFetching, isError, refetch } = useChanges(
-    windowed
-      ? { ...query, timeRange: 'all', limit: LOCAL_RING_LIMIT, deltaSync: true }
-      : { ...query, deltaSync: query.timeRange === 'all' },
-  )
-  // applyClientFilters runs on BOTH paths: a multi-kind selection is a CLIENT-side
-  // filter (only a single kind rides the /changes server query key), so a 2+ kind
-  // pick is narrowed here whether or not a window is set. A non-windowed query has
-  // null from/to, so the [from,to] bounding inside is a no-op there; the windowed
-  // path additionally bounds the loaded ring. The memo watches kindsKey itself —
-  // `data` identity won't change when only the kind set does.
-  const kindsKey = query.kinds?.join(',')
-  const events = useMemo(
-    () => (data ? applyClientFilters(data, query) : data),
-    // `data` identity captures every server-side filter change (namespaces,
-    // k8s-events, deleted — all in the useChanges query key); the client-only
-    // window + cap + kind set are added here, plus includeManaged, which is
-    // client-enforced and must not depend on staying in the server key. The
-    // live tick advances query.toMs, re-filtering to the sliding edge with no
-    // refetch.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [data, query.fromMs, query.toMs, query.limit, kindsKey, query.includeManaged],
-  )
-  return { data: events, isLoading, isFetching, isError, refetch }
-}
-
-export const localSource: TimelineSource = {
-  capabilities: { mode: 'local' },
-  useEvents: useLocalEvents,
-}
+// The local anti-entropy cadence: a full ring reload is a cheap same-host
+// request, so server-side evictions surface within minutes.
+const LOCAL_FULL_RESYNC_MS = 5 * 60 * 1000
 
 const LOCAL_HOUR_MS = 60 * 60 * 1000
 
@@ -252,53 +229,85 @@ const DAY_MS = 24 * HOUR_MS
 // Bound for the 'all' range when the host doesn't specify maxRangeDays.
 const DEFAULT_RETAINED_MAX_RANGE_DAYS = 7
 
-// Recent window the live poll re-fetches and merges over the loaded range. Wide
-// enough that a missed 10s tick can't open a gap. Exported so a unit test can pin
-// it against the base-window quantization step (quantization lag < poll window).
-export const LIVE_WINDOW_MS = 10 * 60 * 1000
-const LIVE_REFETCH_MS = 10_000
-
-function rangeSpanMs(range: TimeRange | undefined, maxRangeDays?: number): number {
-  const cap = (maxRangeDays ?? DEFAULT_RETAINED_MAX_RANGE_DAYS) * DAY_MS
-  let span: number
+// The retained source is the SAME accumulate model as the local source,
+// pointed at the hub: one ring load (the newest RETAINED_RING_LIMIT events
+// over the retention depth), then a poll for everything INGESTED since a
+// server-issued cursor. Ingestion order is what makes the poll complete —
+// a late-arriving or revised event has an old event time but a fresh
+// ingestion time, so it rides the same poll as brand-new events. Period
+// changes re-window the loaded ring client-side; no fetch.
+
+// Matches the hub's per-response row cap. A window holding more arrives as
+// the newest RETAINED_RING_LIMIT events with `truncated` set — ring
+// semantics, exactly like the local source's capped ring, never a silent cut.
+export const RETAINED_RING_LIMIT = 50_000
+
+// Depth ceiling of the initial ring load; the hub rejects wider windows.
+const RETAINED_MAX_DEPTH_DAYS = 31
+
+// Delta poll cadence. Same order as the local source's SSE-nudged refetches.
+const RETAINED_POLL_MS = 10_000
+
+// A row-capped delta page sets `more`; the fetch pages forward immediately,
+// bounded so a pathological feed can't spin a single poll forever.
+const RETAINED_DELTA_MAX_PAGES = 10
+
+// Anti-entropy: a periodic full ring reload, the retained twin of the local
+// source's FULL_RESYNC_MS. Catches what deltas structurally can't — server-
+// side deletions, coverage-gap updates, and a stale truncated flag. Hourly,
+// not the local 5 minutes: a full ring is a heavy transfer and the delta feed
+// carries revisions, so entropy accumulates far slower here.
+const RETAINED_FULL_RESYNC_MS = 60 * 60 * 1000
+
+// Client-vs-hub clock skew allowance, applied at both edges of the ring:
+// the initial window's recent edge extends past the client clock by this
+// slack (a clock BEHIND the hub would otherwise exclude already-ingested
+// events in (clientNow, hubNow] — and the delta cursor already covers them,
+// so no poll would ever deliver them; the window slides back by the same
+// slack to stay within the hub's maximum range), and the delta-merge prune
+// floor sits below the retention depth by the same slack (a clock AHEAD of
+// the hub would otherwise prune oldest events the hub still retains).
+export const RETAINED_CLOCK_SKEW_SLACK_MS = 5 * 60 * 1000
+
+// How often a preset-derived window's sliding lower bound refreshes on an
+// IDLE ring (the no-op cached return keeps ring identity stable, so the memo
+// otherwise never re-samples the clock and a "24h" label slowly overstays).
+const RETAINED_PRESET_TICK_MS = 5 * 60 * 1000
+
+// The client-side spans the `timeRange` presets resolve to when no explicit
+// [from,to] window rides the query — the retained twin of the local source's
+// server-side `since` resolution. Preset arms return their nominal span; only
+// 'all'/unset falls back to the ring depth — clamping a preset wider than a
+// shallow host is the CALLER's job (Math.min at the use site). Exported for
+// unit tests; not re-exported publicly.
+export function rangeSpanMs(range: TimeRange | undefined, capMs?: number): number | undefined {
   switch (range) {
-    case '5m':
-      span = 5 * 60 * 1000
-      break
-    case '30m':
-      span = 30 * 60 * 1000
-      break
-    case '1h':
-      span = HOUR_MS
-      break
-    case '6h':
-      span = 6 * HOUR_MS
-      break
-    case '24h':
-      span = 24 * HOUR_MS
-      break
-    case '7d':
-      span = 7 * DAY_MS
-      break
-    case '30d':
-      span = 30 * DAY_MS
-      break
-    case 'all':
-    case undefined:
-      span = cap
-      break
-    default:
-      span = HOUR_MS
+    case '5m': return 5 * 60 * 1000
+    case '30m': return 30 * 60 * 1000
+    case '1h': return HOUR_MS
+    case '6h': return 6 * HOUR_MS
+    case '24h': return 24 * HOUR_MS
+    case '7d': return 7 * DAY_MS
+    case '30d': return 30 * DAY_MS
+    default: return capMs
   }
-  return Math.min(span, cap)
 }
 
 interface RetainedWindowResult {
   events: TimelineEvent[]
   coverage: TimelineCoverageRecord[]
+  // Next delta cursor (opaque, server-issued). Absent when talking to a hub
+  // that predates the delta feed.
+  cursor?: string
+  // Delta page was row-capped; poll again immediately from `cursor`.
+  more: boolean
+  // Ring load shipped only the newest slice of the window.
+  truncated: boolean
 }
 
-type TerminalRecord = { type: 'end' } | { type: 'error'; message?: string }
+type TerminalRecord =
+  | { type: 'end'; cursor?: string; more?: boolean; truncated?: boolean }
+  | { type: 'error'; message?: string }
 
 // De-dupe by id keeping the LAST occurrence — a later revision of an event
 // replaces the earlier one.
@@ -308,16 +317,9 @@ function dedupeById(events: TimelineEvent[]): TimelineEvent[] {
   return Array.from(byId.values())
 }
 
-// Exported for unit tests (the NDJSON stream parser); not re-exported publicly.
-export async function fetchRetainedWindow(
-  from: number,
-  to: number,
-  signal?: AbortSignal,
-): Promise<RetainedWindowResult> {
-  const res = await apiFetch(
-    apiUrl(`/timeline/events?from=${Math.round(from)}&to=${Math.round(to)}`),
-    signal ? { signal } : undefined,
-  )
+// Shared NDJSON stream reader for both events endpoints (window and delta).
+async function fetchRetainedStream(path: string, signal?: AbortSignal): Promise<RetainedWindowResult> {
+  const res = await apiFetch(apiUrl(path), signal ? { signal } : undefined)
   if (!res.ok) {
     const errorData = await res.json().catch(() => ({ error: `HTTP ${res.status}` }))
     throw new ApiError(errorData.error || `HTTP ${res.status}`, res.status, errorData)
@@ -336,9 +338,9 @@ export async function fetchRetainedWindow(
   const handleLine = (line: string): void => {
     const trimmed = line.trim()
     if (!trimmed) return
-    const rec = JSON.parse(trimmed) as { type?: string; message?: string }
+    const rec = JSON.parse(trimmed) as { type?: string; message?: string; cursor?: string; more?: boolean; truncated?: boolean }
     if (rec.type === 'end') {
-      terminal = { type: 'end' }
+      terminal = { type: 'end', cursor: rec.cursor, more: rec.more, truncated: rec.truncated }
     } else if (rec.type === 'error') {
       terminal = { type: 'error', message: rec.message }
     } else if (rec.type === 'coverage') {
@@ -365,11 +367,56 @@ export async function fetchRetainedWindow(
   if (!terminal) {
     throw new Error('timeline stream truncated (missing terminal record)')
   }
-  if ((terminal as TerminalRecord).type === 'error') {
-    throw new Error((terminal as { message?: string }).message || 'timeline stream error')
+  const end = terminal as TerminalRecord
+  if (end.type === 'error') {
+    throw new Error(end.message || 'timeline stream error')
   }
+  return {
+    events: dedupeById(events),
+    coverage,
+    cursor: end.cursor,
+    more: end.more === true,
+    truncated: end.truncated === true,
+  }
+}
 
-  return { events: dedupeById(events), coverage }
+// The ring load: newest `limit` events overlapping [from, to], plus the delta
+// cursor to continue from. Exported for unit tests; not re-exported publicly.
+export async function fetchRetainedWindow(
+  from: number,
+  to: number,
+  signal?: AbortSignal,
+  limit?: number,
+  namespaces?: string[],
+): Promise<RetainedWindowResult> {
+  const limitParam = limit ? `&limit=${limit}` : ''
+  return fetchRetainedStream(
+    `/timeline/events?from=${Math.round(from)}&to=${Math.round(to)}${limitParam}${namespacesParam(namespaces)}`,
+    signal,
+  )
+}
+
+// A namespace-scoped consumer must scope the SERVER query, not just the
+// client filter: the ring is row-capped, so an all-namespace ring on a busy
+// cluster could spend its whole budget on other namespaces' events. A server
+// that scopes only by time ignores the parameter and the client filter still
+// applies.
+function namespacesParam(namespaces?: string[]): string {
+  if (!namespaces || namespaces.length === 0) return ''
+  return `&namespaces=${encodeURIComponent(namespaces.join(','))}`
+}
+
+// The delta poll: everything ingested since the cursor, in ingestion order.
+// Exported for unit tests; not re-exported publicly.
+export async function fetchRetainedDelta(
+  cursor: string,
+  signal?: AbortSignal,
+  namespaces?: string[],
+): Promise<RetainedWindowResult> {
+  return fetchRetainedStream(
+    `/timeline/events?since=${encodeURIComponent(cursor)}${namespacesParam(namespaces)}`,
+    signal,
+  )
 }
 
 // Mirrors the Go store's TimelineEvent.IsManaged (pkg/timeline/types.go):
@@ -424,88 +471,337 @@ export function applyClientFilters(events: TimelineEvent[], query: TimelineQuery
   return out
 }
 
-function mergeWindows(
-  base: RetainedWindowResult | undefined,
-  live: RetainedWindowResult | undefined,
-): RetainedWindowResult {
-  // live is newer, so it overwrites base for shared ids.
-  const events = dedupeById([...(base?.events ?? []), ...(live?.events ?? [])])
-  const coverage = [...(base?.coverage ?? []), ...(live?.coverage ?? [])]
-  return { events, coverage }
+// The retained ring: what the single query holds. Same shape idea as the
+// local source's cached page, plus retention extras (coverage, truncation).
+export interface RetainedRing {
+  events: TimelineEvent[]
+  coverage: TimelineCoverageRecord[]
+  truncated: boolean
+  // The delta cursor rides the SAME react-query commit as the events it
+  // describes: an aborted or discarded fetch discards both together, so the
+  // cursor can never advance past events that were thrown away. Absent = the
+  // hub predates the delta feed; polls become no-ops (manual refresh still
+  // resyncs) instead of hammering it with a full reload every tick.
+  cursor?: string
+  // When the last FULL ring load ran — the anti-entropy resync clock.
+  loadedAtMs: number
 }
 
-function createRetainedEventsHook(
-  capabilities: TimelineSourceCapabilities,
-): (query: TimelineQuery) => TimelineEventsResult {
-  return function useRetainedEvents(query: TimelineQuery): TimelineEventsResult {
-    const enabled = query.enabled ?? true
+// Whether an explicit [from,to] selection reaches below what the loaded ring
+// holds. A truncated ring kept only the NEWEST rows, so a selection whose
+// from-edge is older than the ring's oldest loaded event would render rows the
+// server still holds as empty — such a window must fetch itself. An
+// untruncated ring holds everything its depth covers, so every selection
+// slices it client-side with no fetch.
+//
+// The ring stays authoritative only while the window reaches to/past the
+// NEWEST loaded ring row: every ring row then falls inside the window, and
+// the ring being the server's globally-newest-ringLimit rows makes them the
+// newest-ringLimit rows within the window too — a server window fetch would
+// return the identical set. A window whose to-edge is BELOW the newest ring
+// row excludes the freshest rows, so a server fetch spends that budget on
+// older rows the truncated ring dropped — such a window must fetch itself.
+// The guard is ring-relative, not wall-clock: distance from the clock proves
+// nothing about coverage (under heavy churn the ring's whole budget can sit
+// inside the last few minutes, leaving a just-frozen window's slice empty).
+//
+// Two allowances keep the LIVE sliding selection — an explicit [from,to]
+// re-derived from the clock on a coarse tick — on the zero-fetch ring path:
+// the newest-row edge caps at `now` (a hub clock ahead of the client stamps
+// ring rows in the client's future; they must not outrun a to-edge that
+// tracks the client clock), and the comparison tolerates one tick of lag
+// (delta merges land fresh rows while the live to-edge waits for its next
+// re-derive; without the tolerance every merge would re-key a full-window
+// fetch until the tick catches up).
+//
+// An empty truncated ring (or one with no parseable timestamps) proves
+// nothing about coverage, so it fails toward fetching. Exported for unit
+// tests; not re-exported publicly.
+const LIVE_WINDOW_TICK_SLACK_MS = 2 * LIVE_TICK_MS
+export function needsWindowFetch(
+  ring: Pick<RetainedRing, 'events' | 'truncated'>,
+  fromMs: number,
+  toMs: number,
+  now: number,
+): boolean {
+  if (!ring.truncated) return false
+  let oldest = Number.POSITIVE_INFINITY
+  let newest = Number.NEGATIVE_INFINITY
+  for (const e of ring.events) {
+    const t = new Date(e.timestamp).getTime()
+    if (!Number.isFinite(t)) continue
+    if (t < oldest) oldest = t
+    if (t > newest) newest = t
+  }
+  if (Number.isFinite(newest) && toMs >= Math.min(newest, now) - LIVE_WINDOW_TICK_SLACK_MS) return false
+  return fromMs < oldest
+}
 
-    // Pin the base window when the range (or cap) changes — not on every render —
-    // so the query key is stable and react-query can cache it. Recency is the
-    // live poll's job.
-    const window = useMemo<TimelineRange>(() => {
-      if (query.fromMs != null && query.toMs != null) {
-        // An explicit window (frozen brush, or a hand-entered ?from&to) must not
-        // reach further back than maxRangeDays — the same cap rangeSpanMs applies
-        // to the range-derived branch below. Anchor at the recent edge.
-        const capMs = (capabilities.maxRangeDays ?? DEFAULT_RETAINED_MAX_RANGE_DAYS) * DAY_MS
-        const from = Math.max(query.fromMs, query.toMs - capMs)
-        // Sliding: quantize so two ticks inside one step share a query key (no
-        // refetch). The precise [from,to] is still enforced by applyClientFilters.
-        if (query.sliding) {
-          const q = quantizeBaseWindow(from, query.toMs)
-          return { from: q.fromMs, to: q.toMs }
+// A frozen window never slides and never polls, so it refetches only on a
+// genuinely new mount past this staleness. Not cached forever: a late-ingested
+// event CAN land inside an old window, so an aged cache entry may still
+// refresh.
+const FROZEN_WINDOW_STALE_MS = 10 * 60 * 1000
+
+// Ring keys whose next fetch must be a full reload (manual refresh). A side
+// flag, not a side cursor: consuming it only switches the PATH of the next
+// fetch — all sync state that must stay consistent with the data lives inside
+// RetainedRing itself.
+const retainedForceResync = new Set<string>()
+
+// Ring-fetch orchestration, the retained twin of client.ts's
+// runDeltaSyncFetch: full ring load when there's no cached page (or a resync
+// is due), else delta pages merged in with replace-by-id. Extracted so the
+// full-load → delta-poll → cursor-reset contract is exercisable without a
+// React render; state (the cached page, the force flag) is passed in
+// explicitly.
+export async function runRetainedRingFetch(deps: {
+  ringKey: string
+  cached: RetainedRing | undefined
+  forceResync: Set<string>
+  // Retention depth of the backend. Undefined = unbounded (a local store may
+  // be configured to retain forever): the full load starts at epoch zero and
+  // delta merges never age-prune - the ring row cap is the only bound.
+  capMs?: number
+  now: number
+  signal?: AbortSignal
+  // Ring row cap: the server's per-request ceiling for this source (the hub
+  // serves up to 50k; the local binary pages at 10k). Also bounds delta
+  // accumulation client-side.
+  ringLimit?: number
+  // Scope the server query when the consumer is namespace-scoped; see
+  // namespacesParam.
+  namespaces?: string[]
+  // Anti-entropy cadence: how stale the ring may get before a full reload
+  // (server-side evictions and retention prunes are invisible to deltas).
+  // The local binary reloads cheaply so it keeps its historical 5-minute
+  // cadence; a Cloud ring is a heavy transfer and resyncs hourly.
+  resyncMs?: number
+}): Promise<RetainedRing> {
+  const {
+    ringKey, cached, forceResync, capMs, now, signal,
+    ringLimit = RETAINED_RING_LIMIT, namespaces, resyncMs = RETAINED_FULL_RESYNC_MS,
+  } = deps
+  // Anti-entropy: past the resync window (or on manual refresh), fall through
+  // to a full reload regardless of cursor state — refreshing coverage,
+  // recomputing the truncated flag, and dropping anything deltas can't
+  // retract.
+  // A negative age (loadedAtMs in the future — backward clock step, suspend/
+  // resume) counts as due: the resync clock must fail toward refreshing, not
+  // toward silently suspending anti-entropy for hours.
+  const ringAge = cached != null ? now - cached.loadedAtMs : 0
+  const resyncDue = forceResync.has(ringKey) || (cached != null && (ringAge < 0 || ringAge > resyncMs))
+  if (cached && !resyncDue) {
+    if (!cached.cursor) {
+      return cached
+    }
+    try {
+      let cursor = cached.cursor
+      let merged = cached.events
+      let changed = false
+      for (let page = 0; page < RETAINED_DELTA_MAX_PAGES; page++) {
+        const delta = await fetchRetainedDelta(cursor, signal, namespaces)
+        if (delta.cursor) cursor = delta.cursor
+        if (delta.events.length) {
+          merged = mergeDeltaEvents(merged, delta.events, Number.POSITIVE_INFINITY)
+          changed = true
         }
-        return { from, to: query.toMs }
+        if (!delta.more) break
       }
-      const to = Date.now()
-      return { from: to - rangeSpanMs(query.timeRange, capabilities.maxRangeDays), to }
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [query.fromMs, query.toMs, query.timeRange, query.sliding, capabilities.maxRangeDays])
+      // Returning the cached reference on a no-op delta skips re-renders. An
+      // idle cluster's cursor is stable by construction — verified against the
+      // hub: EventsIngestedSince starts its frontier AT `since` and advances
+      // it only past emitted rows, and the read-side clamp can only lower a
+      // frontier that already rests at or below the visibility edge.
+      if (!changed && cursor === cached.cursor) return cached
+      // Two bounds keep an always-open tab from growing without limit: the
+      // retention floor (the server TTL-deletes past the same boundary,
+      // held below the depth by the skew slack so a client clock ahead of
+      // the hub cannot prune events the hub still retains) and the ring row
+      // cap — accumulation past it drops the OLDEST rows, the same
+      // semantics as the initial load and the local source's ring, and
+      // flips `truncated` so the UI says so.
+      const floor = capMs != null ? now - capMs - RETAINED_CLOCK_SKEW_SLACK_MS : Number.NEGATIVE_INFINITY
+      const pruned = capMs != null ? merged.filter((e) => new Date(e.timestamp).getTime() >= floor) : merged
+      const capped = pruned.length > ringLimit
+      return {
+        events: capped ? pruned.slice(0, ringLimit) : pruned,
+        coverage: cached.coverage,
+        truncated: cached.truncated || capped,
+        cursor,
+        loadedAtMs: cached.loadedAtMs,
+      }
+    } catch (err) {
+      // A rejected cursor (hub restarted onto an older build, operator wiped
+      // the store) is recoverable: fall through to a full reload. Anything
+      // else propagates — react-query keeps the cached ring visible.
+      if (!(err instanceof ApiError && err.status === 400)) {
+        throw err
+      }
+    }
+  }
+  // The recent edge extends past the client clock by the skew slack (a client
+  // clock behind the hub would otherwise leave a permanent hole: events in
+  // (clientNow, hubNow] are under the returned cursor, so no delta re-delivers
+  // them). The window slides back by the same slack to stay within the hub's
+  // maximum range.
+  const to = now + RETAINED_CLOCK_SKEW_SLACK_MS
+  const full = await fetchRetainedWindow(capMs != null ? to - capMs : 0, to, signal, ringLimit, namespaces)
+  // Consume the flag only while this fetch still owns the query. A resolved
+  // load can still be discarded — a manual refresh cancels the in-flight poll
+  // AFTER its network call finished — and deleting then would eat the flag
+  // that refresh just armed, turning it into a silent no-op delta poll.
+  if (!signal?.aborted) forceResync.delete(ringKey)
+  return {
+    events: full.events,
+    coverage: full.coverage,
+    truncated: full.truncated,
+    cursor: full.cursor,
+    loadedAtMs: now,
+  }
+}
 
-    const base = useQuery<RetainedWindowResult>({
-      // apiBase scopes the key: a host that swaps clusters (mutable module global)
-      // must not serve the previous cluster's cached window.
-      queryKey: ['timeline-retained', getApiBase(), 'base', window.from, window.to],
-      queryFn: ({ signal }) => fetchRetainedWindow(window.from, window.to, signal),
+// One events hook for every mode. Local and hub-backed timelines share the
+// whole cycle — ring load, cursor deltas, client-side re-windowing — and
+// differ only in depth (capMs) and the server's per-request row ceiling
+// (ringLimit). The endpoint path is identical (`{apiBase}/timeline/events`);
+// apiBase alone decides which server answers.
+function createRingEventsHook(opts: {
+  // Undefined = unbounded depth (the server's own retention is the bound).
+  capMs?: number
+  ringLimit: number
+  resyncMs: number
+}): (query: TimelineQuery) => TimelineEventsResult {
+  const { capMs, ringLimit, resyncMs } = opts
+  return function useRingEvents(query: TimelineQuery): TimelineEventsResult {
+    const enabled = query.enabled ?? true
+    const queryClient = useQueryClient()
+
+    // The key carries the depth, the apiBase (a host that swaps clusters must
+    // not serve the previous cluster's ring), and the namespace scope (the
+    // ring is row-capped, so the SERVER query must be scoped for a
+    // namespace-scoped consumer — an all-namespace ring could spend its whole
+    // budget elsewhere). It does NOT carry the query's [from,to]: period
+    // changes re-window the loaded ring client-side in applyClientFilters,
+    // issuing no fetch. A frozen window the ring cannot answer runs its own
+    // separately-keyed query below instead of widening the ring.
+    const apiBase = getApiBase()
+    const ringNamespacesKey = query.namespaces?.length ? [...query.namespaces].sort().join(',') : ''
+    const queryKey = useMemo(
+      () => ['timeline-ring', apiBase, capMs ?? 'unbounded', ringNamespacesKey],
+      [apiBase, ringNamespacesKey],
+    )
+
+    const ring = useQuery<RetainedRing>({
+      queryKey,
+      queryFn: ({ signal }) =>
+        runRetainedRingFetch({
+          ringKey: JSON.stringify(queryKey),
+          cached: queryClient.getQueryData<RetainedRing>(queryKey),
+          forceResync: retainedForceResync,
+          capMs,
+          now: Date.now(),
+          signal,
+          ringLimit,
+          namespaces: ringNamespacesKey ? ringNamespacesKey.split(',') : undefined,
+          resyncMs,
+        }),
       enabled,
-      staleTime: LIVE_REFETCH_MS,
-      // The base window quantizes to fixed steps, so its key rotates every few
-      // minutes even while live. Hold the previous window's events through the
-      // refetch instead of blanking the range on each rotation.
-      placeholderData: keepPreviousData,
+      refetchInterval: RETAINED_POLL_MS,
+      staleTime: 5000,
     })
 
-    // Fixed recent-window re-poll. Key is stable; queryFn reads the clock fresh
-    // each tick so the window slides without churning the cache key. Skipped for
-    // a purely historical brush (its right edge is older than the live window),
-    // where recency merging would only add events the time filter drops.
-    const liveEnabled = enabled && (query.toMs == null || query.toMs >= Date.now() - LIVE_WINDOW_MS)
-    const live = useQuery<RetainedWindowResult>({
-      queryKey: ['timeline-retained', getApiBase(), 'live'],
+    // On a store holding more than ringLimit rows, an explicit frozen
+    // [from,to] older than the ring's oldest loaded event has NO rows in the
+    // ring even though the server holds them — slicing would render the deep
+    // past as empty. Such a window fetches itself: same endpoint, same wire
+    // contract in both modes. Ring-covered and live-edge windows never arm
+    // this query (see needsWindowFetch), so period changes and the live tick
+    // stay zero-fetch.
+    //
+    // The clock sample only refreshes when a dep changes; that is safe here
+    // because the predicate is ring-relative — the clock only caps the
+    // newest-row comparison against skew-stamped future rows, and a stale
+    // sample makes that cap tighter (toward the ring), never looser.
+    const windowFromMs = query.fromMs
+    const windowToMs = query.toMs
+    const windowNeeded = useMemo(
+      () =>
+        enabled && windowFromMs != null && windowToMs != null && ring.data != null &&
+        needsWindowFetch(ring.data, windowFromMs, windowToMs, Date.now()),
+      [enabled, windowFromMs, windowToMs, ring.data],
+    )
+    const windowQuery = useQuery<RetainedWindowResult>({
+      queryKey: ['timeline-window', apiBase, windowFromMs, windowToMs, ringNamespacesKey],
       queryFn: ({ signal }) => {
-        const to = Date.now()
-        return fetchRetainedWindow(to - LIVE_WINDOW_MS, to, signal)
+        if (windowFromMs == null || windowToMs == null) {
+          // Unreachable: `enabled` requires both bounds. Guards the invariant
+          // without a non-null assertion.
+          throw new Error('timeline window query ran without an explicit [from,to]')
+        }
+        return fetchRetainedWindow(
+          windowFromMs,
+          windowToMs,
+          signal,
+          ringLimit,
+          ringNamespacesKey ? ringNamespacesKey.split(',') : undefined,
+        )
       },
-      enabled: liveEnabled,
-      refetchInterval: LIVE_REFETCH_MS,
+      enabled: windowNeeded,
+      staleTime: FROZEN_WINDOW_STALE_MS,
     })
 
-    const merged = useMemo(
-      () => mergeWindows(base.data, live.data),
-      [base.data, live.data],
-    )
-
     const kindsKey = query.kinds?.join(',')
+    const namespacesKey = query.namespaces?.join(',')
+    // A preset-derived window slides with the clock; on an idle ring the memo
+    // would never re-sample it (the no-op cached return keeps ring identity
+    // stable), freezing a "24h" bound overnight. A coarse tick keeps the label
+    // honest without meaningful churn.
+    const derivedWindow =
+      query.fromMs == null && query.toMs == null && !!query.timeRange && query.timeRange !== 'all'
+    // Gated on `enabled` too: a disabled consumer (an unopened tab) must not
+    // pay a periodic re-filter of the shared ring. The bump on arming keeps
+    // the window fresh across a disable→enable gap (tab reopened hours later
+    // must not show the stale bound until the next tick).
+    const tickActive = derivedWindow && enabled
+    const [presetTick, setPresetTick] = useState(0)
+    useEffect(() => {
+      if (!tickActive) return
+      setPresetTick((t) => t + 1)
+      const id = setInterval(() => setPresetTick((t) => t + 1), RETAINED_PRESET_TICK_MS)
+      return () => clearInterval(id)
+    }, [tickActive])
     const data = useMemo(() => {
-      if (base.data === undefined && live.data === undefined) return undefined
-      return applyClientFilters(merged.events, query)
+      if (windowNeeded) {
+        // Serving from the frozen-window fetch. Same client filters as the
+        // ring path so the two are indistinguishable to consumers; undefined
+        // while in flight so the host shows a loader, not an empty ring slice.
+        return windowQuery.data ? applyClientFilters(windowQuery.data.events, query) : undefined
+      }
+      if (!ring.data) return undefined
+      // A `timeRange` preset without an explicit [from,to] window resolves to
+      // a client-side bound over the ring — the retained twin of the local
+      // source's server-side `since` resolution. Without this, a consumer
+      // like the Applications History tab picking "24h" would silently get
+      // the whole ring.
+      let effective = query
+      if (derivedWindow) {
+        const span = rangeSpanMs(query.timeRange, capMs)
+        if (span != null) {
+          effective = { ...query, fromMs: Date.now() - (capMs != null ? Math.min(span, capMs) : span) }
+        }
+      }
+      return applyClientFilters(ring.data.events, effective)
+      // Every filter is client-side here (the ring key carries none of them),
+      // so each rides the memo: array-valued ones via join keys so identity
+      // churn from the host doesn't re-filter. The live tick advances
+      // query.toMs, re-windowing to the sliding edge with no refetch.
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
-      merged,
-      base.data,
-      live.data,
-      query.namespaces,
+      ring.data,
+      windowNeeded,
+      windowQuery.data,
+      namespacesKey,
       kindsKey,
       query.includeK8sEvents,
       query.includeDeleted,
@@ -513,20 +809,44 @@ function createRetainedEventsHook(
       query.limit,
       query.fromMs,
       query.toMs,
+      query.timeRange,
+      capMs,
+      derivedWindow,
+      presetTick,
     ])
 
+    if (windowNeeded) {
+      // Every signal follows the query that serves the data: the ring keeps
+      // polling in the background, but its flags describe data the consumer
+      // is not looking at.
+      return {
+        data,
+        isLoading: windowQuery.isLoading,
+        isFetching: windowQuery.isFetching,
+        isError: windowQuery.isError,
+        error: windowQuery.error,
+        refetch: () => {
+          windowQuery.refetch()
+        },
+        coverage: windowQuery.data?.coverage,
+        truncated: windowQuery.data?.truncated,
+      }
+    }
+
     return {
       data,
-      isLoading: base.isLoading,
-      isFetching: base.isFetching || live.isFetching,
-      // Base failure is a real error; a failing live poll must not blank an
-      // already-loaded range.
-      isError: base.isError,
+      isLoading: ring.isLoading,
+      isFetching: ring.isFetching,
+      isError: ring.isError,
+      error: ring.error,
       refetch: () => {
-        base.refetch()
-        live.refetch()
+        // Manual refresh is the resync backstop: flag the ring so the next
+        // fetch reloads it whole instead of trusting accumulated state.
+        retainedForceResync.add(JSON.stringify(queryKey))
+        ring.refetch()
       },
-      coverage: merged.coverage,
+      coverage: ring.data?.coverage,
+      truncated: ring.data?.truncated,
     }
   }
 }
@@ -564,14 +884,31 @@ async function fetchRetainedOverview(range: TimelineRange): Promise<TimelineOver
   return { buckets, availableFromMs: env.availableFromMs }
 }
 
+export const localSource: TimelineSource = {
+  capabilities: { mode: 'local', ringLimit: LOCAL_RING_LIMIT },
+  useEvents: createRingEventsHook({
+    // No depth cap: the binary's own ring size and --timeline-retention are
+    // the real bounds, and retention may legitimately be unlimited. The ring
+    // row ceiling still bounds client-side growth.
+    ringLimit: LOCAL_RING_LIMIT,
+    resyncMs: LOCAL_FULL_RESYNC_MS,
+  }),
+}
+
 export function createRetainedSource(config: TimelineSourceConfig): TimelineSource {
   const capabilities: TimelineSourceCapabilities = {
     mode: 'retained',
+    ringLimit: RETAINED_RING_LIMIT,
     maxRangeDays: config.maxRangeDays,
   }
   return {
     capabilities,
-    useEvents: createRetainedEventsHook(capabilities),
+    useEvents: createRingEventsHook({
+      capMs:
+        Math.min(capabilities.maxRangeDays ?? DEFAULT_RETAINED_MAX_RANGE_DAYS, RETAINED_MAX_DEPTH_DAYS) * DAY_MS,
+      ringLimit: RETAINED_RING_LIMIT,
+      resyncMs: RETAINED_FULL_RESYNC_MS,
+    }),
     fetchOverview: fetchRetainedOverview,
   }
 }