@ignex/nova 0.1.3 → 0.1.6

package/src/core/server/socket-lifecycle.ts

@@ -0,0 +1,57 @@
+/**
+ * Socket lifecycle — the server-side `open` / `close` WebSocket handlers as
+ * small `(state, ws)` actions (functional-composition style, like the other
+ * core action modules). The composition root (`index.ts`) wires them into
+ * `Bun.serve`'s websocket handlers.
+ */
+import type { ServerWebSocket } from "bun";
+import type { Bindings } from "../../bindings/types";
+import { joinGroup as addToGroup, leaveGroup as removeFromGroup } from "../groups";
+import { sendControl } from "../outbound";
+import { adoptGrave, burySession } from "../resume";
+import { leaveRoom } from "../rooms";
+import type { ServerState, WsData } from "../state";
+
+/** A socket opened: register, adopt resume history, seed groups, greet. */
+export function onSocketOpen(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  state.sockets.add(ws);
+  // belt-and-suspenders: an auth race could double-register an id — kick the stale session
+  const existing = state.clients.get(ws.data.id);
+  if (existing && existing !== ws) existing.close(1000, "replaced by newer session");
+  state.clients.set(ws.data.id, ws);
+  // resume: adopt a parked history for this client id (continues the
+  // previous session's delivery-seq stream) BEFORE anything is sent
+  adoptGrave(state, ws);
+  // events-layer attach (client record + presence) BEFORE group seeding
+  state.onConnect?.(ws);
+  for (const g of ws.data.groups) addToGroup(state, ws, g);
+  greetClient(state, ws);
+}
+
+/** Announce wire version + capabilities, then pin this client's identity. */
+function greetClient(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  // announce our wire version + capabilities so clients can negotiate
+  sendControl(state, ws, "hello", {
+    version: (state.bindings as Bindings).wireVersion,
+    caps: [],
+    lastSeq: 0,
+  });
+  // then assign identity so the client knows its id + server-side groups
+  sendControl(state, ws, "welcome", { clientId: ws.data.id, groups: [...ws.data.groups] });
+}
+
+/** A socket closed: detach everywhere and park the resume history. */
+export function onSocketClose(state: ServerState, ws: ServerWebSocket<WsData>): void {
+  // events-layer detach FIRST (client record still carries groups/topics)
+  state.onDisconnect?.(ws);
+  state.sockets.delete(ws);
+  state.clients.delete(ws.data.id);
+  for (const g of ws.data.groups) removeFromGroup(state, ws, g);
+  ws.data.groups.clear();
+  for (const t of ws.data.topics) leaveRoom(state, ws, t);
+  ws.data.topics.clear();
+  delete ws.data.queue;
+  // resume: park the sent-history so a reconnect with the same id can
+  // pick up where this session left off (no-op when resume is off)
+  burySession(state, ws);
+}

package/src/core/state.ts

@@ -10,9 +10,11 @@ import type { ServerWebSocket } from "bun";
 import { defaultBindings } from "../bindings/default";
 import type { Bindings, DefaultBindings, EventNameOf } from "../bindings/types";
 import type { NatsBridge, NatsBridgeOptions } from "../bridge/nats";
+import { createEventTrace, type EventTrace, type EventTraceOptions } from "../events/trace";
 import { createTransport, defaultTransport, type Transport } from "../transport/transport";
 import type { Int64GuardMode } from "./int64-guard";
 import { createMetrics, type Metrics } from "./metrics";
+import { resolveRateLimit, type RateLimitOptions, type ResolvedRateLimit } from "./rate-limit";
 import type { RingBuffer } from "./ring";
 
 /**
@@ -57,6 +59,15 @@ export interface WsData {
   connectedAt: number;
   /** drop-oldest backpressure queue (only non-empty while the socket is saturated) */
   queue?: RingBuffer<Uint8Array>;
