@ignex/nova 0.1.3 → 0.1.5

package/src/events/trace.ts

@@ -0,0 +1,283 @@
+/**
+ * Event trace — a fixed-capacity, structure-of-arrays ring that records every
+ * fired nova event (emitted, published, received) so a debugger can answer
+ * "what fired, when, where did it go, how big" without touching the hot path.
+ *
+ * Design goals (GC pressure ≈ zero):
+ *   - ALL scalars live in pre-allocated TypedArrays sized once at creation
+ *     (instantiation-time allocation, never per event).
+ *   - Strings (event name / target key / captured payload) are stored as
+ *     REFERENCES into pre-allocated slot arrays — writing a record moves no
+ *     memory and allocates nothing; old strings are reclaimed naturally when
+ *     the ring wraps over their slots.
+ *   - Row objects are materialized ONLY on read (`recent` / `stats`) — the
+ *     debugger's poll pays the allocation, the event loop never does.
+ *
+ * Recording is bounded work: a monotonic seq, six typed-array stores and a
+ * couple of reference stores (~tens of ns) — safe to leave ON in development
+ * and production alike (`IGNEX_NOVA_TRACE=0` disables it globally).
+ */
+import type { EmitTargetKind } from "./types";
+
+/** Where a traced event came from / went. Encoded as one byte per record. */
+export type TraceDirection =
+  | "out.publish" // server API publish* (fan-out to local sockets)
+  | "out.emit" // events-layer emit (targeted fan-out)
+  | "in.client" // decoded from a local socket frame
+  | "in.remote" // cluster sync frame from another instance
+  | "in.bridge"; // NATS bridge inbound
+
+/** Numeric encoding (TypedArray storage) for {@link TraceDirection}. */
+const DIRS = ["out.publish", "out.emit", "in.client", "in.remote", "in.bridge"] as const;
+
+const DIR_CODES: Record<TraceDirection, number> = {
+  "out.publish": 0,
+  "out.emit": 1,
+  "in.client": 2,
+  "in.remote": 3,
+  "in.bridge": 4,
+};
+
+/** Numeric encoding for {@link EmitTargetKind} (+ none for inbound rows). */
+const TARGET_CODES: Record<string, number> = {
+  broadcast: 0,
+  topic: 1,
+  group: 2,
+  user: 3,
+  client: 4,
+};
+const TARGET_NAMES = ["broadcast", "topic", "group", "user", "client"] as const;
+
+/** Options — all resolved at creation (instantiation time). */
+export interface EventTraceOptions {
+  /** Ring capacity in records. Default 1024 (≈ a few hundred KB total). */
+  capacity?: number;
+  /** Master switch. Default true unless `IGNEX_NOVA_TRACE=0`. */
+  enabled?: boolean;
+  /**
+   * Capture a truncated JSON preview of the payload per record. Default 0
+   * (off) — capture costs a stringify per recorded event.
+   */
+  capturePayloadChars?: number;
+}
+
+/** One materialized trace row (allocated on read, never on write). */
+export interface EventTraceRow {
+  /** monotonic sequence (ring-global ordering) */
+  seq: number;
+  /** epoch ms when the event was recorded */
+  ts: number;
+  direction: TraceDirection;
+  /** wire event name ("quote.tick", "subscribe", …) */
+  name: string;
+  /** emit target kind (absent for plain inbound rows) */
+  target?: EmitTargetKind;
+  /** topic / group / userId / clientId the event was addressed to */
+  key?: string;
+  /** encoded frame size in bytes (0 for rows without a frame) */
+  bytes: number;
+  /** truncated JSON payload preview (only when capture is enabled) */
+  payload?: string;
+}
+
+/** Aggregate counters over the records currently retained by the ring. */
+export interface EventTraceStats {
+  enabled: boolean;
+  capacity: number;
+  /** records retained (≤ capacity; full once the ring has wrapped) */
+  size: number;
+  /** total records written since creation (incl. overwritten ones) */
+  total: number;
+  inCount: number;
+  outCount: number;
+  bytes: number;
+  /** per-event counts over the retained window (name → n) */
+  byName: Record<string, number>;
+  /** last recorded event (name + ts) for at-a-glance panels */
+  last: { name: string; ts: number } | null;
+}
+
+/** Filter + limit options shared by `recent()` and server-level getters. */
+export interface TraceQueryOptions {
+  /** max rows (default 100, capped by capacity) */
+  limit?: number;
+  /** keep only this direction */
+  direction?: TraceDirection;
+  /** keep only this wire event name */
+  name?: string;
+}
+
+/** The trace surface owned by a server's state (created once per server). */
+export interface EventTrace {
+  readonly enabled: boolean;
+  readonly capacity: number;
+  /** true when payload previews are being captured (call sites stringify then) */
+  readonly captures: boolean;
+  /**
+   * Record one event. Allocation-free: scalars go into TypedArrays, strings
+   * are held by reference in reused slots. `payloadText` (pre-truncated JSON)
+   * is stored only when capture is enabled.
+   */
+  record(
+    direction: TraceDirection,
+    name: string,
+    target: EmitTargetKind | undefined,
+    key: string | undefined,
+    bytes: number,
+    payloadText?: string,
+  ): void;
+  /** Materialize up to `limit` rows, newest first, optionally filtered. */
+  recent(options?: TraceQueryOptions): EventTraceRow[];
+  /** Aggregate over the retained window (computed on read). */
+  stats(): EventTraceStats;
+  /** Drop every retained record (counters survive). */
+  clear(): void;
+}
+
+/** True unless explicitly disabled (`IGNEX_NOVA_TRACE=0`). */
+export const traceEnabledDefault = (): boolean => process.env.IGNEX_NOVA_TRACE !== "0";
+
+/** Truncate-and-stringify used by call sites when capture is enabled. */
+export const capturePayload = (payload: unknown, maxChars: number): string => {
+  try {
+    const text = JSON.stringify(payload) ?? String(payload);
+    return text.length > maxChars ? text.slice(0, maxChars) : text;
+  } catch {
+    return "[unserializable]";
+  }
+};
+
+export function createEventTrace(options: EventTraceOptions = {}): EventTrace {
+  const enabled = options.enabled ?? traceEnabledDefault();
+  const capacity = Math.max(1, options.capacity ?? 1024);
+  const captureChars = Math.max(0, options.capturePayloadChars ?? 0);
+
+  // ── pre-allocated storage (the only allocation this module ever makes) ──
+  const seqArr = new Float64Array(capacity); // seq can exceed 2^31 safely
+  const tsArr = new Float64Array(capacity);
+  const dirArr = new Uint8Array(capacity);
+  const targetArr = new Uint8Array(capacity); // 255 = none
+  const bytesArr = new Int32Array(capacity);
+  const nameSlots: Array<string | undefined> = Array.from({ length: capacity });
+  const keySlots: Array<string | undefined> = Array.from({ length: capacity });
+  const payloadSlots: Array<string | undefined> =
+    captureChars > 0 ? Array.from({ length: capacity }) : [];
+
+  let head = 0; // next slot to overwrite
+  let size = 0; // records retained (≤ capacity)
+  let totalWritten = 0;
+  let totalBytes = 0;
+  let lastSeq = 0;
+
+  return {
+    enabled,
+    capacity,
+    captures: captureChars > 0,
+
+    record(direction, name, target, key, bytes, payloadText) {
+      if (!enabled) return;
+      const i = head;
+      seqArr[i] = ++lastSeq;
+      tsArr[i] = Date.now();
+      dirArr[i] = DIR_CODES[direction];
+      targetArr[i] = target === undefined ? 255 : (TARGET_CODES[target] ?? 255);
+      bytesArr[i] = bytes;
+      nameSlots[i] = name;
+      keySlots[i] = key;
+      if (captureChars > 0 && payloadText !== undefined) payloadSlots[i] = payloadText;
+      head = i + 1 === capacity ? 0 : i + 1;
+      if (size < capacity) size++;
+      totalWritten++;
+      totalBytes += bytes;
+    },
+
+    recent(options = {}) {
+      if (!enabled || size === 0) return [];
+      const limit = Math.max(0, Math.min(options.limit ?? 100, size));
+      const dirFilter = options.direction !== undefined ? DIR_CODES[options.direction] : -1;
+      const nameFilter = options.name;
+      const out: EventTraceRow[] = [];
+      // walk backwards from the newest slot (head - 1), wrapping as needed
+      let i = head === 0 ? capacity - 1 : head - 1;
+      for (let seen = 0; seen < size && out.length < limit; seen++) {
+        const dir = dirArr[i] ?? 255;
+        const name = nameSlots[i];
+        if (
+          (dirFilter < 0 || dir === dirFilter) &&
+          (nameFilter === undefined || name === nameFilter)
+        ) {
+          const targetCode = targetArr[i] ?? 255;
+          const row: EventTraceRow = {
+            seq: seqArr[i] ?? 0,
+            ts: tsArr[i] ?? 0,
+            direction: DIRS[dir] ?? "out.publish",
+            name: name ?? "?",
+            bytes: bytesArr[i] ?? 0,
+          };
+          if (targetCode !== 255) {
+            const t = TARGET_NAMES[targetCode];
+            if (t !== undefined) row.target = t;
+          }
+          const key = keySlots[i];
+          if (key !== undefined) row.key = key;
+          if (captureChars > 0) {
+            const p = payloadSlots[i];
+            if (p !== undefined) row.payload = p;
+          }
+          out.push(row);
+        }
+        i = i === 0 ? capacity - 1 : i - 1;
+      }
+      return out;
+    },
+
+    stats() {
+      const byName: Record<string, number> = {};
+      let inCount = 0;
+      let outCount = 0;
+      let windowBytes = 0;
+      let lastName: string | undefined;
+      let lastTs = 0;
+      let newestSeq = -1;
+      if (enabled) {
+        let i = head === 0 ? capacity - 1 : head - 1;
+        for (let seen = 0; seen < size; seen++) {
+          const name = nameSlots[i];
+          const seq = seqArr[i] ?? 0;
+          if (name !== undefined) {
+            byName[name] = (byName[name] ?? 0) + 1;
+            if (seq > newestSeq) {
+              newestSeq = seq;
+              lastName = name;
+              lastTs = tsArr[i] ?? 0;
+            }
+          }
+          const dir = dirArr[i] ?? 255;
+          if (dir <= 1) outCount++;
+          else inCount++;
+          windowBytes += bytesArr[i] ?? 0;
+          i = i === 0 ? capacity - 1 : i - 1;
+        }
+      }
+      return {
+        enabled,
+        capacity,
+        size: enabled ? size : 0,
+        total: totalWritten,
+        inCount,
+        outCount,
+        bytes: windowBytes,
+        byName,
+        ...(lastName !== undefined ? { last: { name: lastName, ts: lastTs } } : { last: null }),
+      };
+    },
+
+    clear() {
+      head = 0;
+      size = 0;
+      nameSlots.fill(undefined);
+      keySlots.fill(undefined);
+      if (captureChars > 0) payloadSlots.fill(undefined);
+    },
+  };
+}

