@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/realtime/hub.server.ts

@@ -0,0 +1,318 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Kabmo's realtime hub: the one place a server-originated event enters,
+ * and the one place it leaves from. Every publisher calls
+ * `publish(topic, payload)`; every subscriber is a WebSocket connection from
+ * `@/server/routes/realtime/ws`. Nothing else fans out to clients.
+ *
+ * A snapshot is BUFFERED, not just sent: it is produced by an async resolver,
+ * so there is a window between "subscribed" and "its snapshot exists".
+ * Registering after the resolve loses a delta that lands inside that window;
+ * registering before it without buffering hands the client `delta seq 7` ahead
+ * of `snapshot seq 5`. The order is register → note `seq` → resolve → send the
+ * snapshot stamped with that `seq` → replay the deltas published meanwhile.
+ * `seq` is contiguous per topic, which is what lets a client detect a gap and
+ * ask for `resync` instead of sitting on stale data.
+ *
+ * Concurrent subscribers share one resolve; a later one starts a fresh resolve
+ * rather than a cached answer, because caching would reintroduce the staleness
+ * this transport exists to remove.
+ *
+ * State is anchored on `globalThis` for the reason the database handle is:
+ * `bun --hot` re-evaluates this module while the sockets it serves live on, so a
+ * module-level binding would orphan every connection's subscription.
+ */
+
+import type {
+  HubState,
+  RealtimeConnection,
+  RealtimeHub,
+  TopicDescriptor,
+  TopicEntry,
+} from '@/server/lib/realtime/hub.types';
+
+export type {
+  PendingDelta,
+  RealtimeConnection,
+  RealtimeHub,
+  TopicDescriptor,
+  TopicEntry,
+  TopicResolver,
+} from '@/server/lib/realtime/hub.types';
+
+/**
+ * Most deltas held while a snapshot resolves. A resolve is a few milliseconds
+ * of work, so overflow means a burst far beyond anything Kabmo produces;
+ * a connection that overflows is re-resolved rather than served a partial
+ * replay, because a silent gap is the one outcome this transport must not have.
+ */
+const MAX_PENDING_DELTAS = 256;
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoRealtimeHub: HubState | undefined;
+  // eslint-disable-next-line no-var
+  var __kabmoRealtimeHubInstance: RealtimeHub | undefined;
+}
+
+function state(): HubState {
+  return (globalThis.__kabmoRealtimeHub ??= { topics: new Map(), descriptors: new Map() });
+}
+
+/**
+ * Register the topics this hub serves. Called once at boot with the full
+ * registry; a later call replaces the descriptor set (a hot reload
+ * re-registers).
+ */
+export function registerTopics(descriptors: Map<string, TopicDescriptor>): void {
+  const host = state();
+  host.descriptors = descriptors;
+}
+
+export function createHub(): RealtimeHub {
+  const entryFor = (topic: string): TopicEntry => {
+    const host = state();
+    let entry = host.topics.get(topic);
+    if (!entry) {
+      entry = { seq: 0, subscribers: new Set(), detach: null, buffer: [], resolve: null, baseSeq: 0, overflowed: false };
+      host.topics.set(topic, entry);
+    }
+    return entry;
+  };
+
+  /** Drop a topic entry once nothing is watching it, so memory tracks demand. */
+  const reapIfIdle = (topic: string, entry: TopicEntry): void => {
+    if (entry.subscribers.size === 0 && entry.resolve === null) state().topics.delete(topic);
+  };
+
+  /**
+   * Serve one connection its snapshot, joining an in-flight resolve or starting
+   * one. Attempts are bounded: a connection that overflows the delta buffer is
+   * re-resolved once, and a second overflow is reported as an error rather than
+   * looping forever on a pathologically hot topic.
+   */
+  const deliverSnapshot = async (topic: string, connection: RealtimeConnection, attempt = 0): Promise<void> => {
+    const host = state();
+    const entry = entryFor(topic);
+    const resolver = host.descriptors.get(topic)?.resolve;
+    if (!resolver) {
+      connection.send({ t: 'error', code: 'unknown_topic', message: `Unknown topic: ${topic}`, topic });
+      return;
+    }
+
+    if (entry.resolve === null) {
+      entry.baseSeq = entry.seq;
+      entry.buffer = [];
+      entry.overflowed = false;
+      entry.resolve = resolver(topic).then(
+        (payload) => ({ ok: true as const, payload }),
+        (error: unknown) => ({ ok: false as const, error }),
+      );
+      // Clear the slot only after every awaiting connection has been served, so
+      // a subscriber arriving mid-flight joins THIS resolve rather than starting
+      // a second scan for the same topic.
+      void entry.resolve.then(() => {
+        entry.resolve = null;
+      });
+    }
+
+    const result = await entry.resolve;
+    if (connection.closed || !connection.topics.has(topic)) return;
+
+    if (!result.ok) {
+      const message = result.error instanceof Error ? result.error.message : String(result.error);
+      connection.send({ t: 'error', code: 'snapshot_failed', message, topic });
+      return;
+    }
+
+    if (entry.overflowed) {
+      if (attempt >= 1) {
+        connection.send({
+          t: 'error',
+          code: 'snapshot_failed',
+          message: `Topic ${topic} changed faster than its snapshot could be delivered.`,
+          topic,
+        });
+        return;
+      }
+      // A fresh snapshot is the honest repair: the buffered deltas are gone.
+      void deliverSnapshot(topic, connection, attempt + 1);
+      return;
+    }
+
+    const baseSeq = entry.baseSeq;
+    const replay = entry.buffer.filter((delta) => delta.seq > baseSeq);
+    connection.send({ t: 'snapshot', topic, seq: baseSeq, payload: result.payload });
+    for (const delta of replay) {
+      if (connection.closed) return;
+      connection.send({ t: 'delta', topic, seq: delta.seq, payload: delta.payload });
+    }
+    connection.snapshotted.add(topic);
+  };
+
+  /** Run the descriptor's `attach` for `topic` and store its cleanup. */
+  const bind = (topic: string, entry: TopicEntry): void => {
+    const attach = state().descriptors.get(topic)?.attach;
+    if (!attach) return;
+    try {
+      entry.detach = attach(topic) ?? null;
+    } catch {
+      entry.detach = null;
+    }
+  };
+
+  /** Release the descriptor's binding, if any. */
+  const dropBinding = (entry: TopicEntry): void => {
+    const detach = entry.detach;
+    entry.detach = null;
+    if (!detach) return;
+    try {
+      detach();
+    } catch {
+      // Unbinding is best-effort; a throwing cleanup must not break the caller.
+    }
+  };
+
+  /** Drop the descriptor's binding once nobody is watching. */
+  const detachIfIdle = (entry: TopicEntry): void => {
+    if (entry.subscribers.size > 0 || entry.detach === null) return;
+    dropBinding(entry);
+  };
+
+  return {
+    knows: (topic) => state().descriptors.has(topic),
+
+    resolve: (topic) => {
+      const descriptor = state().descriptors.get(topic);
+      if (!descriptor) return Promise.reject(new Error(`Unknown topic: ${topic}`));
+      return descriptor.resolve(topic);
+    },
+
+    subscribe(connection, topic) {
+      const entry = entryFor(topic);
+      const first = entry.subscribers.size === 0;
+      entry.subscribers.add(connection);
+      connection.topics.add(topic);
+      connection.snapshotted.delete(topic);
+      // Bind the source BEFORE the snapshot resolves: a delta published while
+      // the snapshot is in flight must reach the buffer, and an unbound source
+      // would simply never produce one.
+      if (first && entry.detach === null) bind(topic, entry);
+      void deliverSnapshot(topic, connection);
+    },
+
+    unsubscribe(connection, topic) {
+      const entry = entryFor(topic);
+      entry.subscribers.delete(connection);
+      connection.topics.delete(topic);
+      connection.snapshotted.delete(topic);
+      detachIfIdle(entry);
+      reapIfIdle(topic, entry);
+    },
+
+    release(connection) {
+      connection.closed = true;
+      for (const topic of [...connection.topics]) {
+        const entry = state().topics.get(topic);
+        if (!entry) continue;
+        entry.subscribers.delete(connection);
+        detachIfIdle(entry);
+        reapIfIdle(topic, entry);
+      }
+      connection.topics.clear();
+      connection.snapshotted.clear();
+    },
+
+    publishSnapshot(topic, payload) {
+      const entry = entryFor(topic);
+      entry.seq += 1;
+      const seq = entry.seq;
+      // The buffer is dropped: a snapshot supersedes whatever it held, and the
+      // awaiting connections are about to be given this baseline.
+      entry.buffer = [];
+      entry.overflowed = false;
+      for (const connection of entry.subscribers) {
+        if (connection.closed) continue;
+        connection.snapshotted.add(topic);
+        connection.send({ t: 'snapshot', topic, seq, payload });
+      }
+    },
+
+    republishSnapshot(topic) {
+      const entry = state().topics.get(topic);
+      if (!entry || entry.subscribers.size === 0) return;
+      // Re-resolve for EVERY subscriber: they are all at the same baseline, and
+      // a fresh snapshot is what repairs each of them.
+      for (const connection of [...entry.subscribers]) {
+        connection.snapshotted.delete(topic);
+        void deliverSnapshot(topic, connection);
+      }
+    },
+
+    rebind(topic) {
+      const entry = state().topics.get(topic);
+      // Nobody is watching: there is no binding to repair, and a topic with no
+      // subscribers must not hold a source open (see `detachIfIdle`).
+      if (!entry || entry.subscribers.size === 0) return;
+      // Replace the source binding wholesale. `attach` is bound ONCE per
+      // subscription, so a source that is REPLACED under a live subscriber (a
+      // session's omp child respawned by the idle reaper, an approval-mode
+      // reconcile, a crash) leaves the topic wired to the dead one — the
+      // subscriber keeps its subscription and receives snapshots but no frames,
+      // which reads as "the answer never streamed until I reloaded".
+      dropBinding(entry);
+      bind(topic, entry);
+    },
+
+    publish(topic, payload) {
+      const entry = entryFor(topic);
+      entry.seq += 1;
+      const seq = entry.seq;
+
+      // A connection still waiting on its snapshot cannot receive this as a
+      // live delta; the buffer is what it replays after the snapshot lands.
+      const awaiting = [...entry.subscribers].some((connection) => !connection.snapshotted.has(topic));
+      if (awaiting) {
+        if (entry.buffer.length >= MAX_PENDING_DELTAS) {
+          entry.overflowed = true;
+          entry.buffer = [];
+        } else {
+          entry.buffer.push({ seq, payload });
+        }
+      }
+
+      for (const connection of entry.subscribers) {
+        if (connection.closed || !connection.snapshotted.has(topic)) continue;
+        connection.send({ t: 'delta', topic, seq, payload });
+      }
+    },
+
+    sequenceOf: (topic) => entryFor(topic).seq,
+
+    activeTopics() {
+      const names: string[] = [];
+      for (const [topic, entry] of state().topics) {
+        if (entry.subscribers.size > 0) names.push(topic);
+      }
+      return names;
+    },
+  };
+}
+
+/**
+ * The process's single hub. Publishers and the WS route both resolve it here so
+ * a hot reload cannot leave a publisher writing into a discarded instance.
+ */
+export function getRealtimeHub(): RealtimeHub {
+  return (globalThis.__kabmoRealtimeHubInstance ??= createHub());
+}
+
+/** Test seam: drop the hub and its topic state. */
+export function resetRealtimeHub(): void {
+  globalThis.__kabmoRealtimeHub = undefined;
+  globalThis.__kabmoRealtimeHubInstance = undefined;
+}