+  /** per-connection inbound rate limiter (lazily created on first frame) */
+  rate?: import("./rate-limit").RateLimiter;
+  /**
+   * Next per-connection delivery seq to stamp (envelope v2). Starts at 1;
+   * continues a previous session's stream when a grave is adopted.
+   */
+  sendSeq: number;
+  /** bounded sent-frame history for gap recovery (lazily created, resume only) */
+  history?: import("./ring").RingBuffer<import("./resume").SentFrame>;
 }
 
 /** Slow-consumer policy (see `IgnBackpressureOptions`). */
@@ -97,9 +108,23 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
    * traffic. Off by default to keep the hot path allocation-free.
    */
   replay?: { historySize?: number };
+  /**
+   * Gap-free delivery (envelope v2 seq + resume). When set, every frame sent
+   * to a socket carries a per-connection delivery seq, the connection keeps a
+   * bounded sent-history ring, and closed sessions park that ring in a
+   * per-client-id graveyard so reconnects can resume missed frames.
+   */
+  resume?: { historySize?: number; ttlMs?: number };
+  /**
+   * Durable topic log behind the replay ring (`src/core/topic-log.ts`). When
+   * set, every recorded topic frame is appended and `snapshotRequest`s older
+   * than the ring hydrate from the log. Default: none (ring-only).
+   */
+  topicLog?: import("./topic-log").TopicLog;
   /**
    * Async auth hook run BEFORE the WebSocket upgrade. Return `false` to reject
-   * the connection (401). Return `true` to allow it (client gets an auto-
+   * the connection (401) — a hook that throws (or rejects) denies it too.
+   * Return `true` to allow it (client gets an auto-
    * generated id), or a `ClientMeta` object to pin the client id / seed its
    * server-side groups / attach metadata. Inspect `req` as needed.
    */
@@ -115,6 +140,22 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
   maxConnections?: number;
   /** maximum inbound frame size in bytes (close 1009 beyond) */
   maxMessageSize?: number;
+  /**
+   * Per-connection inbound rate limiting (token bucket over ALL frames — app
+   * AND control). Default: off (zero hot-path overhead). Over-limit frames are
+   * dropped (default) or the socket is closed (`policy: "close"`, code 1008);
+   * either way the event is counted in `metrics.rateLimited`.
+   */
+  rateLimit?: RateLimitOptions;
+  /**
+   * Authorize a client's topic (room) join — enforced for EVERY join path:
+   * `subscribe` control frames, programmatic `server.join`, and auth-seeded
+   * topics. Return false to reject (the frame/ call is ignored and counted in
+   * `metrics.rejectedJoins`). Default: allow all.
+   */
+  authorizeTopic?: (topic: string, ws: ServerWebSocket<WsData>) => boolean;
+  /** Authorize a server-side group join (same contract as `authorizeTopic`). */
+  authorizeGroup?: (group: string, ws: ServerWebSocket<WsData>) => boolean;
   /**
    * Lossless-int64 guard for plain `number` int64 fields: values outside the
    * safe-integer range (±2^53-1) throw / warn at encode time (default "off" —
@@ -141,6 +182,13 @@ export interface IgnServerOptions<B extends Bindings = DefaultBindings> {
    * (`ignex-nova/events`) is bound by default.
    */
   events?: import("../events/types").EventsOptions<B>;
+  /**
+   * Event trace ring — records every fired event (emitted / published /
+   * received) into a pre-allocated structure-of-arrays buffer so a debugger
+   * (ignex debugbar, MCP) can see what fired without any hot-path allocation.
+   * Default: on with capacity 1024; `IGNEX_NOVA_TRACE=0` disables globally.
+   */
+  trace?: EventTraceOptions;
   /** additional HTTP handler for non-ws routes (e.g. serving a static demo page) */
   fetch?: (req: Request) => Response | Promise<Response>;
 }