package/src/events/types/client.ts

@@ -0,0 +1,68 @@
+/**
+ * Client record types — the server-side representation of a connected peer.
+ *
+ * Type-only module (part of the `src/events/types` barrel). The runtime lives
+ * in `src/events/clients.ts` / `src/events/data.ts`.
+ */
+import type { ServerWebSocket } from "bun";
+import type { WsData } from "../../core/state";
+
+/** Per-connection state store attached to an active client record. */
+export interface ClientData {
+  /** Read a value previously `set` on this connection. */
+  get(key: string): unknown;
+  /** Store a value on this connection (arbitrary app state, per socket). */
+  set(key: string, value: unknown): void;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  keys(): string[];
+  entries(): Array<[string, unknown]>;
+  toJSON(): Record<string, unknown>;
+}
+
+/**
+ * An active user connection — the server-side representation of "who is
+ * connected, on whose behalf, and what to remember about them".
+ *
+ * - `id` is the connection id (the socket identity, unique per connection).
+ * - `userId` is the identity this connection acts ON BEHALF OF (set via the
+ *   `authenticate` hook, `hub.setUserId`, or later); several connections may
+ *   share a `userId` (multi-tab / multi-device), and `hub.clientsByUser`
+ *   groups them.
+ * - `data` is the per-connection app store, cleared automatically on close.
+ * - `groups` / `topics` are shared with the transport (`ws.data`), so control
+ *   frames (`joinGroup` / `subscribe`) stay consistent with the events layer.
+ */
+export interface EventClient {
+  /** stable connection id (ws identity, unique per socket) */
+  readonly id: string;
+  /** identity this connection acts on behalf of (undefined = anonymous) */
+  readonly userId: string | undefined;
+  /** arbitrary app metadata from `authenticate` (undefined if none) */
+  readonly meta: Record<string, unknown> | undefined;
+  /** per-connection app state store (auto-cleared on disconnect) */
+  readonly data: ClientData;
+  /** server-side client groups this connection belongs to */
+  readonly groups: ReadonlySet<string>;
+  /** topics/rooms this connection has joined */
+  readonly topics: ReadonlySet<string>;
+  /** epoch ms the socket connected */
+  readonly connectedAt: number;
+  /** remote IP (from the socket) */
+  readonly ip: string;
+  /** true after the socket closed (record is then detached) */
+  readonly closed: boolean;
+  /** the underlying socket (advanced / low-level use) */
+  readonly ws: ServerWebSocket<WsData>;
+}
+
+/** A connection known to exist on ANOTHER instance (via cluster presence). */
+export interface RemoteClient {
+  clientId: string;
+  /** the instance that reported this connection */
+  instanceId: string;
+  userId?: string;
+  /** epoch ms the connection was (re)confirmed by its instance */
+  lastSeen: number;
+}

