@ignex/nova 0.1.1 → 0.1.5

package/docs/architecture.md

@@ -5,28 +5,40 @@ a Rust FFI serializer — hidden behind a typed pub/sub API.
 
 ## Pipeline
 
+The wire stack is generated from TypeBox schemas. The built-in registry
+(`src/schema/index.ts`) runs the in-repo orchestrator (`scripts/generate.ts`);
+**any** app can run the same emitters on its own schema via
+`generateBindings` (`@ignex/nova/generate` → `src/codegen/`).
+
 ```
 src/schema/index.ts (TypeBox — single source of truth: app events + control events)
-        │  scripts/generate.ts
+        │  scripts/generate.ts   (or generateBindings() for YOUR schema)
         ▼
 backend.fbs ──flatc --ts──▶ src/generated/ts/          (decoders, both sides)
         └───flatc --rust──▶ rust/src/generated/         (table builders)
-scripts/rust-glue-gen.ts ─▶ rust/src/transcode/         (JSON glue + direct-args FFI)
-scripts/direct-gen.ts ────▶ src/generated/direct-ser.ts (zero-alloc server encoder)
-scripts/ts-ser-gen.ts ─────▶ src/generated/ts-ser.ts    (pure-JS browser encoder)
-scripts/registry-gen.ts ───▶ src/generated/registry.ts  (event routing, both sides)
-scripts/generate.ts ────────▶ src/generated/wire-registry.json (name→id map for external consumers)
+src/codegen/rust-glue-gen.ts ─▶ rust/src/transcode/     (JSON glue + direct-args FFI)
+src/codegen/direct-gen.ts ────▶ src/generated/direct-ser.ts (zero-alloc server encoder)
+src/codegen/ts-ser-gen.ts ─────▶ src/generated/ts-ser.ts    (pure-JS browser encoder)
+src/codegen/registry-gen.ts ───▶ src/generated/registry.ts  (event routing, both sides)
+scripts/generate.ts ───────────▶ src/generated/wire-registry.json (name→id map for external consumers)
 ```
 
+Every artifact is also emitted per-user-schema by `generateBindings`
+(`src/codegen/*` emitters, `public/generate.ts`) into the app's
+`ignex/generated/` folder, then assembled into a runtime `Bindings`
+(`src/bindings/`) that `createServer` / `createClient` / `createNatsBridge`
+accept via `options.bindings` (default: the built-in `defaultBindings`). See
+[docs/generic-bindings.md](generic-bindings.md).
+
 ## Functional composition
 
 The public API is built by **functional composition over an explicit state
 object** — no classes, no `this`. `public/server.ts` and `public/client.ts`
-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
+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
@@ -38,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,
@@ -68,29 +82,76 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
 ## Runtime layout
 
 - `public/server.ts`, `public/client.ts`, `public/nats.ts` — thin re-export shims
