@ignex/nova 0.1.3 → 0.1.5

package/README.md

@@ -292,9 +292,12 @@ createServer({
   replay: { historySize: 64 },      // per-topic last-value replay on subscribe
   authenticate: async (req) => checkToken(req.headers.get("authorization")),
   allowedOrigins: ["http://localhost:3000"],
-  token: "shared-secret",           // or (tok) => boolean
+  token: "shared-secret",           // or (tok) => boolean — constant-time compared
   maxConnections: 10_000,
   maxMessageSize: 64 * 1024,
+  rateLimit: { messagesPerSecond: 100, burst: 200, policy: "drop" }, // per-conn inbound bucket ("close" → 1008)
+  authorizeTopic: (topic, ws) => topic !== "admin",   // gate room joins (all paths)
+  authorizeGroup: (group, ws) => ws.data.userId != null, // gate group joins
   int64Guard: "warn",               // "off" | "throw" | "warn"
   nats: { servers: ["nats://localhost:4222"], inbound: true }, // optional NATS bridge
   tls: { keyFile, certFile },       // enables wss://

package/docs/ai/TREE.md

@@ -5,10 +5,10 @@
 > curated maps live in `docs/architecture.md` + `docs/wire-format.md`
 > (and `AGENTS.md` for agents).
 
-- package: `@ignex/nova` v0.1.1
+- package: `@ignex/nova` v0.1.3
 - engines: {"bun":">=1.4"}
 - rust crate: `ignex-nova-ffi` v0.1.0
-- scripts (19): `generate`, `build:rust`, `build:client`, `build:dist`, `build`, `prebuild`, `test`, `lint`, `typecheck`, `verify`, `pack:check`, `gen:ai-map`, …
+- scripts (20): `generate`, `build:rust`, `build:client`, `build:dist`, `build`, `prebuild`, `test`, `lint`, `typecheck`, `verify`, `pack:check`, `gen:ai-map`, …
 
 ## src/
 
@@ -19,7 +19,11 @@ src/
 │  ├─ default.ts
 │  └─ types.ts
 ├─ bridge/
-│  ├─ nats.ts
+│  ├─ nats/
+│  │  ├─ inbound.ts
+│  │  ├─ index.ts
+│  │  ├─ real-transport.ts
+│  │  └─ types.ts
 │  └─ subjects.ts
 ├─ codegen/
 │  ├─ constants.ts
@@ -32,10 +36,17 @@ src/
 │  ├─ ts-ser-gen.ts
 │  └─ typebox-to-fbs.ts
 ├─ core/
+│  ├─ server/
+│  │  ├─ client-info.ts
+│  │  ├─ http-routes.ts
+│  │  ├─ index.ts
+│  │  ├─ metrics-view.ts
+│  │  └─ socket-lifecycle.ts
 │  ├─ auth.ts
 │  ├─ backpressure.ts
 │  ├─ client-heartbeat.ts
 │  ├─ client-reconnect.ts
+│  ├─ client-rpc.ts
 │  ├─ client-state.ts
 │  ├─ client-wire.ts
 │  ├─ client.ts
@@ -43,24 +54,59 @@ src/
 │  ├─ int64-guard.ts
 │  ├─ metrics.ts
 │  ├─ outbound.ts
+│  ├─ rate-limit.ts
 │  ├─ replay.ts
+│  ├─ resume.ts
 │  ├─ ring.ts
 │  ├─ rooms.ts
 │  ├─ routing.ts
-│  ├─ server.ts
-│  └─ state.ts
+│  ├─ state.ts
+│  └─ topic-log.ts
 ├─ events/
+│  ├─ cluster/
+│  │  ├─ dedupe.ts
+│  │  ├─ envelope.ts
+│  │  ├─ index.ts
+│  │  ├─ keys.ts
+│  │  ├─ kinds.ts
+│  │  ├─ presence-table.ts
+│  │  ├─ presence.ts
+│  │  ├─ redis-client.ts
+│  │  ├─ store-memory.ts
+│  │  ├─ store-redis.ts
+│  │  ├─ subjects.ts
+│  │  ├─ sync.ts
+│  │  ├─ transport-nats.ts
+│  │  └─ transport-redis.ts
+│  ├─ hub/
+│  │  ├─ context-factory.ts
+│  │  ├─ dispatch.ts
+│  │  ├─ index.ts
+│  │  ├─ internal.ts
+│  │  ├─ metrics-snapshot.ts
+│  │  └─ resolve-cluster.ts
+│  ├─ types/
+│  │  ├─ client.ts
+│  │  ├─ cluster.ts
+│  │  ├─ context.ts
+│  │  ├─ emit-target.ts
+│  │  ├─ groups.ts
+│  │  ├─ hub.ts
+│  │  ├─ index.ts
+│  │  ├─ metrics.ts
+│  │  └─ options.ts
 │  ├─ clients.ts
-│  ├─ cluster.ts
+│  ├─ cluster-rpc.ts
 │  ├─ data.ts
+│  ├─ delivery.ts
 │  ├─ emit.ts
 │  ├─ global.ts
 │  ├─ groups.ts
-│  ├─ hub.ts
 │  ├─ index.ts
 │  ├─ queue.ts
 │  ├─ registry.ts
-│  └─ types.ts
+│  ├─ schedule.ts
+│  └─ trace.ts
 ├─ generated/
 │  ├─ fbs/
 │  │  └─ backend.fbs
@@ -82,6 +128,10 @@ src/
 │  │  ├─ portfolio-position.ts
 │  │  ├─ portfolio-snapshot.ts
 │  │  ├─ quote.ts
+│  │  ├─ resume.ts
+│  │  ├─ resumed.ts
+│  │  ├─ rpc-call.ts
+│  │  ├─ rpc-result.ts
 │  │  ├─ side.ts
 │  │  ├─ snapshot-request.ts
 │  │  ├─ subscribe.ts
@@ -102,7 +152,6 @@ src/
 ├─ transport/
 │  ├─ byte-buffer-pool.ts
 │  ├─ scratch.ts
-│  ├─ stats.ts
 │  └─ transport.ts
 └─ server.ts
 ```
@@ -158,8 +207,11 @@ test/
 ├─ bidirectional.test.ts
 ├─ bindings-gen.test.ts
 ├─ byte-buffer-pool.test.ts
+├─ cluster-v2.test.ts
+├─ data-integrity-edge.test.ts
 ├─ direct.test.ts
 ├─ e2e.test.ts
+├─ efficiency.test.ts
 ├─ events-cluster.test.ts
 ├─ events.test.ts
 ├─ ffi.test.ts
@@ -171,12 +223,19 @@ test/
 ├─ metrics.test.ts
 ├─ nats-bridge.test.ts
 ├─ nats-integration.test.ts
+├─ performance.test.ts
 ├─ reconnect.test.ts
+├─ resume.test.ts
 ├─ ring.test.ts
 ├─ rooms.test.ts
 ├─ roundtrip.test.ts
+├─ rpc.test.ts
+├─ security-hardening.test.ts
+├─ security-live-fuzz.test.ts
 ├─ security.test.ts
+├─ stability-resilience.test.ts
 ├─ targeting.test.ts
+├─ trace.test.ts
 └─ wire.test.ts
 ```
 
@@ -185,6 +244,7 @@ test/
 ```
 bench/
 ├─ BASELINE.md
+├─ dispatch.ts
 ├─ ffi-margin.ts
 ├─ measure.ts
 ├─ serialize.ts

package/docs/architecture.md

@@ -38,7 +38,7 @@ are thin re-export shims that keep the npm entrypoints (`@ignex/nova/server`,
 `@ignex/nova/client`) and the `dist` build stable; the implementation lives in
 `src/core/`.
 
-- **Composition roots** (`src/core/server.ts`, `src/core/client.ts`) — the only
+- **Composition roots** (`src/core/server/`, `src/core/client.ts`) — the only
   places that know how the pieces fit together. `createServer(options)` builds
   the `ServerState`, wires `Bun.serve`, and returns a plain API object;
   `createClient(url, opts)` builds the client state and returns a plain API
@@ -50,7 +50,9 @@ are thin re-export shims that keep the npm entrypoints (`@ignex/nova/server`,
   the per-socket queue), `routing` (inbound dispatch), and the client's
   `client-wire` / `client-reconnect` (pure backoff math) / `client-heartbeat`.
 - **Factories** for encapsulated mutable state: `createMetrics()`, `createScratch()`
-  (reusable zero-alloc output buffer), `createStats()` (encode-path counters).
+  (reusable zero-alloc output buffer), per-event `EncodeRecord`s (encode-path
+  counters resolved eagerly at `createTransport()` — instantiation time, not
+  first-encode).
   `int64-guard` intentionally stays a module-global (cheap `off`-mode no-op) so
   threading it through the generated encoders can't cost the ~200ns hot path.
 - **Dev discipline**: `bun run lint` (oxlint with FP rules: no-var,
@@ -82,21 +84,42 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
 - `public/server.ts`, `public/client.ts`, `public/nats.ts` — thin re-export shims
   (npm entrypoints `@ignex/nova/server` / `client` / `nats` + the `dist` build).
   Implementation is in `src/core/` + `src/bridge/`.
-- `src/core/server.ts` — `createServer` composition root: `Bun.serve`, client
-  registry (id → socket), rooms, groups, inbound routing, control frames,
-  auth/origin/token gates, backpressure, replay history, metrics, NATS bridge
-  hook, graceful drain, `/health` + `/clients`.
+- `src/core/server/index.ts` — `createServer` composition root: `Bun.serve`,
+  client registry (id → socket), rooms, groups, inbound routing, control
+  frames, auth/origin/token gates, backpressure, replay history, metrics,
+  NATS bridge hook, graceful drain, `/health` + `/clients`. Decomposed into
+  sibling modules: `client-info.ts` (pure introspection mapper),
+  `http-routes.ts` (fetch handler), `socket-lifecycle.ts` (open/close as
+  `(state, ws)` actions), `metrics-view.ts` (pure snapshot assembly).
 - `src/core/client.ts` — `createClient` composition root: typed
   `on`/`send`/`subscribe`/`joinGroup`, reconnect with backoff, heartbeat, status
-  events, `clientId`/`groups` (from the `welcome` control frame).
-- `src/core/{state,auth,rooms,groups,replay,backpressure,outbound,routing}.ts` —
+  events, `clientId`/`groups` (from the `welcome` control frame); the rpc
+  plumbing (`client.request`) lives in `client-rpc.ts`.
+- `src/core/{state,auth,rooms,groups,replay,backpressure,outbound,routing,resume,rate-limit}.ts` —
   server action modules over the explicit `ServerState`. `groups.ts` mirrors
   `rooms.ts` (targeting sets, no replay); `state.clients` is the id→socket
-  registry, `state.groups` the group→members index.
+  registry, `state.groups` the group→members index. `rate-limit.ts` is the
+  per-connection token bucket (`options.rateLimit`, default off); `auth.ts`
+  compares literal bearer tokens in constant time and gates the HTTP admin
+  surface; topic/group joins are authorized via `authorizeTopic` /
+  `authorizeGroup`. `resume.ts` is gap-free delivery (below). `replay.ts`
+  serves per-topic snapshots (`snapshotRequest { topic, fromSeq }`) and feeds
+  the optional durable topic log; `topic-log.ts` is the pluggable durability
+  seam (`createMemoryTopicLog()` ships in-repo).
+- **Gap-free delivery** (`src/core/resume.ts`, envelope v2): with
+  `createServer({ resume })` every APP frame is stamped (in place, pre-`ws.send`)
+  with a per-connection delivery seq and recorded in a bounded per-connection
+  history ring. A client that detects a hole sends `resume { lastSeq }`; the
+  server replays from the ring with ORIGINAL seqs (in-order, duplicate-free).
+  On disconnect the ring parks in a bounded/TTL'd graveyard keyed by client id;
+  a reconnecting session adopts it via `hello { lastSeq }`. Control frames are
+  never stamped (no ordering obligations), and external copies (NATS bridge /
+  cluster envelope) are always taken BEFORE stamping mutates the scratch.
 - `src/core/{client-state,client-wire,client-reconnect,client-heartbeat}.ts` —
   client action modules over the explicit client state.
-- `src/bridge/{nats,subjects}.ts` — optional NATS bridge: `createNatsBridge`
-  (injectable `NatsTransport` for tests; eager non-blocking connect with retry),
+- `src/bridge/` — optional NATS bridge (`createNatsBridge`;
+  injectable `NatsTransport` for tests; eager non-blocking connect with retry;
+  `nats/{index,types,real-transport,inbound}.ts` + `subjects.ts`),
   subject builders (`ignex.broadcast.*` / `ignex.topic.*` / `ignex.group.*` /
   inbound `ignex.inbound.>`). Outbound frames are copied from the shared
   scratch; inbound frames are decoded via `readFrameHeader`/`decodePayload` and
@@ -105,15 +128,28 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
 - `src/core/metrics.ts`, `src/core/int64-guard.ts` — `createMetrics()` factory
   + the exact-int64 safety net.
 - `src/events/*` — the events layer (opt-in via `createServer({ events })`,
-  public entry `@ignex/nova/events` → `public/events.ts`): `hub.ts` composition
-  root (`server.events`, binds the module-global `emit`/`on` singleton),
-  `types.ts` (`EventClient` records with `userId` + per-connection `data`,
-  `EmitTarget` discriminated union, hub/options interfaces), `registry.ts`
-  (multi-handler dispatch with isolation), `clients.ts`/`data.ts` (client
-  store: byId + byUser index), `groups.ts` (client groups reusing the
-  transport registry + user groups), `emit.ts` (encode-once local fan-out +
-  bridge + cluster), `cluster.ts` (origin-tagged envelope, NATS/Redis/custom
-  transports, presence, shared-state indexes), `queue.ts` (bounded offload
+  public entry `@ignex/nova/events` → `public/events.ts`): `hub/` composition
+  root (`server.events`, binds the module-global `emit`/`on` singleton;
+  decomposed into `context-factory.ts` (cached handler contexts),
+  `dispatch.ts` (reliability-aware dispatch), `metrics-snapshot.ts` (pure
+  snapshot assembly), `resolve-cluster.ts` (transport resolution)),
+  `types/` (`EventClient` records with `userId` + per-connection `data`,
+  `EmitTarget` discriminated union, hub/options interfaces — one module per
+  concern behind a barrel), `registry.ts`
+  (multi-handler dispatch with isolation — copy-on-write lists,
+  allocation-free dispatch, plus a settling variant for retries), `trace.ts`
+  (the zero-GC event trace ring behind `server.getEventTrace()`),
+  `clients.ts`/`data.ts` (client store: byId + byUser index), `groups.ts`
+  (client groups reusing the transport registry + user groups), `emit.ts`
+  (encode-once; bridge + cluster copies FIRST — pristine frames — then the
+  stamped local fan-out), `cluster/` (v2 envelope codec in `envelope.ts`,
+  presence codec + table, dedupe window, shared-state keys, NATS/Redis
+  transports and memory/Redis state stores; ROUTED targeted delivery via
+  per-instance subjects; broker-redelivery dedupe window), `delivery.ts`
+  (opt-in handler retry/backoff + dead-letter sink via `events.handlers`),
+  `schedule.ts` (`hub.schedule(name, payload, target, delayMs)` + cancel),
+  `cluster-rpc.ts` (cross-instance request/response: `hub.call` /
+  `hub.onMethod` over the cluster transport), `queue.ts` (bounded offload
   workers that keep all cluster/state work off the WS hot path), `global.ts`
   (the importable `emit`/`emitToGroup`/… singleton).
 - `src/transport/{transport,scratch,stats}.ts` — object → frame encoding:
@@ -140,11 +176,11 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
   `publishToGroup(group, …)` (server-side targeting sets — from auth metadata,
   `joinGroup(id, group)`, or client `joinGroup` control frames).
 - **Bridge**: `createServer({ nats })` creates a `NatsBridge`. The fan-out path
-  (`fanOutAll`) encodes once and reuses that frame for WS clients AND NATS
-  (`frame.slice()` copy — the scratch is reused). Subjects are derived by
-  `src/bridge/subjects.ts`. Inbound NATS events are decoded and forwarded via
-  `fanOutAll` (no bridge call → loop prevention). All bridge counters fold into
-  `server.getMetrics()`.
+  encodes once; the NATS copy is taken BEFORE per-socket delivery-seq stamping
+  mutates the scratch header, so external consumers see pristine frames.
+  Subjects are derived by `src/bridge/subjects.ts`. Inbound NATS events are
+  decoded and forwarded via `fanOutAll` (no bridge call → loop prevention). All
+  bridge counters fold into `server.getMetrics()`.
 
 ## Why it's fast
 
@@ -167,5 +203,17 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
   `Type.BigInt()` fields for exact values, or enable `int64Guard`.
 - The direct fast path covers flat types + packed vectors; nested single-object
   tables fall back to JSON (observable via metrics).
-- Full gap-based replay (per-frame sequence numbers) is a future extension;
-  today the server replays bounded per-topic history on subscribe.
+- Resume history is bounded (`resume.historySize`, default 256 frames) and the
+  cross-session graveyard is TTL'd (`resume.ttlMs`, default 60s): a hole older
+  than what is retained is reported `resumed { ok: false }` — clients should
+  resubscribe topics for a fresh snapshot. Frames published while NO session
+  for a client id exists are not buffered per-client (that's an offline-inbox
+  feature, not resume).
+- The durable topic log seam ships with a process-local implementation
+  (`createMemoryTopicLog`); production adapters (NATS JetStream / Redis
+  Streams / filesystem) implement the same three-method interface.
+- Cluster envelope v2 is not understood by v1 peers (rolling upgrades count
+  decode errors on the old instances until they are replaced).
+- Cross-instance rpc `.any` calls are delivered to every instance; the first
+  response wins and later responders still execute their handlers (keep
+  `.any` methods idempotent, or address a specific instance).

package/docs/events.md

@@ -142,15 +142,97 @@ deferred to a bounded offload queue (`events.queue`, drop-newest on overflow).
 - Self-delivery dedupe: frames carry the origin `instanceId`
   (`cluster.instanceId`, random by default); an instance drops its own frames,
   so a broadcast is delivered exactly once per socket.
+- **Broker-redelivery dedupe**: every message carries a unique id; a durable
+  broker that redelivers after reconnect gets its duplicates dropped inside the
+  receiver's window (`metrics.events.clusterDroppedDupe`).
+- **Routed targeted delivery**: `emitToClient` / `emitToUser` consult cluster
+  presence and are published ONLY to the per-instance subject of the instance(s)
+  that hold the destination socket(s) — not to the whole mesh. Unknown targets
+  fall back to the full-mesh wildcard (visible in
+  `metrics.events.clusterRouted` vs `clusterPublished`).
 - **Presence with no shared state**: join/leave + periodic heartbeat messages
-  — `hub.clusterClients()` lists connections on other instances.
+  — `hub.clusterClients()` lists connections on other instances;
+  `hub.clusterInstances()` lists the other instances themselves.
 - **Shared state store** (`cluster.state`, default per-instance memory;
   production: `createRedisStateStore(...)`): user→clients index
   (`clusterUserClients`), cluster group membership, cluster-wide client data.
+- **Cross-instance rpc** (`hub.call` / `hub.onMethod`): request/response
+  between instances over the same transport — targeted
+  (`call(method, args, { instanceId })`) or any-instance
+  (`call(method)` — first response wins; keep `.any` handlers idempotent).
+  Timeouts bound every call; counters fold into `metrics.events.rpcSent` /
+  `rpcReceived`.
+- **Trace propagation**: emits carry a unique trace id through the cluster
+  envelope; remote `onServerEvent` contexts expose it as `ctx.traceId` for
+  end-to-end correlation.
 - **Server-side events**: other instances' events reach `onServerEvent`
   handlers with `ctx.source === "remote"` (delivered to clients AND handlers);
   NATS-inbound events reach them with `source === "bridge"`.
 
+## Handler reliability — retries + dead letters
+
+Opt in via `createServer({ events: { handlers: {...} } })`; without it,
+dispatch is fire-and-forget with per-handler error isolation only.
+
+```ts
+createServer({
+  port: 3000,
+  events: {
+    handlers: {
+      retries: 2,          // extra attempts after the first try
+      backoffMs: 100,      // doubling: 100ms, 200ms, …
+      dlq(info) { /* { name, payload, err, attempts } */ },
+    },
+  },
+});
+```
+
+A handler that keeps failing is retried on the same event, then handed to
+`dlq`. Counters live in `server.getMetrics().events.handlerRetries` /
+`.dlqCount`.
+
+## Scheduled emits (time-based events)
+
+```ts
+const id = hub.schedule("reminder.push", payload, { type: "user", userId }, delayMs);
+hub.cancelScheduled(id);   // true if it had not fired yet
+hub.scheduledCount;        // pending count
+```
+
+Scheduled emits run through the normal emit path at fire time — identical
+targeting, bridging and cluster routing semantics. Timers are cleared on
+`hub.close()`.
+
+## Request/response
+
+Two complementary layers:
+
+- **Client ⇄ this server**: `client.request(name, payload)` sends an `rpcCall`
+  control frame (correlation id + timeout) and awaits the responder registered
+  via `server.handle(name, fn)` or `hub.onRequest(name, fn)`. The response
+  reuses the SAME event schema both directions.
+- **Instance ⇄ instance**: `hub.call` / `hub.onMethod` (above).
+
+## Event trace (what fired — debugger visibility)
+
+Every server owns an **event trace ring** (`src/events/trace.ts`) that records
+each fired event — emitted (`out.emit`), published through the server API
+(`out.publish`), received from a client (`in.client`), from another instance
+(`in.remote`), or from the NATS bridge (`in.bridge`) — with its wire name,
+target kind + key (topic/group/userId/clientId), frame size and timestamp.
+
+- **Zero-GC by construction**: scalars live in pre-allocated TypedArrays,
+  strings are held by reference in reused slots; row objects materialize only
+  when the ring is read. Recording is a handful of typed-array stores (~ns).
+- Read it with `server.getEventTrace({ limit, direction, name })` →
+  `{ enabled, capacity, stats, recent }` (newest first) and reset it with
+  `server.clearEventTrace()`. `stats.byName` / `stats.last` power at-a-glance
+  panels (the ignex debugbar's Nova panel and MCP tool use exactly this).
+- Configure with `createServer({ trace: { capacity, enabled, capturePayloadChars } })`.
+  Default: on, capacity 1024, no payload capture. `IGNEX_NOVA_TRACE=0`
+  disables recording globally; set `capturePayloadChars` (e.g. 512) to store
+  truncated JSON previews of each payload (opt-in — costs a stringify/event).
+
 ## Metrics & shutdown
 
 `server.getMetrics().events` (or `hub.metrics()`) exposes emitted counts per

package/docs/generic-bindings.md

@@ -52,6 +52,16 @@ Rules (same as the built-in registry):
 - The transport control events (hello / welcome / subscribe / unsubscribe /
   joinGroup / leaveGroup / snapshotRequest / ping / pong) are ALWAYS included —
   you can add your own but cannot override the standard ones.
+- **Unsupported field types fail loudly at generate time.** `Type.Any()`,
+  `Type.Unknown()`, `Type.Date()`, `Type.Null()`, `Type.Record(...)`, and mixed
+  unions (e.g. `number | string`) have no FlatBuffers representation and are
+  rejected with a clear error — they used to be *silently coerced to `string`
+  fields*, which forced `JSON.stringify(...)` at the call site and put raw JSON
+  text inside the (still-binary) frame. If you genuinely need an opaque JSON
+  payload, model it explicitly as `Type.String()` and pass the JSON string —
+  the frame stays valid, but the JSON bytes appear verbatim in it. Prefer typed
+  fields (nested tables, vectors, scalars) so the wire carries structure
+  instead of JSON text.
 
 ## 2. Generate bindings
 

package/docs/wire-format.md

@@ -8,18 +8,25 @@ client from the generated FlatBuffers schema — no Bun, no Rust, no FFI needed.
 Every WebSocket **binary** frame is:
 
 ```