@@ -163,7 +211,11 @@ export interface ServerState {
   token?: string | ((token: string) => boolean);
   maxConnections?: number;
   maxMessageSize?: number;
+  rateLimit: ResolvedRateLimit | null;
+  authorizeTopic?: (topic: string, ws: ServerWebSocket<WsData>) => boolean;
+  authorizeGroup?: (group: string, ws: ServerWebSocket<WsData>) => boolean;
   replay: { historySize: number } | null;
+  resume: { historySize: number; ttlMs: number } | null;
   sockets: Set<ServerWebSocket<WsData>>;
   /** id → live socket (client registry for targeted sends / introspection) */
   clients: Map<string, ServerWebSocket<WsData>>;
@@ -175,11 +227,23 @@ export interface ServerState {
   inboundHandlers: Map<string, InboundHandler>;
   topicHistory: Map<string, RingBuffer<{ seq: number; frame: Uint8Array }>>;
   replaySeq: number;
+  /** optional durable topic log (wired in createServer when `options.topicLog` is set) */
+  topicLog?: import("./topic-log").TopicLog;
+  /**
+   * Responder registry for request/response (`rpcCall` control frames):
+   * inner event name → async responder. Registered via `server.handle` /
+   * `hub.onRequest`.
+   */
+  rpcHandlers: Map<string, (payload: unknown, ws: ServerWebSocket<WsData>) => Promise<unknown>>;
+  /** parked sent-history rings of closed sessions (cross-connection resume) */
+  graves: Map<string, { history: RingBuffer<import("./resume").SentFrame>; nextSeq: number; expiresAt: number }>;
   /** events-layer lifecycle hooks (wired by createServer when `events` is set) */
   onConnect?: (ws: ServerWebSocket<WsData>) => void;
   onDisconnect?: (ws: ServerWebSocket<WsData>) => void;
   /** fired on ANY group membership change (auth seed, control frames, programmatic) */
   onGroupChange?: (group: string, ws: ServerWebSocket<WsData>, joined: boolean) => void;
+  /** event trace ring (debugger visibility; pre-allocated, zero-GC writes) */
+  trace: EventTrace;
 }
 
 export function createServerState<B extends Bindings = DefaultBindings>(
@@ -205,7 +269,12 @@ export function createServerState<B extends Bindings = DefaultBindings>(
     ...(options.token !== undefined ? { token: options.token } : {}),
     ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
     ...(options.maxMessageSize !== undefined ? { maxMessageSize: options.maxMessageSize } : {}),
+    rateLimit: resolveRateLimit(options.rateLimit),
+    ...(options.authorizeTopic !== undefined ? { authorizeTopic: options.authorizeTopic } : {}),
+    ...(options.authorizeGroup !== undefined ? { authorizeGroup: options.authorizeGroup } : {}),
+    ...(options.topicLog !== undefined ? { topicLog: options.topicLog } : {}),
     replay: options.replay ? { historySize: options.replay.historySize ?? 64 } : null,
+    resume: options.resume ? { historySize: options.resume.historySize ?? 256, ttlMs: options.resume.ttlMs ?? 60_000 } : null,
     sockets: new Set(),
     clients: new Map(),
     rooms: new Map(),
@@ -213,5 +282,8 @@ export function createServerState<B extends Bindings = DefaultBindings>(
     inboundHandlers: new Map(),
     topicHistory: new Map(),
     replaySeq: 0,
+    rpcHandlers: new Map(),
+    graves: new Map(),
+    trace: createEventTrace(options.trace),
   };
 }

package/src/core/topic-log.ts

@@ -0,0 +1,86 @@
+/**
+ * Durable topic-log seam — the pluggable backend behind the bounded replay
+ * ring. The ring keeps the LAST N frames per topic in memory; a {@link TopicLog}
+ * receives the same frames so subscribers can resume from points the ring has
+ * already forgotten.
+ *
+ * Contract (deliberately narrow):
+ *   - `append` is SYNCHRONOUS and must never throw onto the publish hot path —
+ *     implementations buffer internally and flush on their own schedule (the
+ *     memory impl appends to an array; a file impl would hand off to a writer;
+ *     a NATS JetStream / Redis Streams impl would enqueue a publish).
+ *   - `range(topic, afterSeq, limit?)` returns frames strictly AFTER `afterSeq`
+ *     oldest → newest, synchronously. Adapters over remote stores should
+ *     maintain a local read-through cache so this stays sync-friendly.
+ *   - `latestSeq(topic)` mirrors the server's replay-seq counter for the topic
+ *     (0 = unknown/empty).
+ *
+ * Ship-with implementation: {@link createMemoryTopicLog} — per-topic bounded
+ * array (drop-oldest), process-local durability (survives ring overflow, not a
+ * restart). Production adapters (JetStream / Redis Streams / filesystem)
+ * implement the same three methods — see docs/architecture.md ("Durability").
+ */
+import { RingBuffer } from "./ring";
+
+/** One durably-retained topic frame. */
+export interface LoggedFrame {
+  /** global replay seq (the same counter stamped into the topic history) */
+  seq: number;
+  frame: Uint8Array;
+}
+
+export interface TopicLog {
+  /** Record a frame for `topic` (fire-and-forget; never throws). */
+  append(topic: string, frame: Uint8Array, seq: number): void;
+  /** Frames strictly after `afterSeq`, oldest → newest (at most `limit`). */
+  range(topic: string, afterSeq: number, limit?: number): LoggedFrame[];
+  /** Highest seq retained for `topic` (0 = none). */
+  latestSeq(topic: string): number;
+  /** Release resources (flush buffers, close files/connections). */
+  close(): void;
+}
+
+export interface MemoryTopicLogOptions {
+  /** max frames retained PER TOPIC (drop-oldest beyond), default 10_000 */
+  maxPerTopic?: number;
+}
+
+/** Process-local durable log: survives ring overflow, not a restart. */
+export function createMemoryTopicLog(
+  opts: MemoryTopicLogOptions = {},
+): TopicLog {
+  const max = Math.max(1, opts.maxPerTopic ?? 10_000);
+  const topics = new Map<string, { frames: RingBuffer<LoggedFrame>; latest: number }>();
+  const ensure = (topic: string) => {
+    let t = topics.get(topic);
+    if (!t) {
+      t = { frames: new RingBuffer<LoggedFrame>(max, true), latest: 0 };
+      topics.set(topic, t);
+    }
+    return t;
+  };
+  return {
+    append(topic, frame, seq) {
+      const t = ensure(topic);
+      t.frames.push({ seq, frame: frame.slice() });
+      if (seq > t.latest) t.latest = seq;
+    },
+    range(topic, afterSeq, limit) {
+      const t = topics.get(topic);
+      if (!t) return [];
+      const out: LoggedFrame[] = [];
+      for (const e of t.frames) {
+        if (e.seq <= afterSeq) continue;
+        out.push(e);
+        if (limit !== undefined && out.length >= limit) break;
+      }
+      return out;
+    },
+    latestSeq(topic) {
+      return topics.get(topic)?.latest ?? 0;
+    },
+    close() {
+      topics.clear();
+    },
+  };
+}

package/src/events/clients.ts

@@ -67,6 +67,11 @@ export interface ClientStore {
   get(id: string): EventClient | undefined;
   all(): EventClient[];
   byUser(userId: string): EventClient[];
+  /**
+   * Invoke `each` for every live socket of `userId`; returns the count.
+   * Allocation-free variant of {@link byUser} for emit hot paths.
+   */
+  forEachByUser(userId: string, each: (client: EventClient) => void): number;
   setUserId(clientId: string, userId: string): boolean;
   onAttach(cb: (client: EventClient) => void): void;
   onDetach(cb: (client: EventClient) => void): void;
@@ -136,6 +141,19 @@ export function createClientStore(): ClientStore {
       }
       return out;
     },
+    forEachByUser(userId, each) {
+      const ids = byUser.get(userId);
+      if (ids === undefined || ids.size === 0) return 0;
+      let n = 0;
+      for (const id of ids) {
+        const c = byId.get(id);
+        if (c !== undefined) {
+          each(c);
+          n++;
+        }
+      }
+      return n;
+    },
     setUserId(clientId, userId) {
       const client = byId.get(clientId);
       if (!client) return false;

package/src/events/cluster/dedupe.ts

@@ -0,0 +1,43 @@
+/**
+ * Broker-redelivery dedupe window — bounded recent-message-id tracking.
+ *
+ * Durable brokers may redeliver; every processed message id is recorded in a
+ * ring + set pair and duplicates are dropped. Encapsulated factory (like
+ * `createMetrics`) — the state is private, the surface is one pure predicate.
+ */
+import { RingBuffer } from "../../core/ring";
+
+export interface DedupeWindow {
+  /**
+   * Record `id` and report whether it was ALREADY seen (true → drop the
+   * message). Empty ids and a zero-size window disable tracking entirely.
+   */
+  markSeen(id: string): boolean;
+}
+
+/**
+ * @param size how many message ids to remember (0 disables; values < 16 are
+ *   clamped up so the ring has usable capacity).
+ */
+export function createDedupeWindow(size: number): DedupeWindow {
+  const window = Math.max(0, size);
+  if (window === 0) return { markSeen: () => false };
+
+  const ring = new RingBuffer<string>(Math.max(16, window), true);
+  const seen = new Set<string>();
+
+  return {
+    markSeen(id: string): boolean {
+      if (id === "") return false;
+      if (seen.has(id)) return true;
+      // evict the oldest id when the window is full (FIFO — matches redelivery)
+      if (ring.length >= window) {
+        const evict = ring.shift();
+        if (evict !== undefined) seen.delete(evict);
+      }
+      ring.push(id);
+      seen.add(id);
+      return false;
+    },
+  };
+}

package/src/events/cluster/envelope.ts

@@ -0,0 +1,149 @@
+/**
+ * Cluster envelope codec — the self-describing binary frame published to the
+ * broker. Routing never depends on broker channel syntax; everything a peer
+ * needs (origin, kind, key, event name, dedupe id, trace id) rides in the
+ * header so any transport works identically.
+ *
+ * Wire layout (v2):
+ *   [envVer:1]
+ *   [originLen:u8][origin:utf8][kind:u8][keyLen:u8][key:utf8][nameLen:u8][name:utf8]
+ *   [msgIdLen:u8][msgId:utf8][traceLen:u8][trace:utf8]
+ *   [frame:bytes]
+ *
+ * v2 adds the envelope VERSION byte, a message id (broker-level redelivery
+ * dedupe) and an optional trace id (cross-instance trace correlation). A v1
+ * peer's frames fail the version check and are counted as errors.
+ *
+ * Pure functions — no I/O, no shared state.
+ */
+import {
+  CLUSTER_ENV_VERSION,
+  CLUSTER_KINDS,
+  CLUSTER_KIND_ID,
+  type ClusterKind,
+  clusterKindFromId,
+} from "./kinds";
+
+// module-global codecs: allocation happens once per process, not per message
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** One decoded cluster message (`frame` is a view into the input buffer). */
+export interface ClusterEnvelope {
+  origin: string;
+  kind: ClusterKind;
+  key: string;
+  name: string;
+  frame: Uint8Array;
+  /** producer-assigned unique message id (dedupe across broker redeliveries) */
+  msgId: string;
+  /** optional cross-instance trace id */
+  traceId: string;
+}
+
+/** Write `[len:u8][bytes]` at `p`; returns the offset after the payload. */
+function putLenPrefixed(out: Uint8Array, p: number, bytes: Uint8Array): number {
+  out[p] = bytes.byteLength;
+  out.set(bytes, p + 1);
+  return p + 1 + bytes.byteLength;
+}
+
+/** Encode all length-prefixed header strings up-front (also validates sizes). */
+function encodeHeaderStrings(
+  origin: string,
+  key: string,
+  name: string,
+  msgId: string,
+  traceId: string,
+): [Uint8Array, Uint8Array, Uint8Array, Uint8Array, Uint8Array] {
+  const o = enc.encode(origin);
+  const k = enc.encode(key);
+  const n = enc.encode(name);
+  const m = enc.encode(msgId);
+  const t = enc.encode(traceId);
+  // length fields are single bytes — anything longer would silently wrap
+  // mod 256 and CORRUPT the frame for every peer; fail loudly instead
+  if (
+    o.byteLength > 255 ||
+    k.byteLength > 255 ||
+    n.byteLength > 255 ||
+    m.byteLength > 255 ||
+    t.byteLength > 255
+  ) {
+    throw new RangeError(
+      "ignex cluster: origin/key/name/msgId/trace exceed the 255-byte envelope limit " +
+        `(got ${o.byteLength}/${k.byteLength}/${n.byteLength}/${m.byteLength}/${t.byteLength})`,
+    );
+  }
+  return [o, k, n, m, t];
+}
+
+export function encodeClusterMessage(
+  origin: string,
+  kind: ClusterKind,
+  key: string,
+  name: string,
+  frame: Uint8Array,
+  msgId = "",
+  traceId = "",
+): Uint8Array {
+  const [o, k, n, m, t] = encodeHeaderStrings(origin, key, name, msgId, traceId);
+  // fixed bytes: envVer(1) originLen(1) kind(1) keyLen(1) nameLen(1) msgIdLen(1) traceLen(1)
+  const headerLen = 7 + o.byteLength + k.byteLength + n.byteLength + m.byteLength + t.byteLength;
+  const out = new Uint8Array(headerLen + frame.byteLength);
+  let p = 0;
+  out[p] = CLUSTER_ENV_VERSION;
+  p++;
+  p = putLenPrefixed(out, p, o);
+  out[p] = CLUSTER_KIND_ID[kind];
+  p++;
+  p = putLenPrefixed(out, p, k);
+  p = putLenPrefixed(out, p, n);
+  p = putLenPrefixed(out, p, m);
+  p = putLenPrefixed(out, p, t);
+  out.set(frame, p);
+  return out;
+}
+
+/** Read one length-prefixed string at `at`; `null` when truncated/malformed. */
+function readLenPrefixed(
+  bytes: Uint8Array,
+  at: number,
+): { str: string; next: number } | null {
+  if (at >= bytes.byteLength) return null;
+  const len = bytes[at]!;
+  if (at + 1 + len > bytes.byteLength) return null;
+  return { str: dec.decode(bytes.subarray(at + 1, at + 1 + len)), next: at + 1 + len };
+}
+
+/**
+ * Decode a cluster envelope. Returns `null` for undecodable input or a
+ * foreign/legacy envelope version (callers count those as errors).
+ */
+export function decodeClusterMessage(bytes: Uint8Array): ClusterEnvelope | null {
+  if (bytes.byteLength < 4) return null;
+  if (bytes[0] !== CLUSTER_ENV_VERSION) return null; // foreign / legacy envelope
+  const o = readLenPrefixed(bytes, 1);
+  if (!o) return null;
+  const kindId = bytes[o.next];
+  if (kindId === undefined || kindId >= CLUSTER_KINDS.length) return null;
+  const k = readLenPrefixed(bytes, o.next + 1);
+  if (!k) return null;
+  const n = readLenPrefixed(bytes, k.next);
+  if (!n) return null;
+  const m = readLenPrefixed(bytes, n.next);
+  if (!m) return null;
+  const t = readLenPrefixed(bytes, m.next);
+  if (!t) return null;
+  const kind = clusterKindFromId(kindId);
+  if (kind === undefined) return null;
+  return {
+    origin: o.str,
+    kind,
+    key: k.str,
+    name: n.str,
+    msgId: m.str,
+    traceId: t.str,
+    frame: bytes.subarray(t.next),
+  };
+}

package/src/events/cluster/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Cluster sync — barrel. Horizontal scaling for the events layer, decomposed
+ * by concern:
+ *
+ *   kinds           — routing-kind constants + wire ids
+ *   envelope        — the self-describing binary frame codec (pure)
+ *   subjects        — broker channel names derived from the prefix
+ *   presence        — presence message codec (join/leave/sync)
+ *   presence-table  — in-memory remote-presence index with TTL pruning
+ *   dedupe          — bounded broker-redelivery dedupe window
+ *   keys            — shared-state key builders
+ *   sync            — createClusterSync composition root
+ *   transport-nats / transport-redis — ClusterTransport adapters
+ *   store-memory / store-redis       — ClusterStateStore adapters
+ *
+ * All cross-instance work is deferred to the offload queue — the emit call
+ * never blocks on a broker.
+ */
+
+export { CLUSTER_ENV_VERSION, CLUSTER_KINDS, CLUSTER_KIND_ID, clusterKindFromId, type ClusterKind } from "./kinds";
+export { decodeClusterMessage, encodeClusterMessage, type ClusterEnvelope } from "./envelope";
+export { createClusterSubjects, type ClusterSubjects } from "./subjects";
+export {
+  decodePresence,
+  encodePresence,
+  type PresenceJoin,
+  type PresenceLeave,
+  type PresenceMessage,
+  type PresenceSync,
+} from "./presence";
+export { createPresenceTable, type PresenceTable } from "./presence-table";
+export { createDedupeWindow, type DedupeWindow } from "./dedupe";
+export {
+  clientDataKey,
+  clientGroupStateKey,
+  parsePresenceMember,
+  presenceInstanceKey,
+  presenceUserKey,
+  userGroupStateKey,
+} from "./keys";
+export {
+  createClusterSync,
+  type ClusterMsgMeta,
+  type ClusterSync,
+  type ClusterSyncOptions,
+} from "./sync";
+export { createNatsClusterTransport } from "./transport-nats";
+export { createRedisClusterTransport } from "./transport-redis";
+export { createMemoryStateStore } from "./store-memory";
+export { createRedisStateStore } from "./store-redis";

package/src/events/cluster/keys.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared-state key builders — the canonical key names used in the
+ * `ClusterStateStore` (Redis in production). Centralized so every instance
+ * agrees on the layout; pure string functions.
+ */
+
+/** User-group membership set (`member` = userId). */
+export const userGroupStateKey = (name: string): string => `ignex:group-users:${name}`;
+
+/** Client-group membership set (`member` = clientId). */
+export const clientGroupStateKey = (name: string): string => `ignex:group:${name}`;
+
+/** Per-user presence index (`member` = `{instanceId}:{clientId}`). */
+export const presenceUserKey = (userId: string): string => `ignex:presence:user:${userId}`;
+
+/** Per-instance presence index (`member` = clientId). */
+export const presenceInstanceKey = (instanceId: string): string =>
+  `ignex:presence:instance:${instanceId}`;
+
+/** Client data blob (JSON string). */
+export const clientDataKey = (clientId: string): string => `ignex:client-data:${clientId}`;
+
+/**
+ * Split a `{instanceId}:{clientId}` presence member back into its parts.
+ * Returns `null` for malformed members (never crashes on foreign data).
+ */
+export function parsePresenceMember(
+  member: string,
+): { instanceId: string; clientId: string } | null {
+  const idx = member.indexOf(":");
+  if (idx <= 0) return null;
+  return { instanceId: member.slice(0, idx), clientId: member.slice(idx + 1) };
+}

package/src/events/cluster/kinds.ts

@@ -0,0 +1,32 @@
+/**
+ * Cluster routing kinds — the semantic addressing modes carried in the
+ * cluster envelope. Numeric ids ride the wire; the strings are internal.
+ *
+ * Pure constants module (part of the `src/events/cluster` composition).
+ */
+
+/** Every envelope kind, in wire order (index = kind id). */
+export const CLUSTER_KINDS = ["broadcast", "topic", "group", "user", "client", "presence"] as const;
+export type ClusterKind = (typeof CLUSTER_KINDS)[number];
+
+/** Wire encoding of a {@link ClusterKind} (single byte). */
+export const CLUSTER_KIND_ID: Record<ClusterKind, number> = {
+  broadcast: 0,
+  topic: 1,
+  group: 2,
+  user: 3,
+  client: 4,
+  presence: 5,
+};
+
+/**
+ * Envelope format version. A peer on a different version fails the version
+ * check and its frames are counted as errors — mixed-version clusters during
+ * a rolling upgrade degrade visibly instead of delivering corrupt frames.
+ */
+export const CLUSTER_ENV_VERSION = 2;
+
+/** Map a numeric wire kind back to its name (`undefined` when out of range). */
+export function clusterKindFromId(id: number): ClusterKind | undefined {
+  return CLUSTER_KINDS[id];
+}