-  (npm entrypoints `ignex-nova/server` / `client` / `nats` + the `dist` build).
+  (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
-  forwarded to clients (never re-bridged).
+  forwarded to clients (never re-bridged). `subscribeRaw` exposes raw byte
+  subscriptions (re-subscribed on reconnect) for the events cluster layer.
 - `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/` 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:
   `encodeToScratch` (direct/JSON), the reusable zero-alloc scratch, and
   encode-path stats.
@@ -115,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
 
@@ -142,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

@@ -0,0 +1,252 @@
+# Events layer — typed event-driven system on the FlatBuffer core
+
+The events layer (`@ignex/nova/events`, opt-in via `createServer({ events })`) is
+the application-facing, event-driven surface on top of the transport: **an
+events file receives events, and a global emit sends events through
+websockets** — with first-class client records, named groups, and
+cross-instance sync for horizontally scaled deployments.
+
+Enable it (everything else is opt-in):
+
+```ts
+import { createServer } from "@ignex/nova/server";
+
+const server = createServer({
+  port: 3000,
+  events: {
+    onConnect: (client) => client.data.set("connectedAt", client.connectedAt),
+  },
+});
+```
+
+`server.events` is the hub; the module-global singleton
+(`@ignex/nova/events`) is bound to it by default.
+
+## The events file (receiving events)
+
+Declare handlers like routes — a dedicated events file where inbound events
+arrive. The handler receives the payload and a context describing **who sent
+it and how to reply**:
+
+```ts
+// app/events.ts
+import { on, emitToUser, emitToGroup } from "@ignex/nova/events";
+
+on("chat.message", (payload, ctx) => {
+  // ctx.client — the sender's connection record (id, userId, data, groups…)
+  // ctx.emit / ctx.emitToUser / … — reply without importing the singleton
+  emitToUser(payload.to, "chat.delivered", { id: payload.id });
+});
+
+on("order.created", (payload, ctx) => {
+  emitToGroup("backoffice", "order.alert", { orderId: payload.orderId });
+});
+```
+
+- `hub.on(name, handler)` / `off` / `once` / `onAny` — multiple handlers per
+  event, per-handler error isolation (one throwing handler never blocks the
+  others; failures count in `metrics().handlerErrors`).
+- `hub.onServerEvent(name, handler)` — server-side handling of events that
+  arrive from OTHER instances or the NATS bridge (`ctx.source` is
+  `"remote"`/`"bridge"`, `ctx.client` is undefined). Do NOT re-emit the same
+  event from these handlers (loop).
+- `on` auto-allows the event for inbound clients (`server.allowInbound`);
+  `onAny` sees every event listed in `events.inbound`.
+
+## The global emit (sending events through websockets)
+
+`emit` and friends are importable anywhere — no server reference needed:
+
+```ts
+import { emit, emitToGroup, emitToUser, emitToClient, emitToTopic } from "@ignex/nova/events";
+
+emit("quote", { symbol: "AAPL", bid: 180.1, ask: 180.2 });          // broadcast
+emitToGroup("traders", "alert", { text: "halt" });                  // group fan-out
+emitToUser("u-42", "order.update", { orderId: "o-1" });             // user's sockets
+emitToClient("c-123", "session.expired", { reason: "idle" });       // one connection
+```
+
+Or the discriminated `EmitTarget` — the API's way of **differentiating**
+between addressing modes:
+
+```ts
+server.events.emit("quote", payload, { type: "group", group: "traders" });
+server.events.emit("quote", payload, { type: "user", userId: "u-42" });
+```
+
+When the cluster is configured, every emit is cluster-aware: the target is
+matched against clients on ALL instances.
+
+## Client records — who is connected, on whose behalf
+
+Each active connection is a `client` record:
+
+```ts
+interface EventClient {
+  id: string;              // connection id (unique per socket)
+  userId?: string;         // identity this connection acts ON BEHALF OF
+  meta?: Record<string, unknown>; // auth metadata
+  data: ClientData;        // per-connection app store (auto-cleared on close)
+  groups: ReadonlySet<string>;    // client groups (shared with ws.data)
+  topics: ReadonlySet<string>;    // joined topics (shared with ws.data)
+  connectedAt: number; ip: string; closed: boolean; ws: ServerWebSocket;
+}
+```
+
+- `userId` — "on what behalf": set from `authenticate` (`{ userId }`),
+  `hub.setUserId(clientId, userId)`, or later. Several sockets may share one
+  `userId` (multi-tab / multi-device); `hub.clientsByUser(userId)` groups
+  them and `emitToUser` reaches all of them.
+- `data` — per-connection state (`client.data.set(key, value)` or
+  `hub.setClientData(clientId, key, value)`); with a shared state store it
+  syncs cluster-wide (`hub.remoteClientData(clientId)`).
+- `hub.client(id)` / `clients()` / `clientCount` — live introspection.
+- Lifecycle hooks: `events.onConnect(client)` (seed data) and
+  `events.onDisconnect(client)`.
+
+## Groups — broadcast to groups vs individual users
+
+Two group kinds, clearly differentiated:
+
+| | `hub.group(name)` | `hub.userGroup(name)` |
+|---|---|---|
+| membership | connection ids | user ids |
+| fan-out | members' sockets | every socket of each member user |
+| shares transport groups | yes (`ws.data.groups`, control frames, `server.joinGroup`) | hub-managed |
+| cluster membership | shared state store (`clusterGroupMembers`) | shared state store (`clusterUserGroupMembers`) |
+
+```ts
+const traders = server.events.group("traders");       // client group
+traders.add(clientId); traders.remove(clientId);
+traders.members(); traders.emit("quote", payload);
+
+const ops = server.events.userGroup("ops");           // user group
+ops.add("u-42"); ops.emit("alert", { text: "pager" }); // all of u-42's sockets
+```
+
+## Horizontal scaling (cluster sync)
+
+When multiple instances share a broker, every emit is delivered to the
+target's clients on every instance. Heavy work never runs on the hot path:
+local delivery is synchronous (encode once via the transport scratch + `ws.send`),
+everything else (broker publishes, state-store writes, presence maintenance) is
+deferred to a bounded offload queue (`events.queue`, drop-newest on overflow).
+
+- **NATS** (server ⇄ server): reuse the server bridge with
+  `cluster: { nats: true }`, or a dedicated/different bridge
+  (`nats: NatsBridgeOptions | NatsBridge`).
+- **Redis**: `cluster: { redis: { url: "redis://…" } }` (lazy `ioredis`
+  optional peer dependency — `bun add ioredis`).
+- **Custom**: `cluster: { transport: MyClusterTransport }` (tests use an
+  in-memory bus).
+- 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.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
+target, delivered local frames, cluster received/self-dropped/errors,
+queue and handler errors, presence sizes. `hub.close()` unsubscribes,
+flushes the queue, announces leaves, and closes owned transports; call it via
+`server.drain()` / `server.stop()`.
+
+## Performance notes
+
+- Zero-alloc local encode + fan-out (the transport scratch is reused; Bun
+  copies on `ws.send`) — the emit call is O(target sockets).
+- The cluster publish copies the frame once (required — the scratch is
+  reused) and enqueues; a slow or offline broker never blocks the socket loop
+  and never throws into it.
+- Without `events`, there is zero overhead; the global functions throw a
+  descriptive error if no hub is bound.

package/docs/generic-bindings.md

@@ -0,0 +1,207 @@
+# Generic bindings — bring your own schema
+
+`@ignex/nova` is schema-driven: **any** TypeBox schema you define in your app can
+be turned into a full wire stack (FlatBuffers schema, TS decoders, pure-JS
+encoder, Rust FFI fast path, NATS wire registry) with one function call —
+`generateBindings(schema)` — and then served / consumed / bridged through the
+same `createServer` / `createClient` / `createNatsBridge` APIs, fully typed
+against **your** events.
+
+```
+your app
+  src/schema.ts (TypeBox — source of truth)
+        │  scripts/generate-bindings.ts
+        │  import { generateBindings } from "@ignex/nova/generate";
+        ▼
+  ignex/generated/  (backend.fbs, ts/decoders, registry.ts, ts-ser.ts,
+                     direct-ser.ts, wire-registry.json, rust/ crate, index.ts)
+        │  makeBindings(yourSchema) → Bindings
+        ▼
+  createServer({ bindings }) · createClient(url, { bindings }) · createNatsBridge({ bindings })
+```
+
+## 1. Define your schema (TypeBox)
+
+```ts
+// src/schema.ts — your app's single source of truth
+import { Type } from "@sinclair/typebox";
+
+export const ChatMsg = Type.Object(
+  { room: Type.String(), text: Type.String(), ts: Type.Integer() },
+  { additionalProperties: false },
+);
+export const Telemetry = Type.Object(
+  { device: Type.String(), readings: Type.Array(Type.Number()), ok: Type.Boolean() },
+  { additionalProperties: false },
+);
+
+export const schemas = { ChatMsg, Telemetry };
+export const events = { chat: ChatMsg, telemetry: Telemetry };
+export const controlEvents = {}; // optional extra transport-internal events
+```
+
+Rules (same as the built-in registry):
+
+- `Type.Object({...}, { additionalProperties: false })` for payloads.
+- `Type.Integer()` → int64; `Type.Integer({ bigint: true })` / `Type.BigInt()`
+  → exact bigint int64 (lossless beyond 2^53).
+- String-literal unions (`Type.Union([Type.Literal("a"), ...])`) → enums.
+- Arrays of scalars / strings / enums / flat objects → vectors (packed on the
+  direct fast path). Nested objects → tables. Tables-in-tables fall back to the
+  JSON path.
+- 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
+
+> `scripts/generate-bindings.ts` is an example filename **you** give a script in your own app — it is not a file shipped in the `@ignex/nova` package, so don't go looking for it in `node_modules`.
+
+```ts
+// scripts/generate-bindings.ts — run once per schema change
+import { generateBindings } from "@ignex/nova/generate";
+import { schemas, events, controlEvents } from "../src/schema";
+
+const gen = generateBindings(
+  { schemas, events, controlEvents },
+  { outDir: "./ignex/generated" }, // default
+);
+const written = gen.write(); // e.g. 26 files under ignex/generated/
+console.log("generated:", written.length, "files");
+```
+
+Requirements: `flatc` on PATH (the FlatBuffers compiler — the same prerequisite
+as the built-in registry: `brew install flatbuffers` /
+`apt install flatbuffers-compiler`). Pass `rust: false` to skip the Rust crate
+scaffold (you lose the FFI fast path; the pure-JS encoder is still used).
+
+The output folder contains:
+
+| File | Role |
+| --- | --- |
+| `backend.fbs` | FlatBuffers schema (wire layout for independent consumers) |
+| `ts/*.ts` | flatc-generated decoders (browser + Bun) |
+| `registry.ts` | event ids, `readFrameHeader` / `decodePayload` / `decodeFrame`, `SCHEMA_FINGERPRINT` |
+| `ts-ser.ts` | pure-JS encoder (works in the browser) |
+| `direct-ser.ts` | direct fast-path serde (Bun server, when FFI is used) |
+| `wire-registry.json` | machine-readable event-id registry for NATS consumers |
+| `rust/` | a complete cargo crate — build it for the FFI fast path |
+| `index.ts` | `makeBindings(schema)` — assembles the runtime `Bindings` |
+
+## 3. Assemble the bindings and use the APIs
+
+```ts
+// bindings.ts
+import { makeBindings } from "./ignex/generated"; // generated
+import * as schema from "../src/schema";
+
+export const bindings = makeBindings(schema);
+export type AppEvents = import("@ignex/nova").EventsOf<typeof bindings>;
+```
+
+```ts
+// server.ts (Bun)
+import { createServer } from "@ignex/nova/server";
+import { bindings } from "./bindings";
+
+const server = createServer({
+  port: 3000,
+  bindings,
+  inbound: ["chat"],                       // events clients may send
+  nats: { servers: ["nats://localhost:4222"], inbound: true, bridgeClientEvents: true },
+});
+server.publish("chat", { room: "lobby", text: "hello", ts: Date.now() }); // typed!
+server.on("chat", (msg, ws) => console.log(msg.room, msg.text));
+```
+
+```ts
+// FE (browser or Bun)
+import { createClient } from "@ignex/nova/client";
+import { bindings } from "./bindings";
+
+const client = createClient("ws://localhost:3000/ws", { bindings });
+client.on("telemetry", (t) => console.log(t.device, t.readings)); // typed!
+client.send("chat", { room: "lobby", text: "hi from FE", ts: Date.now() });
+client.connect();
+```
+
+The whole public surface is generic:
+
+- `createServer({ bindings })` → `publish` / `publishToTopic` / `publishToGroup`
+  / `on` / … typed against your `Events`.
+- `createClient(url, { bindings })` → `on` / `send` / `once` / `onAny` / …
+  typed against your `Events`.
+- `createNatsBridge({ bindings })` → decodes inbound frames with your schema.
+
+## Rust FFI fast path (optional)
+
+By default generated bindings use `ffiMode: "optional"`: the server tries the
+Rust addon only when you point `IGNEX_FFI_PATH` at one — otherwise it silently
+uses the pure-JS encoder (correct everywhere, just not zero-allocation). To get
+the fast path:
+
+```bash
+cd ignex/generated/rust
+cargo build --release            # produces libignex_ffi.so/.dylib/.dll
+IGNEX_FFI_PATH=$(pwd)/target/release/libignex_ffi.so bun run your-server.ts
+```
+
+The cdylib exports a **schema fingerprint** (`fb_schema_fingerprint`) that the
+bind-time self-test checks against `SCHEMA_FINGERPRINT` in your generated
+registry — a stale or schema-mismatched addon fails loudly instead of producing
+undecodable frames. (`ffiMode: "required"` makes a missing/mismatched addon a
+hard error.)
+
+## NATS & horizontal scaling
+
+Point every server instance at the same NATS and the same subject prefix, and
+they behave as one hub:
+
+- Every `publish` / `publishToTopic` / `publishToGroup` is ALSO published to
+  NATS as the identical wire frame (`{prefix}.broadcast.<event>`,
+  `{prefix}.topic.<topic>.<event>`, `{prefix}.group.<group>.<event>`) — any
+  backend (BE) service can consume them with the wire registry +
+  `backend.fbs`.
+- External producers (or BE services) publish on `{prefix}.inbound.>`; every
+  server forwards those events to its own clients.
+- With `nats.bridgeClientEvents: true`, events that a client sends to ONE
+  server are re-published to `{prefix}.inbound.<event>`, so all other servers'
+  clients receive them too — client messages become cluster-wide. Loop
+  prevention is built in: frames that arrive via NATS are forwarded to clients
+  but never re-bridged.
+
+```
+             ┌─────────────┐  publish("chat", …)   ┌─────────────┐
+ FE client ─▶│ server A    │──────▶ NATS ◀─────────│ server B    │◀─ FE client
+             │ ignex.*     │                        │ ignex.*     │
+             └─────────────┘                        └─────────────┘
+                     │  inbound.<event> (client-sent, bridgeClientEvents)
+                     └──────────────▶ BE consumers (any language)
+```
+
+Because the wire bytes are schema-derived, all instances must run the SAME
+generated bindings (same event names → same FNV-1a ids). Changing the schema
+changes the fingerprint — regenerate all instances together.
+
+## Independent (non-JS) consumers
+
+`wire-registry.json` maps event names → stable FNV-1a ids, and `backend.fbs`
+is the FlatBuffer layout — decode bridged NATS frames in any language. See
+`docs/wire-format.md` for the envelope.
+
+## What about the built-in events?
+
+The built-in registry (quote/trade/portfolio/…) is just the default
+`Bindings` (`defaultBindings`); every API accepts `bindings` and defaults to
+it, so existing code is untouched. Use the built-in events as a reference for
+schema style — your app's schema works exactly the same way.

package/docs/publishing.md

@@ -10,9 +10,9 @@ mirrors how the `@ignex/*` packages in the Ignex monorepo are shipped.
 | Field | Value | Why |
 | --- | --- | --- |
 | `main` / `module` / `types` | `./index.ts` | source entrypoint (Bun-native) |
-| `exports` | `.` → `index.ts`, `./server` → `public/server.ts`, `./client` → `public/client.ts`, `./nats` → `public/nats.ts`, `./package.json` | typed subpath API |
+| `exports` | `@ignex/nova` → `index.ts`; `@ignex/nova/server` → `public/server.ts`; `@ignex/nova/client` → `public/client.ts`; `@ignex/nova/nats` → `public/nats.ts`; `@ignex/nova/events` → `public/events.ts`; `@ignex/nova/bindings` → `public/bindings.ts`; `@ignex/nova/generate` → `public/generate.ts`; `@ignex/nova/internal` → `public/internal.ts`; `@ignex/nova/package.json` → `package.json` | typed subpath API |
 | `files` | `index.ts`, `public`, `src`, `rust`, `prebuilds`, `docs`, `README.md`, `LICENSE` | everything consumers need, nothing they don't |
-| `publishConfig` | `{ "access": "public" }` | unscoped package must be public |
+| `publishConfig` | `{ "access": "public" }` | scoped packages are restricted by default — `access: public` publishes `@ignex/nova` publicly |
 | `engines` | `{ "bun": ">=1.4" }` | Bun-only runtime |
 | `sideEffects` | `false` | safe to tree-shake / mark in bundlers |