package/src/events/types/cluster.ts

@@ -0,0 +1,40 @@
+/**
+ * Cluster sync port types — the broker transport and shared-state store
+ * contracts used by `src/events/cluster/`.
+ *
+ * Type-only module (part of the `src/events/types` barrel).
+ */
+
+/**
+ * Cross-instance messaging transport (server ⇄ server). NATS and Redis
+ * adapters are provided; any broker that supports named channels + byte
+ * payloads can be plugged in (tests use an in-memory bus). All calls are
+ * fire-and-forget and are invoked from the offload queue, never from the WS
+ * hot path.
+ */
+export interface ClusterTransport {
+  readonly connected: boolean;
+  /** synchronously hand bytes to the broker (throws → caller counts an error) */
+  publish(subject: string, data: Uint8Array): void;
+  /** subscribe; `cb` receives raw message bytes; returns an unsubscribe fn */
+  subscribe(subject: string, cb: (data: Uint8Array) => void): () => void;
+  close(): Promise<void>;
+}
+
+/**
+ * Optional shared-state store (presence / cluster group membership / client
+ * data). A memory implementation is used by default (per-instance); Redis is
+ * the production choice for horizontally scaled deployments (`createRedisStateStore`).
+ */
+export interface ClusterStateStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlMs?: number): Promise<void>;
+  del(key: string): Promise<void>;
+  sadd(key: string, member: string): Promise<void>;
+  srem(key: string, member: string): Promise<void>;
+  smembers(key: string): Promise<string[]>;
+  expire(key: string, ttlMs: number): Promise<void>;
+}
+
+/** Redis connection options — a URL string or an ioredis options object. */
+export type RedisConnectionOptions = string | Record<string, unknown>;

