@ignex/nova 0.1.1 → 0.1.5

package/src/core/client.ts

@@ -4,43 +4,63 @@
  * ONLY place that knows how the pieces fit together; `connect` lives here
  * because it owns the socket lifecycle.
  *
+ * Generic over the wire stack: `createClient(url, { bindings })` with your own
+ * generated bindings types `on` / `send` / ... against YOUR events. The default
+ * is the built-in registry, so existing code keeps working unchanged.
+ *
  * Public entry: `public/client.ts` re-exports `createClient` + the types.
  */
-import { WIRE_VERSION } from "../generated/registry";
-import { encodeEventFrame } from "../generated/ts-ser";
-import type { Events, EventName } from "../schema";
+import type { Bindings, DefaultBindings, EventNameOf, EventsOf } from "../bindings/types";
 import { createClientState, setStatus, type ClientState, type ClientStatus, type IgnClientOptions } from "./client-state";
-import { handleMessage, sendControl, sendFrame } from "./client-wire";
+import { handleMessage, emitError, sendControl, sendFrame, flushPending } from "./client-wire";
 import { startHeartbeat, stopHeartbeat } from "./client-heartbeat";
 import { scheduleReconnect } from "./client-reconnect";
+import { failAllPending, createRpcRequest } from "./client-rpc";
+
+/** Result of a request/response round-trip. */
+export interface RpcResult<P> {
+  payload: P;
+}
 
 /** The public client API (returned by `createClient`). */