package/src/server/lib/realtime/hub.types.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The realtime hub's contracts: the descriptor a topic is wired with, the
+ * connection the transport hands it, and the surface publishers and subscribers
+ * use.
+ *
+ * Split from `hub.server.ts` because the runtime there sits on the repo's
+ * 350-line ceiling, and these are the shapes two other modules (the WS route and
+ * the topic registry) need without pulling the implementation in.
+ */
+
+import type { RealtimeServerFrame } from '@/shared/lib/realtime/protocol';
+
+/** Resolves a topic to its current value. Rejects for a topic that cannot be read. */
+export type TopicResolver = (topic: string) => Promise<unknown>;
+
+/**
+ * A topic's server-side wiring. `attach` runs when the FIRST connection
+ * subscribes and its cleanup when the LAST one leaves — the only place a topic
+ * binds to a per-session source (an omp child's fanout, a BTW registry) without
+ * working for nobody, which is what makes "no subscribers, no work" true for a
+ * topic whose data is pushed rather than read.
+ */
+export interface TopicDescriptor {
+  resolve: TopicResolver;
+  /** Bind to the underlying source. Returns the cleanup that unbinds it. */
+  attach?: (topic: string) => (() => void) | void;
+}
+
+/** One connected client. `send` is the transport's own writer. */
+export interface RealtimeConnection {
+  readonly topics: Set<string>;
+  /** Topics whose snapshot this connection has already received. */
+  readonly snapshotted: Set<string>;
+  send: (frame: RealtimeServerFrame) => void;
+  closed: boolean;
+}
+
+export interface PendingDelta {
+  seq: number;
+  payload: unknown;
+}
+
+export interface TopicEntry {
+  /** Last published sequence number. Contiguous per topic. */
+  seq: number;
+  subscribers: Set<RealtimeConnection>;
+  /** Cleanup for the descriptor's `attach`, held while subscribers exist. */
+  detach: (() => void) | null;
+  /** Deltas published while a resolve is in flight, for the awaiting connections. */
+  buffer: PendingDelta[];
+  /** The in-flight resolve, shared by every connection that joined it. */
+  resolve: Promise<{ ok: true; payload: unknown } | { ok: false; error: unknown }> | null;
+  /** `seq` at the moment the current resolve started. */
+  baseSeq: number;
+  /** A resolve outran its buffer; awaiting connections need a fresh one. */
+  overflowed: boolean;
+}
+
+export interface RealtimeHub {
+  /** The topics this hub can serve. An unknown topic is refused, not ignored. */
+  knows: (topic: string) => boolean;
+  /**
+   * The CURRENT value of `topic`, through the descriptor this hub was
+   * registered with.
+   *
+   * Publishers that report a write by re-resolving must go through here rather
+   * than their own module's descriptor table: a test (or a future second
+   * registry) registers its own descriptors, and re-resolving from a private
+   * copy would answer from — or silently blank — a topic the hub never served.
+   */
+  resolve: (topic: string) => Promise<unknown>;
+  subscribe: (connection: RealtimeConnection, topic: string) => void;
+  unsubscribe: (connection: RealtimeConnection, topic: string) => void;
+  /** Drop every subscription of a closed connection. */
+  release: (connection: RealtimeConnection) => void;
+  /** Publish a topic's new value to its subscribers. */
+  publish: (topic: string, payload: unknown) => void;
+  /**
+   * Re-resolve `topic` and send the result as a fresh `snapshot`, resetting
+   * every subscriber's sequence baseline.
+   *
+   * For the case a delta cannot express: a topic whose SOURCE did not exist
+   * when it was first subscribed (a session with no omp child yet). The
+   * resolver is the same one `subscribe` uses, so the two can never disagree.
+   */
+  republishSnapshot: (topic: string) => void;
+  /**
+   * Re-run a topic's `attach` under its live subscribers.
+   *
+   * `attach` binds a topic to its SOURCE once per subscription, so a source
+   * that is REPLACED while the subscription stands (a session's omp child
+   * respawned by the idle reaper, a mode reconcile or a crash) leaves the topic
+   * wired to the old one: the subscriber receives snapshots and then silence.
+   * Called wherever the source is known to have been replaced; a no-op with no
+   * subscribers, so a topic nobody watches never holds a source open.
+   */
+  rebind: (topic: string) => void;
+  /**
+   * Send an EXTERNALLY produced snapshot to every subscriber of `topic`,
+   * resetting their baselines.
+   *
+   * For the peer bridge: an instance that does not own a session relays the
+   * owner's frames, and the owner's own snapshot must become this instance's
+   * subscribers' baseline — the local resolver cannot produce it (the child is
+   * not here).
+   */
+  publishSnapshot: (topic: string, payload: unknown) => void;
+  /** Test seam: the sequence number a topic is at. */
+  sequenceOf: (topic: string) => number;
+  /** Every topic with at least one subscriber, in subscription order. */
+  activeTopics: () => string[];
+}
+
+export interface HubState {
+  topics: Map<string, TopicEntry>;
+  descriptors: Map<string, TopicDescriptor>;
+}