package/src/events/types/context.ts

@@ -0,0 +1,50 @@
+/**
+ * Event context + handler types — what every hub handler receives.
+ *
+ * Type-only module (part of the `src/events/types` barrel). Contexts are
+ * built (and cached) by `src/events/hub/context-factory.ts`.
+ */
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../../bindings/types";
+import type { IgnServer } from "../../core/server";
+import type { EmitTarget } from "./emit-target";
+import type { EventClient } from "./client";
+import type { EventsHub } from "./hub";
+
+/** Where an event reached the hub from. */
+export type EventSource = "client" | "remote" | "bridge";
+
+/**
+ * The context every handler receives — the "who / where / how do I reply"
+ * bundle. For client-sent events `client` is the sender's record; for
+ * server-side events (`onServerEvent`) there is no sender client.
+ */
+export interface EventContext<B extends Bindings = DefaultBindings> {
+  /** where the event came from: a local client, another instance, or the bridge */
+  readonly source: EventSource;
+  /** the client that sent the event (undefined for remote/bridge events) */
+  readonly client?: EventClient;
+  /** cross-instance trace id (remote/bridge events; undefined when absent) */
+  readonly traceId?: string;
+  /** the events hub (for `hub.emit`, groups, client data, …) */
+  readonly hub: EventsHub<B>;
+  /** the underlying server (raw `publish`/`publishToClient`/… escape hatch) */
+  readonly server: IgnServer<B>;
+  /** emit helpers bound to this hub (reply without importing the singleton) */
+  emit<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K], target?: EmitTarget): void;
+  emitToGroup<K extends EventNameOf<B>>(group: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToUser<K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToClient<K extends EventNameOf<B>>(clientId: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToTopic<K extends EventNameOf<B>>(topic: string, name: K, payload: EventsOf<B>[K]): void;
+}
+
+/** A handler registered on the hub (client-sent events). May be async. */
+export type EventHandler<B extends Bindings, K extends EventNameOf<B>> = (
+  payload: EventsOf<B>[K],
+  ctx: EventContext<B>,
+) => void | Promise<void>;
+
+/** A handler for server-side events (remote instances / bridge inbound). */
+export type ServerEventHandler<B extends Bindings, K extends EventNameOf<B>> = (
+  payload: EventsOf<B>[K],
+  ctx: EventContext<B>,
+) => void | Promise<void>;

package/src/events/types/emit-target.ts

@@ -0,0 +1,29 @@
+/**
+ * Emit target — the discriminated union that addresses an emit.
+ *
+ * Type-only module (part of the `src/events/types` barrel). The delivery
+ * runtime lives in `src/events/emit.ts`.
+ */
+
+/**
+ * Where an emit goes. The discriminated union is how the API "easily
+ * differentiates" between the addressing modes:
+ *
+ *   - `{ type: "broadcast" }` — every connected client, on every instance.
+ *   - `{ type: "topic", topic }` — subscribers of a topic (rooms + replay).
+ *   - `{ type: "group", group }` — members of a server-side group.
+ *   - `{ type: "user", userId }` — every socket acting on behalf of `userId`.
+ *   - `{ type: "client", clientId }` — one specific connection.
+ *
+ * Local delivery is synchronous and allocation-free (the transport scratch +
+ * `ws.send` copy); the cross-instance fan-out (when a cluster is configured)
+ * is deferred to the offload queue so the emit call never blocks.
+ */
+export type EmitTarget =
+  | { type: "broadcast" }
+  | { type: "topic"; topic: string }
+  | { type: "group"; group: string }
+  | { type: "user"; userId: string }
+  | { type: "client"; clientId: string };
+
+export type EmitTargetKind = EmitTarget["type"];

package/src/events/types/groups.ts

@@ -0,0 +1,35 @@
+/**
+ * Group handle types — client groups (by connection id) and user groups
+ * (by userId).
+ *
+ * Type-only module (part of the `src/events/types` barrel). The runtime lives
+ * in `src/events/groups.ts`.
+ */
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../../bindings/types";
+
+/** A named client group: membership by connection id, fan-out via the hub. */
+export interface ClientGroup<B extends Bindings = DefaultBindings> {
+  readonly name: string;
+  /** add a connection (by id) to the group (idempotent) */
+  add(clientId: string): void;
+  remove(clientId: string): void;
+  has(clientId: string): boolean;
+  /** member connection ids */
+  members(): string[];
+  readonly size: number;
+  /** emit an event to every member of this group (cluster-aware) */
+  emit<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
+}
+
+/** A named USER group: membership by `userId`, fan-out to every socket of each member user. */
+export interface UserGroup<B extends Bindings = DefaultBindings> {
+  readonly name: string;
+  add(userId: string): void;
+  remove(userId: string): void;
+  has(userId: string): boolean;
+  /** member user ids */
+  members(): string[];
+  readonly size: number;
+  /** emit an event to every socket acting on behalf of each member user */
+  emit<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
+}

package/src/events/types/hub.ts

@@ -0,0 +1,124 @@
+/**
+ * The events hub — the public API surface type.
+ *
+ * Type-only module (part of the `src/events/types` barrel). The runtime
+ * composition root is `src/events/hub/index.ts` (`createEventsHub`).
+ */
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../../bindings/types";
+import type { IgnServer } from "../../core/server";
+import type { EventContext, EventHandler, ServerEventHandler } from "./context";
+import type { ClientGroup, UserGroup } from "./groups";
+import type { EmitTarget } from "./emit-target";
+import type { EventClient, RemoteClient } from "./client";
+import type { EventsMetricsSnapshot } from "./metrics";
+
+/**
+ * The events hub — the public API returned as `server.events` when
+ * `createServer({ events: {...} })` is used, and the backing store for the
+ * module-global `emit` / `on` singleton (`ignex-nova/events`).
+ */
+export interface EventsHub<B extends Bindings = DefaultBindings> {
+  readonly server: IgnServer<B>;
+  /** stable id of THIS instance (self-delivery dedupe in a cluster) */
+  readonly instanceId: string;
+
+  // ── receiving events (the "events file": where events come in) ────────
+  on<K extends EventNameOf<B>>(name: K, handler: EventHandler<B, K>): EventsHub<B>;
+  off<K extends EventNameOf<B>>(name: K, handler?: EventHandler<B, K>): EventsHub<B>;
+  once<K extends EventNameOf<B>>(name: K, handler: EventHandler<B, K>): EventsHub<B>;
+  /** every client-sent inbound event (name + payload + ctx) */
+  onAny(cb: (name: EventNameOf<B>, payload: unknown, ctx: EventContext<B>) => void): EventsHub<B>;
+  offAny(cb: (name: EventNameOf<B>, payload: unknown, ctx: EventContext<B>) => void): EventsHub<B>;
+  /** server-side handlers for events from OTHER instances / the bridge */
+  onServerEvent<K extends EventNameOf<B>>(name: K, handler: ServerEventHandler<B, K>): EventsHub<B>;
+  offServerEvent<K extends EventNameOf<B>>(
+    name: K,
+    handler?: ServerEventHandler<B, K>,
+  ): EventsHub<B>;
+  /** event names with at least one handler */
+  events(): EventNameOf<B>[];
+  listenerCount(name: EventNameOf<B>): number;
+  removeAllListeners(name?: EventNameOf<B>): EventsHub<B>;
+
+  // ── emitting events (through websockets, cluster-aware) ───────────────
+  emit<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K], target?: EmitTarget): void;
+  emitToTopic<K extends EventNameOf<B>>(topic: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToGroup<K extends EventNameOf<B>>(group: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToUser<K extends EventNameOf<B>>(userId: string, name: K, payload: EventsOf<B>[K]): void;
+  emitToClient<K extends EventNameOf<B>>(clientId: string, name: K, payload: EventsOf<B>[K]): void;
+
+  // ── client records ("who is connected, on whose behalf") ──────────────
+  client(id: string): EventClient | undefined;
+  clients(): EventClient[];
+  /** every connection acting on behalf of `userId` */
+  clientsByUser(userId: string): EventClient[];
+  readonly clientCount: number;
+  /** bind a connection to an identity (on whose behalf it acts) */
+  setUserId(clientId: string, userId: string): void;
+  /** per-connection app state */
+  setClientData(clientId: string, key: string, value: unknown): void;
+  getClientData(clientId: string, key: string): unknown;
+  clearClientData(clientId: string): void;
+
+  // ── groups ────────────────────────────────────────────────────────────
+  /** client group handle (membership by connection id) */
+  group(name: string): ClientGroup<B>;
+  /** live client-group names */
+  groups(): string[];
+  /** user group handle (membership by userId, fan-out to every socket) */
+  userGroup(name: string): UserGroup<B>;
+  /** live user-group names */
+  userGroups(): string[];
+
+  // ── horizontal scaling ────────────────────────────────────────────────
+  /** connections known on other instances (presence; [] when unclustered) */
+  clusterClients(): RemoteClient[];
+  /** other instance ids heard from recently (presence; [] when unclustered) */
+  clusterInstances(): string[];
+  /** user→clients index from the shared state store, if configured */
+  clusterUserClients(userId: string): Promise<Array<{ instanceId: string; clientId: string }>>;
+  /** cluster-wide client-group members (shared state store), if configured */
+  clusterGroupMembers(group: string): Promise<string[]>;
+  /** cluster-wide user-group members (shared state store), if configured */
+  clusterUserGroupMembers(group: string): Promise<string[]>;
+  /** client data from the shared state store, if configured */
+  remoteClientData(clientId: string): Promise<Record<string, unknown> | undefined>;
+
+  // ── cross-instance rpc (server ⇄ server over the cluster transport) ──
+  /**
+   * Call a method on another instance (or any instance when `opts.instanceId`
+   * is omitted — first responder wins). Requires a configured cluster.
+   */
+  call(method: string, args?: unknown, opts?: { readonly instanceId?: string; readonly timeoutMs?: number }): Promise<unknown>;
+  /** register a cross-instance rpc method handler */
+  onMethod(method: string, handler: (args: unknown, fromInstanceId: string) => unknown | Promise<unknown>): EventsHub<B>;
+  /** request/response for CLIENT-sent events (WS-level, `client.request`) */
+  onRequest<K extends EventNameOf<B>>(
+    name: K,
+    responder: (payload: EventsOf<B>[K], ctx: EventContext<B>) => EventsOf<B>[K] | Promise<EventsOf<B>[K]>,
+  ): EventsHub<B>;
+
+  // ── scheduled emits (time-based events) ───────────────────────────────
+  /** emit `name` after `delayMs`; returns an id usable with {@link cancelScheduled} */
+  schedule<K extends EventNameOf<B>>(
+    name: K,
+    payload: EventsOf<B>[K],
+    target: EmitTarget | undefined,
+    delayMs: number,
+  ): string;
+  /** cancel a scheduled emit — true when it had not fired yet */
+  cancelScheduled(id: string): boolean;
+  /** emits currently scheduled */
+  readonly scheduledCount: number;
+
+  // ── lifecycle / observability ─────────────────────────────────────────
+  metrics(): EventsMetricsSnapshot;
+  queueStats(): {
+    pending: number;
+    queued: number;
+    processed: number;
+    dropped: number;
+    errors: number;
+  };
+  close(): Promise<void>;
+}

package/src/events/types/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Events layer types — barrel. One folder per concern:
+ *
+ *   client       — EventClient / ClientData / RemoteClient records
+ *   emit-target  — EmitTarget addressing union
+ *   context      — EventContext + handler signatures
+ *   groups       — ClientGroup / UserGroup handles
+ *   cluster      — ClusterTransport / ClusterStateStore ports
+ *   metrics      — EventsMetricsSnapshot
+ *   hub          — the public EventsHub API
+ *   options      — EventsOptions / EventsClusterOptions inputs
+ */
+
+export type { ClientData, EventClient, RemoteClient } from "./client";
+export type { EmitTarget, EmitTargetKind } from "./emit-target";
+export type {
+  EventContext,
+  EventSource,
+  EventHandler,
+  ServerEventHandler,
+} from "./context";
+export type { ClientGroup, UserGroup } from "./groups";
+export type {
+  ClusterStateStore,
+  ClusterTransport,
+  RedisConnectionOptions,
+} from "./cluster";
+export type { EventsMetricsSnapshot } from "./metrics";
+export type { EventsHub } from "./hub";
+export type { EventsClusterOptions, EventsOptions } from "./options";