-export interface IgnClient {
-  on<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
-  off<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+export interface IgnClient<B extends Bindings = DefaultBindings> {
+  on<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
+  off<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
   /** Register a handler that fires once for the event, then removes itself. */
-  once<K extends EventName>(name: K, handler: (payload: Events[K]) => void): IgnClient;
+  once<K extends EventNameOf<B>>(name: K, handler: (payload: EventsOf<B>[K]) => void): IgnClient<B>;
   /** Register a handler for EVERY incoming app event (name + payload). */
-  onAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
-  offAny(cb: (name: EventName, payload: unknown) => void): IgnClient;
+  onAny(cb: (name: EventNameOf<B>, payload: unknown) => void): IgnClient<B>;
+  offAny(cb: (name: EventNameOf<B>, payload: unknown) => void): IgnClient<B>;
   /** Names that currently have at least one handler. */
-  events(): EventName[];
+  events(): EventNameOf<B>[];
   /** Remove all handlers (optionally just for one event). */
-  removeAllListeners(name?: EventName): IgnClient;
+  removeAllListeners(name?: EventNameOf<B>): IgnClient<B>;
   /** Register an error callback (decode failures, wire-version mismatch). */
-  onError(cb: (err: Error) => void): IgnClient;
-  offError(cb: (err: Error) => void): IgnClient;
+  onError(cb: (err: Error) => void): IgnClient<B>;
+  offError(cb: (err: Error) => void): IgnClient<B>;
   /** Watch connection lifecycle: "connecting" | "connected" | "disconnected" | "reconnecting" | "closed". */
-  onStatus(cb: (status: ClientStatus) => void): IgnClient;
-  offStatus(cb: (status: ClientStatus) => void): IgnClient;
+  onStatus(cb: (status: ClientStatus) => void): IgnClient<B>;
+  offStatus(cb: (status: ClientStatus) => void): IgnClient<B>;
   readonly currentStatus: ClientStatus;
-  connect(): IgnClient;
+  connect(): IgnClient<B>;
   close(): void;
   /** Send a typed app event to the server (server must allow it via `inbound`). */
-  send<K extends EventName>(name: K, payload: Events[K]): void;
+  send<K extends EventNameOf<B>>(name: K, payload: EventsOf<B>[K]): void;
+  /**
+   * Request/response: send `name` and await the responder's payload (encoded
+   * with the SAME event schema). Rejects on timeout (`timeoutMs`, default
+   * `requestTimeoutMs`) or when no responder is registered server-side.
+   */
+  request<K extends EventNameOf<B>>(
+    name: K,
+    payload: EventsOf<B>[K],
+    opts?: { readonly timeoutMs?: number },
+  ): Promise<RpcResult<EventsOf<B>[K]>>;
   /** Ask the server to subscribe this socket to a topic (room membership + replay). */
   subscribe(topic: string): void;
   unsubscribe(topic: string): void;
+  /** Ask the server to re-send recorded topic history strictly after `fromSeq`. */
+  snapshotRequest(topic: string, fromSeq?: number): void;
   /** Ask the server to add this socket to a server-side group. */
   joinGroup(group: string): void;
   leaveGroup(group: string): void;
@@ -50,26 +70,61 @@ export interface IgnClient {
   readonly groups: string[];
 }
 
-export function createClient(url: string, opts: IgnClientOptions = {}): IgnClient {
+export function createClient<B extends Bindings = DefaultBindings>(
+  url: string,
+  opts: IgnClientOptions<B> = {},
+): IgnClient<B> {
   const state: ClientState = createClientState(url, opts);
 
-  function connect(): IgnClient {
+  function connect(): IgnClient<B> {
+    // idempotent: an already-open / opening socket is never leaked or replaced
+    if (state.ws !== null) {
+      const ready = state.ws.readyState;
+      if (ready === WebSocket.OPEN || ready === WebSocket.CONNECTING) return api;
+    }
     state.closed = false;
     setStatus(state, state.attempts === 0 ? "connecting" : "reconnecting");
     const ws = new WebSocket(url);
     ws.binaryType = "arraybuffer";
+    // ownership guard: once a NEWER socket occupies `state.ws`, callbacks from
+    // this (stale) socket must not touch shared state or reschedule reconnects
+    const ownsState = (): boolean => state.ws === null || state.ws === ws;
     ws.onopen = () => {
+      if (!ownsState()) return;
       state.attempts = 0;
       setStatus(state, "connected");
-      sendControl(state, "hello", { version: WIRE_VERSION, caps: [], lastSeq: 0 });
+      state.resumeInFlight = false;
+      if (state.gapTimer !== null) {
+        clearTimeout(state.gapTimer);
+        state.gapTimer = null;
+      }
+      // carry the last contiguous delivery seq so a resume-capable server can
+      // re-send what this session missed (cross-session resume)
+      sendControl(state, "hello", {
+        version: state.bindings.wireVersion,
+        caps: [],
+        lastSeq: state.resume.enabled ? state.rxSeq : 0,
+      });
       // re-subscribe topics from before the disconnect (server cleared them)
       for (const t of state.subscribedTopics) sendControl(state, "subscribe", { topic: t });
       startHeartbeat(state);
     };
-    ws.onmessage = (ev) => handleMessage(state, ev.data as ArrayBuffer | string);
+    ws.onmessage = (ev) => {
+      if (!ownsState()) return;
+      handleMessage(state, ev.data as ArrayBuffer | string);
+    };
+    ws.onerror = () => {
+      // surface refused upgrades / transport failures (onclose follows and
+      // drives the reconnect state machine — no double scheduling here)
+      if (!ownsState()) return;
+      emitError(state, new Error("ignex: connection error"));
+    };
     ws.onclose = () => {
+      if (!ownsState()) return; // replaced by a newer socket — its lifecycle wins
       stopHeartbeat(state);
       state.ws = null;
+      state.resumeInFlight = false;
+      flushPending(state); // accept in-flight gap loss; hello carries rxSeq on reconnect
       if (state.closed) {
         setStatus(state, "closed");
         return;
@@ -80,38 +135,38 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
     return api;
   }
 
-  const api: IgnClient = {
+  const api: IgnClient<B> = {
     on(name, handler) {
       let set = state.handlers.get(name);
       if (!set) {
         set = new Set();
         state.handlers.set(name, set);
       }
-      set.add(handler as never);
+      set.add(handler as (payload: unknown) => void);
       return api;
     },
     off(name, handler) {
-      state.handlers.get(name)?.delete(handler as never);
+      state.handlers.get(name)?.delete(handler as (payload: unknown) => void);
       return api;
     },
     once(name, handler) {
-      const wrap = (payload: never): void => {
+      const wrap = (payload: unknown): void => {
         api.off(name, wrap as never);
-        handler(payload);
+        (handler as (payload: unknown) => void)(payload);
       };
       api.on(name, wrap as never);
       return api;
     },
     onAny(cb) {
-      state.anyHandlers.add(cb);
+      state.anyHandlers.add(cb as (name: string, payload: unknown) => void);
       return api;
     },
     offAny(cb) {
-      state.anyHandlers.delete(cb);
+      state.anyHandlers.delete(cb as (name: string, payload: unknown) => void);
       return api;
     },
     events() {
-      return [...state.handlers.keys()];
+      return [...state.handlers.keys()] as EventNameOf<B>[];
     },
     removeAllListeners(name) {
       if (name) state.handlers.delete(name);
@@ -143,12 +198,28 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
       stopHeartbeat(state);
       if (state.reconnectTimer) clearTimeout(state.reconnectTimer);
       state.reconnectTimer = null;
+      if (state.gapTimer !== null) {
+        clearTimeout(state.gapTimer);
+        state.gapTimer = null;
+      }
+      state.pending.clear();
+      state.pendingFrom = 0;
+      failAllPending(state, new Error("ignex: client closed"));
       state.ws?.close();
       state.ws = null;
       setStatus(state, "closed");
     },
     send(name, payload) {
-      sendFrame(state, encodeEventFrame(name, payload));
+      sendFrame(state, state.bindings.encodeFrame(name, payload));
+    },
+    request(name, payload, opts) {
+      return createRpcRequest(
+        state,
+        name,
+        payload,
+        opts,
+        state.bindings,
+      ) as Promise<RpcResult<EventsOf<B>[typeof name]>>;
     },
     subscribe(topic) {
       state.subscribedTopics.add(topic);
@@ -158,6 +229,9 @@ export function createClient(url: string, opts: IgnClientOptions = {}): IgnClien
       state.subscribedTopics.delete(topic);
       sendControl(state, "unsubscribe", { topic });
     },
+    snapshotRequest(topic, fromSeq = 0) {
+      sendControl(state, "snapshotRequest", { topic, fromSeq });
+    },
     joinGroup(group) {
       sendControl(state, "joinGroup", { group });
     },

package/src/core/groups.ts

@@ -14,6 +14,11 @@ import type { ServerState, WsData } from "./state";
 
 /** Add `ws` to `group` (idempotent) and index it in `state.groups`. */
 export function joinGroup(state: ServerState, ws: ServerWebSocket<WsData>, group: string): void {
+  // every join path (control frames, programmatic, auth-seeded) is gated
+  if (state.authorizeGroup !== undefined && !state.authorizeGroup(group, ws)) {
+    state.metrics.rejectedJoins++;
+    return;
+  }
   ws.data.groups.add(group);
   let set = state.groups.get(group);
   if (!set) {
@@ -21,6 +26,8 @@ export function joinGroup(state: ServerState, ws: ServerWebSocket<WsData>, group
     state.groups.set(group, set);
   }
   set.add(ws);
+  // events-layer hook (auth seed, control frames, programmatic joins all pass here)
+  state.onGroupChange?.(group, ws, true);
 }
 
 /** Remove `ws` from `group`; prune the group when it becomes empty. */
@@ -30,6 +37,7 @@ export function leaveGroup(state: ServerState, ws: ServerWebSocket<WsData>, grou
   if (!set) return;
   set.delete(ws);
   if (set.size === 0) state.groups.delete(group);
+  state.onGroupChange?.(group, ws, false);
 }
 
 /** Fan `frame` out to every member of `group` (no replay). */

package/src/core/metrics.ts

@@ -1,14 +1,19 @@
 /**
  * Server-side metrics counters — a `createMetrics()` factory returning a plain
- * counter object (no class, no `this`). Zero dependencies, no allocations in
- * the steady state (counters are plain numbers; `countPath` only allocates on
- * the first occurrence of an event name).
+ * counter object (no class, no `this`). Zero dependencies and zero allocation
+ * in the steady state (every counter is a plain number field).
+ *
+ * Per-event encode-path counts (`pathCounts`) are NOT tracked here: they live
+ * once, cumulatively, in the transport's per-event records and are derived at
+ * read time by `server.getMetrics()` — polling can never double-count.
  */
 export interface PathCounts {
   /** encodes that used the zero-alloc Rust FFI direct fast path */
   direct: number;
   /** encodes that fell back to the JSON path (nested/unions or disabled symbol) */
   json: number;
+  /** encodes via the pure-JS encoder (user schema without a native addon) */
+  js: number;
 }
 
 export interface MetricsSnapshot {
@@ -28,8 +33,20 @@ export interface MetricsSnapshot {
   inboundControl: number;
   /** undecodable / version-mismatched / unknown-id frames received */
   protocolErrors: number;
+  /** inbound frames shed by the per-connection rate limiter */
+  rateLimited: number;
+  /** topic/group joins rejected by `authorizeTopic` / `authorizeGroup` */
+  rejectedJoins: number;
   bytesSent: number;
-  /** per-event encode path counts (direct vs json) */
+  /** frames stamped with a per-connection delivery seq (envelope v2, resume on) */
+  stampedSeq: number;
+  /** `resume` control frames served from a connection's history ring */
+  resumesServed: number;
+  /** frames re-delivered by resume replays */
+  framesReplayed: number;
+  /** resume requests that could not fully fill the requested hole */
+  resumeMisses: number;
+  /** per-event encode path counts (derived from the transport at read time) */
   pathCounts: Record<string, PathCounts>;
   connectedClients: number;
   uptimeMs: number;
@@ -41,6 +58,8 @@ export interface MetricsSnapshot {
   bridgeInboundErrors?: number;
   /** "connected" | "connecting" | "closed" (undefined when no bridge) */
   natsStatus?: string;
+  /** events-layer counters (present only when `createServer({ events })` is used) */
+  events?: import("../events/types").EventsMetricsSnapshot;
 }
 
 export interface Metrics {
@@ -52,16 +71,17 @@ export interface Metrics {
   inbound: number;
   inboundControl: number;
   protocolErrors: number;
+  rateLimited: number;
+  rejectedJoins: number;
   bytesSent: number;
-  readonly pathCounts: Map<string, PathCounts>;
-  /** Count an encode on a given path for an event (direct = zero-alloc FFI). */
-  countPath(name: string, path: "direct" | "json"): void;
+  stampedSeq: number;
+  resumesServed: number;
+  framesReplayed: number;
+  resumeMisses: number;
   snapshot(connectedClients: number): MetricsSnapshot;
 }
 
 export function createMetrics(startedAt = Date.now()): Metrics {
-  const pathCounts = new Map<string, PathCounts>();
-
   const m: Metrics = {
     published: 0,
     sent: 0,
@@ -71,19 +91,14 @@ export function createMetrics(startedAt = Date.now()): Metrics {
     inbound: 0,
     inboundControl: 0,
     protocolErrors: 0,
+    rateLimited: 0,
+    rejectedJoins: 0,
     bytesSent: 0,
-    pathCounts,
-    countPath(name, path) {
-      let pc = pathCounts.get(name);
-      if (!pc) {
-        pc = { direct: 0, json: 0 };
-        pathCounts.set(name, pc);
-      }
-      pc[path]++;
-    },
+    stampedSeq: 0,
+    resumesServed: 0,
+    framesReplayed: 0,
+    resumeMisses: 0,
     snapshot(connectedClients) {
-      const pathCountsObj: Record<string, PathCounts> = {};
-      for (const [name, pc] of pathCounts) pathCountsObj[name] = { ...pc };
       return {
         published: m.published,
         sent: m.sent,
@@ -93,8 +108,14 @@ export function createMetrics(startedAt = Date.now()): Metrics {
         inbound: m.inbound,
         inboundControl: m.inboundControl,
         protocolErrors: m.protocolErrors,
+        rateLimited: m.rateLimited,
+        rejectedJoins: m.rejectedJoins,
         bytesSent: m.bytesSent,
-        pathCounts: pathCountsObj,
+        stampedSeq: m.stampedSeq,
+        resumesServed: m.resumesServed,
+        framesReplayed: m.framesReplayed,
+        resumeMisses: m.resumeMisses,
+        pathCounts: {},
         connectedClients,
         uptimeMs: Date.now() - startedAt,
       };

package/src/core/outbound.ts

@@ -4,11 +4,11 @@
  * `decide()` result; `doSend` is the single accounting point.
  */
 import type { ServerWebSocket } from "bun";
-import { encodeToScratch } from "../transport/transport";
+import type { ControlEventName, ControlEvents } from "../schema";
 import { decide } from "./backpressure";
 import { RingBuffer } from "./ring";
+import { ensureHistory, recordSent, stampSeq } from "./resume";
 import type { ServerState, WsData } from "./state";
-import type { ControlEventName, ControlEvents } from "../schema";
 
 /** Actual socket write + counters (single accounting point). */
 export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
@@ -18,13 +18,52 @@ export function doSend(state: ServerState, ws: ServerWebSocket<WsData>, frame: U
 }
 
 /**
- * Send one frame to a socket, honoring the configured backpressure policy.
- * Happy path (no backpressure configured, or socket under the high-water mark)
- * is a direct `ws.send` — zero allocations. Under pressure, `ws.send` is
- * replaced by a bounded queue (drop-oldest) / skip (drop-newest) / close
- * (disconnect).
+ * Send one frame to a socket, honoring the configured backpressure policy AND
+ * (when resume is enabled) stamping a per-connection delivery seq into the
+ * envelope v2 header first. Only APP frames are stamped: the delivery seq is
+ * an app-delivery guarantee, and control frames (ping/pong/welcome/resume
+ * acks) must never create ordering obligations for the client's gap gate.
+ *
+ * The stamp mutates the shared scratch view IN PLACE — safe because every
+ * external copy (bridge / cluster / replay history) is taken before this
+ * point, and `ws.send` copies synchronously.
+ *
+ * Pass `seq` to send a pre-stamped frame verbatim (resume replays keep their
+ * original delivery seqs and are not re-recorded).
  */
-export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame: Uint8Array): void {
+export function sendFrame(
+  state: ServerState,
+  ws: ServerWebSocket<WsData>,
+  frame: Uint8Array,
+  opts?: { readonly seq?: number },
+): void {
+  if (opts?.seq !== undefined) {
+    // pre-stamped replay frame — write it as-is
+    const bp0 = state.bp;
+    if (!bp0) {
+      doSend(state, ws, frame);
+      return;
+    }
+    const d0 = decide(bp0, ws);
+    if (d0.kind === "send") doSend(state, ws, frame);
+    else if (d0.kind === "close") {
+      state.metrics.disconnectedSlow++;
+      ws.close(1013, "slow consumer");
+    }
+    return;
+  }
+  if (
+    state.resume !== null &&
+    state.resume !== undefined &&
+    !isControlFrame(state.bindings, frame) &&
+    ensureHistory(state, ws) !== undefined
+  ) {
+    const seq = ws.data.sendSeq++;
+    if (stampSeq(state.bindings, frame, seq)) {
+      recordSent(state, ws, frame, seq);
+      state.metrics.stampedSeq++;
+    }
+  }
   const bp = state.bp;
   if (!bp) {
     doSend(state, ws, frame);
@@ -44,8 +83,12 @@ export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame
       return;
     case "enqueue": {
       // RingBuffer: O(1) push + drop-from-head (no array shift() memmove).
-      const q = (ws.data.queue ??= new RingBuffer<Uint8Array>());
-      q.push(frame.slice()); // owned copy for the queue
+      let q = ws.data.queue;
+      if (q === undefined) {
+        q = new RingBuffer<Uint8Array>();
+        ws.data.queue = q;
+      }
+      q.push(frame.slice()); // owned copy for the queue (already seq-stamped)
       for (let i = 0; i < d.dropHead; i++) {
         q.shift();
         state.metrics.droppedOldest++;
@@ -55,6 +98,14 @@ export function sendFrame(state: ServerState, ws: ServerWebSocket<WsData>, frame
   }
 }
 
+/** Cheap envelope-id probe: true when `frame` is a transport-internal event. */
+function isControlFrame(bindings: ServerState["bindings"], frame: Uint8Array): boolean {
+  if (frame.byteLength < 5) return false;
+  const id =
+    (frame[1]! | (frame[2]! << 8) | (frame[3]! << 16) | (frame[4]! << 24)) >>> 0;
+  return bindings.isControlId(id);
+}
+
 /** Flush a slow socket's drop-oldest queue as the OS buffers drain. */
 export function drainSocket(state: ServerState, ws: ServerWebSocket<WsData>): void {
   const q = ws.data.queue;
@@ -72,5 +123,5 @@ export function sendControl<K extends ControlEventName>(
   name: K,
   payload: ControlEvents[K],
 ): void {
-  sendFrame(state, ws, encodeToScratch(name, payload));
+  sendFrame(state, ws, state.transport.encodeToScratch(name, payload));
 }

package/src/core/rate-limit.ts

@@ -0,0 +1,69 @@
+/**
+ * Per-connection inbound rate limiting — a token bucket evaluated on EVERY
+ * inbound frame (app AND control) before any decode work, so a flooding
+ * client pays ~nothing and can't starve the loop.
+ *
+ * Default OFF (`options.rateLimit` unset → `null`, zero hot-path overhead).
+ * When enabled, each connection lazily gets its own limiter on its first
+ * inbound frame (no per-connect allocation for idle listeners):
+ *
+ *   - tokens refill continuously at `messagesPerSecond`;
+ *   - bucket capacity is `burst` (default = messagesPerSecond), so short
+ *     spikes ride through while sustained floods are shed;
+ *   - `policy: "drop"` silently sheds over-limit frames (counted in
+ *     `metrics.rateLimited`); `policy: "close"` closes the socket 1008.
+ */
+export interface RateLimitOptions {
+  /** sustained inbound frames per second per connection, default 100 */
+  messagesPerSecond?: number;
+  /** burst capacity above the sustained rate, default = messagesPerSecond */
+  burst?: number;
+  /** what happens to over-limit frames, default "drop" */
+  policy?: "drop" | "close";
+}
+
+/** Fully-resolved options (defaults applied once at server creation). */
+export type ResolvedRateLimit = Required<RateLimitOptions>;
+
+export interface RateLimiter {
+  readonly policy: "drop" | "close";
+  /** Consume one inbound frame; false = over limit. Monotonic `now` (epoch ms). */
+  allow(now: number): boolean;
+}
+
+const MIN_RATE = 0.001; // guard against a zero refill (permanent lock-up)
+
+/** Apply option defaults once at instantiation time (not per message). */
+export function resolveRateLimit(opts?: RateLimitOptions): ResolvedRateLimit | null {
+  if (!opts) return null;
+  const messagesPerSecond = Math.max(MIN_RATE, opts.messagesPerSecond ?? 100);
+  const burst = Math.max(1, opts.burst ?? Math.ceil(messagesPerSecond));
+  return { messagesPerSecond, burst, policy: opts.policy ?? "drop" };
+}
+
+/**
+ * Create one connection's limiter from resolved options. The bucket starts
+ * FULL (`burst` tokens) so a well-behaved client is never punished for
+ * connecting right after a burst of legitimate traffic.
+ */
+export function createRateLimiter(r: ResolvedRateLimit): RateLimiter {
+  let tokens = r.burst;
+  let last = -1; // anchored on the FIRST frame (no pre-first-frame credit)
+  return {
+    policy: r.policy,
+    allow(now: number): boolean {
+      if (last < 0) {
+        last = now;
+      } else if (now > last) {
+        // continuous refill since the last consume (clamped to capacity)
+        tokens = Math.min(r.burst, tokens + ((now - last) / 1000) * r.messagesPerSecond);
+        last = now;
+      }
+      if (tokens >= 1) {
+        tokens -= 1;
+        return true;
+      }
+      return false;
+    },
+  };
+}

package/src/core/replay.ts

@@ -6,6 +6,11 @@
  * History is a bounded `RingBuffer` (capacity = historySize): recording is O(1)
  * and, once full, the OLDEST frame is overwritten automatically — same
  * semantics as the old `push` + `shift`, but without the O(n) array shift.
+ *
+ * DURABILITY SEAM: an optional {@link TopicLog} (see `topic-log.ts`) receives
+ * every recorded frame so history can outlive the ring window. When a client
+ * asks for a seq the ring no longer holds, `topicHistoryFrom` hydrates the
+ * missing prefix from the log.
  */
 import { RingBuffer } from "./ring";
 import type { ServerState } from "./state";
@@ -18,7 +23,9 @@ export function recordReplay(state: ServerState, topic: string, frame: Uint8Arra
     hist = new RingBuffer<{ seq: number; frame: Uint8Array }>(state.replay.historySize, true);
     state.topicHistory.set(topic, hist);
   }
-  hist.push({ seq: ++state.replaySeq, frame: frame.slice() }); // owned copy for replay
+  const seq = ++state.replaySeq;
+  hist.push({ seq, frame: frame.slice() }); // owned copy for replay
+  state.topicLog?.append(topic, frame, seq);
 }
 
 /** The recorded frames for `topic`, oldest → newest (already owned copies). */
@@ -29,3 +36,36 @@ export function replayFrames(state: ServerState, topic: string): Uint8Array[] {
   for (const e of hist) out.push(e.frame);
   return out;
 }
+
+/**
+ * Recorded frames for `topic` strictly after `fromSeq` (0 = everything
+ * retained), oldest → newest. Synchronous: serves from the in-memory ring;
+ * when the ring's oldest entry leaves a hole above `fromSeq` and a durable
+ * {@link TopicLog} is configured, the missing prefix is hydrated from the log
+ * (blocking briefly is acceptable on this control path).
+ */
+export function topicHistoryFrom(
+  state: ServerState,
+  topic: string,
+  fromSeq: number,
+): Uint8Array[] {
+  const hist = state.topicHistory.get(topic);
+  const ring: Array<{ seq: number; frame: Uint8Array }> = [];
+  if (hist) for (const e of hist) if (e.seq > fromSeq) ring.push(e);
+  if (ring.length === 0) {
+    // nothing in the ring at/after the resume point — try the durable log
+    const log = state.topicLog;
+    if (log && fromSeq > 0) return log.range(topic, fromSeq).map((e) => e.frame);
+    return [];
+  }
+  const oldest = ring[0]!.seq;
+  if (oldest > fromSeq + 1 && oldest > 1) {
+    // hole between fromSeq and the ring window — hydrate the prefix
+    const log = state.topicLog;
+    if (log) {
+      const prefix = log.range(topic, fromSeq, oldest - fromSeq - 1);
+      return [...prefix.map((e) => e.frame), ...ring.map((e) => e.frame)];
+    }
+  }
+  return ring.map((e) => e.frame);
+}