package/src/server/lib/realtime/signals.server.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Named signals a server module raises when something a realtime topic
+ * describes has changed.
+ *
+ * The indirection exists to keep the dependency arrow pointing one way. The
+ * modules that WRITE the state (`stream-state.server.ts`, `delete.server.ts`)
+ * live below the realtime layer and must not import it — doing so would make
+ * `topics.server.ts` → `sidebar-data.server.ts` → `stream-state.server.ts` →
+ * `topics.server.ts` a cycle. They raise a signal instead, and the realtime
+ * layer subscribes at init.
+ *
+ * This module deliberately imports nothing, so it can sit under any of them.
+ */
+
+export type RealtimeSignal =
+  /** A session's stream status changed (a run opened, ended, or was aborted). */
+  | 'stream-status'
+  /** The sidebar's structure changed (a session or folder was added/removed). */
+  | 'sidebar-structure'
+  /** An omp child for `sessionId` became reachable, or was torn down. */
+  | 'session-attached'
+  /** A scheduled task was created, edited, paused, deleted or fired. */
+  | 'schedule-changed'
+  /** A panel plugin was installed, removed or edited. */
+  | 'panels-changed'
+  /** The model catalog changed (a provider or model was written). */
+  | 'models-changed'
+  /**
+   * A run's work may have changed files on disk or advanced its usage.
+   *
+   * Raised at a turn boundary rather than per tool: a run routinely edits
+   * several files, and republishing a workspace listing per tool would re-run
+   * `git status` and a directory read for every one of them.
+   */
+  | 'workspace-dirty'
+  /**
+   * A background nested-repo walk finished for one workspace root.
+   *
+   * The walk is started by a read (the `repos:` topic's own resolver), so
+   * nothing writes it — the completion is the only moment the list becomes
+   * final, and without this signal the client would have to poll for it.
+   */
+  | 'repos-scanned'
+  /**
+   * One session's DATA changed: its todo snapshot, plan artifacts, context
+   * telemetry or follow-up queue.
+   *
+   * Raised at a turn boundary (a `todo` call commits inside the run, so the
+   * transcript only tells the truth once the turn settles) and by every queue
+   * write. Without it the four `session:<id>:<suffix>` topics were served as a
+   * snapshot and then never moved — the panels rendered whatever existed when
+   * they subscribed and only a reload showed the new state.
+   */
+  | 'session-data-dirty';
+
+export interface RealtimeSignalEvent {
+  signal: RealtimeSignal;
+  /** The session a per-session signal is about. Absent for global signals. */
+  sessionId?: string;
+  /** The workspace root a root-scoped signal is about (`repos-scanned`). */
+  root?: string;
+}
+
+type SignalListener = (event: RealtimeSignalEvent) => void;
+
+const listeners = new Set<SignalListener>();
+
+/** Subscribe to every signal. Returns an unsubscribe. */
+export function onRealtimeSignal(listener: SignalListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * Raise a signal. A throwing listener never stops the others: this sits on
+ * write paths (a status flip inside a frame handler), so it must not be able
+ * to break the write it is reporting on.
+ */
+export function emitRealtimeSignal(signal: RealtimeSignal, sessionId?: string, root?: string): void {
+  const event: RealtimeSignalEvent =
+    sessionId === undefined && root === undefined
+      ? { signal }
+      : { signal, ...(sessionId !== undefined ? { sessionId } : {}), ...(root !== undefined ? { root } : {}) };
+  for (const listener of [...listeners]) {
+    try {
+      listener(event);
+    } catch {
+      // Deliberately swallowed: see the module doc.
+    }
+  }
+}
+
+/** Test seam. */
+export function clearRealtimeSignalListeners(): void {
+  listeners.clear();
+}

package/src/server/lib/realtime/topics/btw.server.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `btw:<id>` topic: one session's side-question frames.
+ *
+ * Bound to the BTW registry while anyone is watching, so the panel follows a
+ * side turn without a socket of its own. The snapshot is the same `btw_state`
+ * the panel used to receive as its stream's first frame.
+ */
+
+import { btwTopic } from '@/shared/lib/realtime/protocol';
+import { getRealtimeHub, type TopicDescriptor } from '@/server/lib/realtime/hub.server';
+import { btwStateFor, subscribeBtw } from '@/server/lib/btw/registry.server';
+
+export function btwDescriptor(sessionId: string): TopicDescriptor {
+  return {
+    resolve: () => btwStateFor(sessionId),
+    attach: () => subscribeBtw(sessionId, (frame) => {
+      getRealtimeHub().publish(btwTopic(sessionId), frame);
+    }),
+  };
+}

package/src/server/lib/realtime/topics/catalog.server.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which topics this hub serves, and how each resolves.
+ *
+ * Split from `topics.server.ts` because that module is the LIFECYCLE (register
+ * once, subscribe to signals, coalesce a burst of republishes) while this one
+ * is the CATALOG — a table of families and the lookup that reads it. Adding a
+ * topic is a row here; nothing in the lifecycle changes.
+ *
+ * Every resolver is read-only by contract: subscribing must never spawn an omp
+ * child for a session nobody is driving.
+ */
+
+import {
+  TOPIC_MODELS,
+  TOPIC_PANELS,
+  TOPIC_SCHEDULE,
+  TOPIC_SIDEBAR,
+  TOPIC_SIDEBAR_STATUS,
+  TOPIC_USAGE,
+  sessionPlanTopic,
+  sessionQueueTopic,
+  sessionTelemetryTopic,
+  sessionTodosTopic,
+} from '@/shared/lib/realtime/protocol';
+import type { SidebarPayload, SidebarStatusPayload } from '@/shared/types/realtime';
+import { isValidPluginId } from '@/shared/lib/plugins/protocol';
+import type { TopicDescriptor } from '@/server/lib/realtime/hub.types';
+import { loadSidebarStatus, loadSidebarStructure } from '@/server/lib/omp/session/sidebar-data.server';
+import { sessionDescriptor } from '@/server/lib/realtime/topics/session.server';
+import { btwDescriptor } from '@/server/lib/realtime/topics/btw.server';
+import { SESSION_DATA_TOPICS } from '@/server/lib/realtime/topics/session-data.server';
+import { globalDescriptor } from '@/server/lib/realtime/topics/global.server';
+import { workspaceDescriptor } from '@/server/lib/realtime/topics/workspace.server';
+import { pluginDescriptor } from '@/server/lib/realtime/topics/plugin.server';
+
+/**
+ * The scoped families, keyed by their topic PREFIX (without the separator).
+ *
+ * A table rather than a chain of `startsWith` calls: each family's descriptor
+ * lives in its own file, and adding one is a row here rather than another
+ * branch. A family whose descriptor is missing means the prefix is not served.
+ */
+export const SCOPED_FAMILIES: Record<string, (scope: string) => TopicDescriptor> = {
+  session: sessionDescriptor,
+  btw: btwDescriptor,
+  git: workspaceDescriptor('git'),
+  fs: workspaceDescriptor('fs'),
+  repos: workspaceDescriptor('repos'),
+  wiki: workspaceDescriptor('wiki'),
+  // A plugin's own topic. The resolver reads the value the plugin PUBLISHED
+  // rather than asking the plugin for it: a resolver that called into plugin
+  // code would run it on every subscribe, including for a plugin that is
+  // switched off but still named by a stale stored layout.
+  plugin: pluginDescriptor,
+};
+
+/** The exact-name topics, plus the per-session DATA families keyed by suffix. */
+export const EXACT_TOPICS = new Map<string, TopicDescriptor>([
+  [TOPIC_SIDEBAR, { resolve: async (): Promise<SidebarPayload> => loadSidebarStructure() }],
+  [TOPIC_SIDEBAR_STATUS, { resolve: async (): Promise<SidebarStatusPayload> => loadSidebarStatus() }],
+  [TOPIC_SCHEDULE, { resolve: () => globalDescriptor(TOPIC_SCHEDULE).resolve(TOPIC_SCHEDULE) }],
+  [TOPIC_USAGE, { resolve: () => globalDescriptor(TOPIC_USAGE).resolve(TOPIC_USAGE) }],
+  [TOPIC_PANELS, { resolve: () => globalDescriptor(TOPIC_PANELS).resolve(TOPIC_PANELS) }],
+  [TOPIC_MODELS, { resolve: () => globalDescriptor(TOPIC_MODELS).resolve(TOPIC_MODELS) }],
+]);
+
+/** Suffixes a `session:<id>:<suffix>` topic may carry. */
+export const SESSION_DATA_SUFFIXES = new Map<string, (sessionId: string) => TopicDescriptor>([
+  ['todos', (id) => SESSION_DATA_TOPICS[sessionTodosTopic('')](id)],
+  ['plan', (id) => SESSION_DATA_TOPICS[sessionPlanTopic('')](id)],
+  ['telemetry', (id) => SESSION_DATA_TOPICS[sessionTelemetryTopic('')](id)],
+  ['queue', (id) => SESSION_DATA_TOPICS[sessionQueueTopic('')](id)],
+]);
+
+/**
+ * Whether `topic` is one this hub serves.
+ *
+ * Prefixes are structural: a scoped topic must be asked about for a scope whose
+ * snapshot a resolver can produce, and an unknown prefix is refused so a typo
+ * reports itself rather than subscribing to nothing.
+ */
+export function isKnownTopicName(topic: string): boolean {
+  if (EXACT_TOPICS.has(topic)) return true;
+  const separator = topic.indexOf(':');
+  if (separator === -1) return false;
+  const family = topic.slice(0, separator);
+  const scope = topic.slice(separator + 1);
+  if (!scope) return false;
+  if (family === 'session') {
+    // A session topic is either the session itself or one of its data families.
+    const nested = scope.indexOf(':');
+    return nested === -1 || SESSION_DATA_SUFFIXES.has(scope.slice(nested + 1));
+  }
+  // A plugin topic's scope is a plugin ID, and it is validated rather than
+  // accepted on the prefix alone: any string after `plugin:` would otherwise be
+  // a servable topic, so a typo (or a hand-typed frame) would subscribe to
+  // something that can never publish instead of being refused.
+  if (family === 'plugin') return isValidPluginId(scope);
+  return family in SCOPED_FAMILIES;
+}
+
+/** The descriptor for `topic`, building a scoped one on first use. */
+export function descriptorFor(topic: string): TopicDescriptor | undefined {
+  const exact = EXACT_TOPICS.get(topic);
+  if (exact) return exact;
+  const separator = topic.indexOf(':');
+  if (separator === -1) return undefined;
+  const family = topic.slice(0, separator);
+  const scope = topic.slice(separator + 1);
+  if (!scope) return undefined;
+
+  if (family === 'session') {
+    const nested = scope.indexOf(':');
+    if (nested === -1) return sessionDescriptor(scope);
+    const build = SESSION_DATA_SUFFIXES.get(scope.slice(nested + 1));
+    return build ? build(scope.slice(0, nested)) : undefined;
+  }
+
+  const build = SCOPED_FAMILIES[family];
+  return build ? build(scope) : undefined;
+}