-┌──────────┬───────────────────┬──────────────────────────────────┐
-│ version  │ event_id          │ size-prefixed FlatBuffer         │
-│ 1 byte   │ u32 (LE)          │ (flatc: 4-byte size prefix + buf)│
-└──────────┴───────────────────┴──────────────────────────────────┘
-    offset 0      1..5                 5..
+┌──────────┬───────────────────┬─────────┬────────────┬──────────────────────────────────┐
+│ version  │ event_id          │ flags   │ seq        │ size-prefixed FlatBuffer         │
+│ 1 byte   │ u32 (LE)          │ 1 byte  │ u64 (LE)   │ (flatc: 4-byte size prefix + buf)│
+└──────────┴───────────────────┴─────────┴────────────┴──────────────────────────────────┘
+    offset 0      1..5               5           6..14       14..
 ```
 
-- `version` = `WIRE_VERSION` (currently `1`). A peer MUST drop frames whose
-  version it doesn't recognize (the decoders return `null`).
+- `version` = `WIRE_VERSION` (currently `2` — v2 added the delivery header).
+  A peer MUST drop frames whose version it doesn't recognize (the decoders
+  return `null`).
 - `event_id` = **FNV-1a 32-bit hash of the event name** (e.g.
   `fnv1a32("quote")`). Stable across schema reordering; collisions are rejected
   at generate time. The id→name table is emitted in `src/generated/registry.ts`.
+- `flags` — bit0 = "seq-valid" (see below); all other bits reserved, send 0.
+- `seq` — per-CONNECTION delivery sequence, stamped by the SERVER on every
+  **app** frame just before `ws.send` (Bun copies synchronously). Clients use
+  it for gap detection + resume. Control frames are never stamped; frames that
+  were not per-destination stamped carry `flags=0, seq=0`. Offsets are derived
+  from `WIRE_HEADER_LEN`: flags at `len-9`, seq at `len-8..len`.
 - The payload is a **size-prefixed FlatBuffer** (built by flatc, both Rust
   builders and the TS object API) with the root table for that event id.
 
@@ -27,6 +34,18 @@ There is **no per-frame checksum and no authentication** — the envelope id byt
 is trusted. Integrity and AuthN are the application's job (see
 [Security](#security)).
 
+## String fields carry raw UTF-8
+
+A FlatBuffer `string` field stores its content as raw UTF-8 bytes in the frame,
+so any JSON document placed in a string field appears **verbatim** inside the
+(binary) frame — expected behavior, not corruption. If a captured frame shows
+`{"items":[...]}` text in the payload, the event schema models that data as a
+`string` field (a JSON-in-a-string envelope, or a field written as
+`Type.Any()`/`Type.Unknown()`, which the codegen now rejects at generate time —
+see docs/generic-bindings.md). Prefer typed fields — `Type.Array(Table)` for
+lists, `Type.Integer()` for counts — so the frame carries structure instead of
+JSON text.
+
 ## Event ids
 
 Event ids are stable hashes, so adding events, reordering the registry, or
@@ -46,13 +65,17 @@ SAME codegen, but are routed internally (never delivered to app handlers):
 
 | name | direction | payload |
 | --- | --- | --- |
-| `hello` | both | `{ version, caps: string[], lastSeq }` — sent on connect; version mismatch → close(1002) |
+| `hello` | both | `{ version, caps: string[], lastSeq }` — sent on connect; version mismatch → close(1002). `lastSeq > 0` asks the server to resume this client id's delivery stream after that seq (cross-session resume) |
 | `welcome` | server→client | `{ clientId, groups: string[] }` — identity assigned to this connection (auth metadata or UUID) + its server-side groups |
 | `subscribe` | client→server | `{ topic }` — join a room (server replies with replay history) |
 | `unsubscribe` | client→server | `{ topic }` |
 | `joinGroup` | client→server | `{ group }` — join a server-side group |
 | `leaveGroup` | client→server | `{ group }` |
-| `snapshotRequest` | client→server | `{ topic }` — reserved for future replay control |
+| `snapshotRequest` | client→server | `{ topic, fromSeq }` — replay recorded topic history STRICTLY after `fromSeq` (0 = from the beginning of retained history); hydrates from the durable topic log when the in-memory ring has moved on |
+| `resume` | client→server | `{ lastSeq }` — same-connection gap recovery: re-send everything after the last CONTIGUOUS delivery seq (original seqs preserved) |
+| `resumed` | server→client | `{ ok: boolean, from: number }` — ack before the replayed frames; `ok:false` = the hole is older than the retained history (partial recovery — resubscribe topics for a fresh snapshot) |
+| `rpcCall` | client→server | `{ id, name, payloadB64 }` — request/response: `payloadB64` is base64 of a full wire frame encoded with event `name`'s schema; the response reuses the SAME schema |
+| `rpcResult` | server→client | `{ id, ok, err, payloadB64 }` — correlated by `id`; `ok:false` carries a plain-text `err` |
 | `ping` | client→server | `{ ts }` — heartbeat |
 | `pong` | server→client | `{ ts }` |
 
@@ -118,7 +141,7 @@ consumer in any language:
 
 1. reads `version` (byte 0) and `event_id` (bytes 1..5) from the frame,
 2. maps `event_id` → name via `wire-registry.json`,
-3. decodes the size-prefixed FlatBuffer from `frame[5..]` with a flatc build of
+3. decodes the size-prefixed FlatBuffer from `frame[14..]` with a flatc build of
    `src/generated/fbs/backend.fbs`.
 
 See `examples/nats-consumer.ts` for a working reference.
@@ -137,12 +160,26 @@ Clients send `ping` every `heartbeatMs` (default 15000). The server replies
 long-idle sockets alive; a client that misses `heartbeatMisses` pongs force-
 closes and reconnects.
 
-## Sequence / replay
-
-The current model replays **recent history on subscribe** (bounded ring per
-topic, last-value snapshot). Full gap-based replay (per-frame sequence numbers
-in the envelope + `hello.lastSeq` negotiation) is a documented future extension;
-the envelope reserves no space for a per-frame seq today.
+## Sequence / resume / request-response
+
+- **Delivery seqs (v2)**: when the server starts with `resume`, every app frame
+  it writes to a socket carries an increasing per-connection `seq` (envelope
+  flags bit0). Clients track the stream; a GAP (lost frame — backpressure drop,
+  transport hiccup) is recovered by sending `resume { lastSeq }`; the server
+  replays from the connection's bounded sent-history ring with ORIGINAL seqs so
+  redelivery is in-order and duplicate-free. On disconnect the ring parks in a
+  per-client-id graveyard (bounded, TTL'd); a reconnecting session with the
+  same auth-pinned id continues the stream via `hello { lastSeq }`.
+- **Topic snapshots**: `snapshotRequest { topic, fromSeq }` replays recorded
+  topic history strictly after a topic seq; a durable `topicLog`
+  (`createServer({ topicLog })`, e.g. `createMemoryTopicLog()`) hydrates ranges
+  the replay ring has already forgotten. Topic-history seqs are a SEPARATE
+  counter (global replay order) from per-connection delivery seqs.
+- **Request/response**: `client.request(name, payload)` wraps a full wire frame
+  (base64) in an `rpcCall` control frame with a correlation id; the server's
+  registered responder (via `server.handle(name, fn)` or `hub.onRequest`)
+  returns the response payload encoded with the SAME event schema. Timeouts and
+  errors are correlated client-side.
 
 ## Security
 
@@ -151,7 +188,17 @@ the envelope reserves no space for a per-frame seq today.
   happily decode the payload as the claimed type. Add integrity at the
   application layer if the wire crosses an untrusted boundary.
 - Server-side guards (all optional): `authenticate(req)` async hook, origin
-  allowlist, bearer `token`, `maxConnections`, `maxMessageSize`.
+  allowlist, bearer `token` (literal tokens compared in constant time),
+  `maxConnections`, `maxMessageSize`, per-connection inbound rate limiting
+  (`rateLimit`: token bucket over app AND control frames — drop or close 1008,
+  counted in `metrics.rateLimited`).
+- Join authorization: `authorizeTopic(topic, ws)` / `authorizeGroup(group, ws)`
+  gate EVERY room/group join path (control frames, programmatic joins, and
+  auth-seeded membership); rejections are counted in `metrics.rejectedJoins`.
+  Leaving is always allowed.
+- Introspection: `GET /clients` is gated by the same token/`authenticate`
+  surface when one is configured (public only on servers with no auth at all);
+  `/health` stays public (counters only).
 - Slow consumers: `backpressure` policy (`drop-oldest`/`drop-newest`/
   `disconnect`) bounds per-socket buffering; without it a hot publish loop can
   balloon memory.
@@ -168,7 +215,7 @@ the envelope reserves no space for a per-frame seq today.
 3. Read `version` (byte 0) and `event_id` (bytes 1..5) from each binary frame.
    Compute ids with FNV-1a 32 over the name (see above) or read the emitted
    `src/generated/registry.ts` table.
-4. `flatbuffers.ByteBuffer(frame[5..])` + `getSizePrefixedRootAs<T>` (or the
+4. `flatbuffers.ByteBuffer(frame[14..])` + `getSizePrefixedRootAs<T>` (or the
    language equivalent) gives you the payload.
 5. Implement the control frames (at minimum `hello` + `ping`/`pong`) to be a
    good citizen; `subscribe` for rooms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignex/nova",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "TypeBox-driven FlatBuffer transport: Rust FFI serializer + Bun WebSocket + typed pub/sub API for server and FE.",
   "license": "MIT",
@@ -72,6 +72,7 @@
     "gen:ai-map": "bun scripts/gen-ai-map.ts",
     "serve": "bun run src/server.ts",
     "bench:serialize": "bun run bench/serialize.ts",
+    "bench:dispatch": "bun run bench/dispatch.ts",
     "bench:throughput": "bun run bench/throughput.ts",
     "release": "bun scripts/release.ts",
     "release:dry": "bun scripts/release.ts --dry-run",