@ignex/nova 0.1.1 → 0.1.3

package/README.md

@@ -5,25 +5,59 @@ serializer — and a typed pub/sub API that hides all of it from developers.
 
 ```ts
 // server (Bun)
-import { createServer } from "ignex-nova/server";
-const server = createServer({ port: 3000, inbound: ["chat"] });
+import { createServer } from "@ignex/nova/server";
+const server = createServer({ port: 3000, inbound: ["trade"] });
 server.publish("quote", { symbol: "AAPL", bid: 180.1, ask: 180.2, bidSize: 100, askSize: 200, ts: Date.now() });
 server.publishToTopic("equities", "quote", {...});   // rooms
-server.on("chat", (msg, ws) => server.publishTo(ws, "chatAck", { ok: true }));
+server.on("trade", (msg, ws) =>
+  server.publishTo(ws, "quote", { symbol: msg.symbol, bid: msg.price, ask: msg.price, bidSize: 1, askSize: 1, ts: Date.now() }),
+);
 
 // FE (browser or Bun)
-import { createClient } from "ignex-nova/client";
+import { createClient } from "@ignex/nova/client";
 const client = createClient("ws://localhost:3000/ws", { reconnect: true });
 client.on("quote", (q) => console.log(q.symbol, q.bid)); // q is a plain typed object
 client.subscribe("equities");       // rooms + last-value replay
-client.send("chat", { text: "hi" }); // typed client→server (pure-JS encoder — works in the browser)
+client.send("trade", { symbol: "AAPL", price: 180.5, volume: 10, side: "buy", ts: Date.now() }); // typed client→server (pure-JS encoder — works in the browser)
 client.connect();
 ```
 
+> The built-in registry ships `quote`/`trade`/`portfolio`/`complex`/`order`/`bigVal` — custom events like `chat` require your own schema via `generateBindings` (see below).
+
 No `flatbuffers.Builder`, no `getRootAs*`, no FFI — developers only ever see
 plain, type-checked objects. The FlatBuffer + Rust machinery is internal, and
 the **browser can send typed frames too** (via a generated pure-JS encoder).
 
+## Bring your own schema (generic bindings)
+
+The transport is **schema-driven**: the built-in events (quote/trade/…) are
+just the default registry. Define **any** TypeBox schema in your app and
+`generateBindings(schema)` produces a complete, typed wire stack for it —
+same APIs, same NATS story, your events:
+
+```ts
+// scripts/generate-bindings.ts
+import { generateBindings } from "@ignex/nova/generate";
+import { schemas, events, controlEvents } from "../src/schema"; // YOUR TypeBox
+generateBindings({ schemas, events, controlEvents }, { outDir: "./ignex/generated" }).write();
+
+// bindings.ts
+import { makeBindings } from "./ignex/generated";
+import * as schema from "../src/schema";
+export const bindings = makeBindings(schema);
+
+// server.ts — publish/on typed against YOUR events; NATS bridging included
+const server = createServer({ port: 3000, bindings, inbound: ["chat"],
+  nats: { servers: ["nats://localhost:4222"], inbound: true, bridgeClientEvents: true } });
+server.publish("chat", { room: "lobby", text: "hi", ts: Date.now() });
+```
+
+The generated stack (flatc TS decoders + pure-JS encoder + direct fast-path
+serde + `wire-registry.json` for NATS consumers + an optional Rust crate for
+the FFI fast path) works without a Rust toolchain — the server falls back to
+the pure-JS encoder when no addon is present. Full guide:
+[docs/generic-bindings.md](docs/generic-bindings.md).
+
 ## Features
 
 - **Typed pub/sub, both directions** — `publish`/`publishTo`/`publishToTopic`
@@ -46,12 +80,30 @@ the **browser can send typed frames too** (via a generated pure-JS encoder).
   server-side groups (`publishToGroup(group, …)`, joined via auth metadata,
   `joinGroup(id, group)`, or client `joinGroup` frames) target sets of clients.
   Active clients are listed via `getClients()` / `GET /clients`.
+- **Generic, schema-driven** — `generateBindings(schema)` (from
+  `@ignex/nova/generate`) builds the whole wire stack for ANY TypeBox schema in
+  your app; `createServer` / `createClient` / `createNatsBridge` accept the
+  resulting `bindings` and are fully typed against your events. The built-in
+  events are just the default registry.
 - **NATS bridge (bidirectional)** — every broadcast/topic/group publish is also
   published to NATS as the **same FlatBuffer wire frame** (`ignex.broadcast.*`,
   `ignex.topic.*`, `ignex.group.*`) so other applications can consume it;
   external apps push events into the hub via `ignex.inbound.>` and the server
-  forwards them to clients. Best-effort (never blocks the WS hot path),
-  observable via metrics.
+  forwards them to clients. `bridgeClientEvents: true` re-publishes client-sent
+  events to the cluster (horizontal scaling). Best-effort (never blocks the WS
+  hot path), observable via metrics.
+- **Events layer** (`@ignex/nova/events`, opt-in via `createServer({ events })`)
+  — the application-facing event-driven system on top of the transport: an
+  **events file** receives events (`server.events.on(...)` with a context
+  carrying the sender's client record), a **global emit** sends events through
+  websockets from anywhere (`emit` / `emitToGroup` / `emitToUser` /
+  `emitToClient`), **client records** model "who is connected, on whose behalf
+  (`userId`), and what to remember per connection (`client.data`)", **client
+  groups vs user groups** make group-vs-user targeting explicit, and an
+  optional **cluster sync** (NATS and/or Redis, offloaded from hot paths)
+  delivers every emit to the target's clients across horizontally scaled
+  instances, with presence + shared-state indexes. See
+  [docs/events.md](docs/events.md).
 - **Bun-only server, browser+Bun client.** Wire spec documented for independent
   clients: [docs/wire-format.md](docs/wire-format.md).
 
@@ -63,10 +115,10 @@ src/schema/index.ts (TypeBox — source of truth: app events + control events)
         ▼
 backend.fbs ──flatc --ts──▶ src/generated/ts/          (decoders)
         └───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 (direct fast-path serde)
-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)
+src/codegen/rust-glue-gen.ts ─▶ rust/src/transcode/         (JSON glue + direct-args FFI)
+src/codegen/direct-gen.ts ────▶ src/generated/direct-ser.ts (direct fast-path serde)
+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)
 
 server:  JS object ─▶ (flat event) fields as direct FFI args ─▶ Rust
                    └▶ (vector/nested) JSON.stringify → cstring ─▶ Rust
@@ -140,15 +192,15 @@ Published as **TypeScript source** (no build step needed — Bun runs `.ts`
 natively), with subpath entrypoints. Works in any Bun ≥ 1.4 project:
 
 ```bash
-bun add ignex-nova
+bun add @ignex/nova
 ```
 
 ```ts
 // server (Bun-only — needs the native addon, see below)
-import { createServer } from "ignex-nova/server";
+import { createServer } from "@ignex/nova/server";
 
 // client (browser + Bun) — the root entry also re-exports everything
-import { createClient, type Events } from "ignex-nova/client";
+import { createClient, type Events } from "@ignex/nova/client";
 
 const q: Events["quote"] = { symbol: "AAPL", bid: 180.1, ask: 180.2, bidSize: 100, askSize: 200, ts: Date.now() };
 ```
@@ -157,17 +209,22 @@ Entrypoints:
 
 | Import | Resolves to |
 | --- | --- |
-| `ignex-nova` | `index.ts` — everything (server + client + nats + schema types) |
-| `ignex-nova/server` | `public/server.ts` — `createServer` (Bun-only) |
-| `ignex-nova/client` | `public/client.ts` — `createClient` (browser + Bun) |
-| `ignex-nova/nats` | `public/nats.ts` — standalone `createNatsBridge` |
+| `@ignex/nova` | `index.ts` — everything (server + client + nats + schema types + generic codegen) |
+| `@ignex/nova/server` | `public/server.ts` — `createServer` (Bun-only) |
+| `@ignex/nova/client` | `public/client.ts` — `createClient` (browser + Bun) |
+| `@ignex/nova/nats` | `public/nats.ts` — standalone `createNatsBridge` |
+| `@ignex/nova/events` | `public/events.ts` — events layer + global emit |
+| `@ignex/nova/generate` | `public/generate.ts` — `generateBindings` (ANY-schema codegen) |
+| `@ignex/nova/bindings` | `public/bindings.ts` — `assembleBindings` / `defaultBindings` + types |
+| `@ignex/nova/internal` | `public/internal.ts` — runtime helpers used by generated code |
+| `@ignex/nova/package.json` | `package.json` — version / metadata for tooling |
 
 **Native addon:** the tarball ships `rust/` source + `prebuilds/<platform>-<arch>/`
 for the platforms built at release (see CI). If your platform has a prebuild it
 just works. Otherwise either rebuild from the shipped source:
 
 ```bash
-cargo build --release --manifest-path node_modules/ignex-nova/rust/Cargo.toml
+cargo build --release --manifest-path node_modules/@ignex/nova/rust/Cargo.toml
 # loader finds it at <pkg>/rust/target/release/…
 # or point at any build explicitly:
 IGNEX_FFI_PATH=/abs/path/to/libignex_ffi.so bun run your-server.ts
@@ -180,9 +237,11 @@ staged, and published to npm.
 
 | Path | Role |
 | --- | --- |
-| `src/schema/index.ts` | TypeBox schemas + `events`/`controlEvents` registries (source of truth) |
-| `scripts/` | `generate.ts` orchestrator + `.fbs` / Rust-glue / registry / ts-ser emitters |
-| `src/generated/` | flatc `--ts`/`--rust` output + `registry.ts` + `direct-ser.ts` + `ts-ser.ts` |
+| `src/schema/index.ts` | built-in TypeBox schemas + `events`/`controlEvents` registries (source of truth for the DEFAULT registry) |
+| `src/bindings/` | the generic `Bindings` contract: `types.ts` (runtime wire-stack interface + `EventNameOf`/`EventsOf`), `assemble.ts`, `default.ts` (built-in bindings) |
+| `src/codegen/` | the schema→wire emitters (published — `@ignex/nova/generate` uses them at runtime) |
+| `scripts/` | dev tooling: `generate.ts` orchestrator, prebuild/pack/release helpers (not published) |
+| `src/generated/` | flatc `--ts`/`--rust` output + `registry.ts` + `direct-ser.ts` + `ts-ser.ts` (built-in schema) |
 | `rust/` | cdylib: `ffi.rs` (C-ABI), `transcode/generated.rs` (glue) |
 | `src/native/` | `bun:ffi` binding, self-tests, per-platform addon loader |
 | `src/transport/` | `transport.ts` (`encodeToScratch`), `scratch.ts` (reusable zero-alloc buffer), `stats.ts` |
@@ -190,21 +249,25 @@ staged, and published to npm.
 | `src/bridge/` | optional NATS bridge: `nats.ts` (injectable transport, eager non-blocking connect), `subjects.ts` (subject naming) |
 | `public/server.ts` | entrypoint shim: `createServer` (publish/rooms/groups/targeting/NATS/auth/backpressure/metrics/drain) |
 | `public/client.ts` | entrypoint shim: `createClient` (on/send/subscribe/joinGroup/reconnect/heartbeat/status) |
-| `public/nats.ts` | entrypoint shim: `createNatsBridge` standalone (`ignex-nova/nats`) |
+| `public/nats.ts` | entrypoint shim: `createNatsBridge` standalone (`@ignex/nova/nats`) |
 | `client/` | browser demo (built to `client-dist/`) |
 | `bench/` | serialize latency + end-to-end throughput (+ `BASELINE.md` perf gate) |
 | `examples/` | `nats-consumer.ts` — independent NATS consumer for bridged frames |
 | `prebuilds/` | staged native addons per platform (`<platform>-<arch>/`), built by `bun run prebuild` / CI |
-| `docs/` | `wire-format.md`, `architecture.md`, `publishing.md` |
+| `docs/` | `wire-format.md`, `architecture.md`, `publishing.md`, `events.md`, `generic-bindings.md` |
 
 ## Adding an event
 
-1. Define the payload in `schema/index.ts` (TypeBox), add it to `schemas`
-   (if it's a named table) and to `events` (name → schema). For exact integer
-   values use `Type.BigInt()`.
-2. Re-run `bun run generate`, `cargo build --release`, `bun run build:client`.
-3. `server.publish("yourEvent", payload)`, `client.on("yourEvent", cb)`, and
-   `client.send("yourEvent", payload)` are now fully typed on both sides.
+**Built-in registry:** 1. Define the payload in `schema/index.ts` (TypeBox), add
+it to `schemas` (if it's a named table) and to `events` (name → schema). For
+exact integer values use `Type.BigInt()`. 2. Re-run `bun run generate`,
+`cargo build --release`, `bun run build:client`. 3.
+`server.publish("yourEvent", payload)`, `client.on("yourEvent", cb)`, and
+`client.send("yourEvent", payload)` are now fully typed on both sides.
+
+**Your own registry:** you don't edit this repo at all — define the schema in
+your app and run `generateBindings` (see
+[docs/generic-bindings.md](docs/generic-bindings.md)).
 
 ## Performance (min-of-N ns/op on this machine, `bun run bench:serialize`)
 
@@ -216,7 +279,7 @@ staged, and published to npm.
 
 Directable events serialize with **~0 B/op** (reusable scratch, no per-call
 allocations, no JSON). End-to-end over a real WebSocket (`bench:throughput`):
-**~1.18M msg/s**.
+**~1.09M msg/s** — see `bench/BASELINE.md` for the perf gate.
 
 ## Server options (all optional)
 
@@ -275,6 +338,43 @@ client.onStatus(() => console.log("my id:", client.clientId));
 NATS consumers (any language) decode bridged frames from
 `src/generated/fbs/backend.fbs` + the FNV-1a id map in `src/generated/wire-registry.json`
 — see [docs/wire-format.md](docs/wire-format.md) and `examples/nats-consumer.ts`.
+For your OWN schema, `generateBindings` emits the same `backend.fbs` +
+`wire-registry.json` into your project — see
+[docs/generic-bindings.md](docs/generic-bindings.md).
+
+## Events layer (the event-driven system)
+
+```ts
+import { createServer } from "@ignex/nova/server";
+import { on, emit, emitToUser } from "@ignex/nova/events"; // global singleton
+
+const server = createServer({
+  port: 3000,
+  events: {
+    onConnect: (client) => client.data.set("since", client.connectedAt),
+    cluster: { nats: true },           // optional: cross-instance sync
+  },
+});
+
+// the events file — receive events (ctx carries the sender's client record)
+on("chat.message", (payload, ctx) => {
+  emitToUser(payload.to, "chat.delivered", { id: payload.id });
+});
+
+// the global emit — send events through websockets from anywhere
+emit("quote", { symbol: "AAPL", bid: 180.1, ask: 180.2 });          // broadcast
+emitToUser("u-42", "order.update", { orderId: "o-1" });             // a user's sockets
+emit("alert", { text: "halt" }, { type: "group", group: "traders" }); // to a group
+
+// client records: id / userId (on whose behalf) / data / groups
+server.events.client("c-1")?.data.set("tier", "gold");
+server.events.clientsByUser("u-42");   // every device of u-42
+server.events.userGroup("ops").add("u-42").emit("pager", { text: "…" });
+```
+
+Full API, cluster semantics, presence, shared-state (Redis) indexes and
+performance notes: **[docs/events.md](docs/events.md)**. The events layer is
+opt-in — without `events`, there is zero overhead.
 
 ## Publishing to npm
 
@@ -283,7 +383,7 @@ Publish directly from source — `bun publish` runs the release gate
 
 ```bash
 bun run release:dry    # plan only — print what would happen
-bun run release        # patch bump → verify → publish → commit/tag/push
+bun run release        # patch bump → verify → publish → commit + tag (push only with `--push`)
 bun run release minor  # minor bump
 bun run release --version 0.2.0   # explicit version
 ```

package/docs/ai/LOCAL_DEV.md

@@ -0,0 +1,81 @@
+# Local Development with the Core Projects — `bun link`
+
+> **Scope**: maintainers and AI agents working across the IgnEX core stack.
+> Application developers consume published versions from npm and do **not**
+> need this file.
+
+## Why
+
+The IgnEX core packages live side-by-side, one directory back from this repo,
+in `/home/adeel/poc/`. When a change in this repo must be tested against the
+local source of a core project (or a core change must be tested against this
+repo), use `bun link` so the consumer resolves the local directory instead of
+the npm registry. This is the supported Bun ≥ 1.4 (Rust-based runtime)
+local-development mechanism
+([`bun link` docs](https://bun.com/docs/cli/link),
+[bun.com/blog/bun-v1.4](https://bun.com/blog/bun-v1.4)).
+
+This workflow is **only for maintainers and AI agents working with the core
+projects**. CI and release pipelines always resolve from the registry; local
+links are a development-only convenience.
+
+## Core packages (one directory back)
+
+| Repo (`/home/adeel/poc/`) | Package(s) | `bun link` name |
+| --- | --- | --- |
+| `ignus` — ignex monorepo, workspaces `packages/*` | `@ignex/core`, `@ignex/cli`, `@ignex/compiler`, `@ignex/native`, `@ignex/shared`, `@ignex/mcp`, `@ignex/app`, `create-ignex` | run `bun link` inside each package dir |
+| `bun-rust-runtime-bench` | `castrum` (Rust addon `castrum.<platform>-<arch>.node`) | `castrum` |
+| `ignex-mongodb` | `@ignex/ninox` | `@ignex/ninox` |
+| `ignex-nova` | `@ignex/nova` | `@ignex/nova` |
+
+Known cross-repo edges (verify with `grep` in `package.json` before assuming):
+
+- `@ignex/native` (in `ignus/packages/native`) depends on `castrum` — link
+  `castrum` there when changing the addon wire (`createNativeRoute`).
+- `@ignex/core` (in `ignus/packages/core`) optionally depends on
+  `@ignex/nova`; `@ignex/app` depends on `@ignex/core`, `@ignex/cli`, and
+  `@ignex/ninox`.
+
+## How to link
+
+```bash
+# 1. Register the core package (once per machine, from the core repo):
+cd /home/adeel/poc/ignex-mongodb
+bun link            # → Success! Registered "@ignex/ninox"
+
+# 2. Link it into the consumer project:
+cd /home/adeel/poc/ignex-app
+bun link @ignex/ninox              # symlinks node_modules/@ignex/ninox → ../ignex-mongodb
+bun link @ignex/ninox --save       # also writes "link:@ignex/ninox" into package.json deps
+```
+
+- `bun link` (no args) in a package directory registers that package globally
+  for this user.
+- `bun link <name>` in a consumer creates a symlink in the consumer's
+  `node_modules` pointing at the registered directory. `--save` additionally
+  records `"<name>": "link:<name>"` in `package.json` dependencies.
+- Unregister a package: `bun unlink` from the core repo dir.
+- Return to registry versions: remove the `link:` entry (or `bun unlink
+  <name>` in the consumer) and `bun install`.
+
+## Rust-core caveats (castrum & @ignex/nova)
+
+Both `castrum` and `@ignex/nova` ship a Rust cdylib. After changing Rust
+source, rebuild the addon **before** linking or using:
+
+- `castrum`: `bun run build` (release `napi build`) or `bun run build:debug`.
+  Under Bun the addon is also called through `bun:ffi` from the same cdylib.
+- `@ignex/nova`: `bun run build:rust`
+  (`cargo build --release --manifest-path rust/Cargo.toml`), or rely on
+  `prepack`/`prebuild` to stage `prebuilds/<platform>-<arch>/`.
+
+A stale `.node`/`.so` silently serves old behavior — rebuild, then re-test.
+`@ignex/nova` additionally fails its bind-time self-test on schema/wire-version
+mismatch (`IGNEX_FFI_PATH` can point at a specific build); `castrum` falls back
+to the napi transport when the `bun:ffi` self-test fails.
+
+## Never publish from a linked tree
+
+Publishing a consumer whose dependencies are `link:` entries ships symlinks,
+not packages. Releases always run against registry versions (`prepublishOnly` /
+CI re-verify with a clean install). Keep `bun link` strictly local.

package/docs/ai/TREE.md

@@ -0,0 +1,232 @@
+# TREE — generated scaffolding map
+
+> AUTO-GENERATED by `bun run gen:ai-map` (`scripts/gen-ai-map.ts`).
+> Do not edit by hand — regenerate after structural changes. The
+> curated maps live in `docs/architecture.md` + `docs/wire-format.md`
+> (and `AGENTS.md` for agents).
+
+- package: `@ignex/nova` v0.1.1
+- 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`, …
+
+## src/
+
+```
+src/
+├─ bindings/
+│  ├─ assemble.ts
+│  ├─ default.ts
+│  └─ types.ts
+├─ bridge/
+│  ├─ nats.ts
+│  └─ subjects.ts
+├─ codegen/
+│  ├─ constants.ts
+│  ├─ direct-gen.ts
+│  ├─ fingerprint.ts
+│  ├─ hash.ts
+│  ├─ registry-gen.ts
+│  ├─ rust-glue-gen.ts
+│  ├─ schema-model.ts
+│  ├─ ts-ser-gen.ts
+│  └─ typebox-to-fbs.ts
+├─ core/
+│  ├─ auth.ts
+│  ├─ backpressure.ts
+│  ├─ client-heartbeat.ts
+│  ├─ client-reconnect.ts
+│  ├─ client-state.ts
+│  ├─ client-wire.ts
+│  ├─ client.ts
+│  ├─ groups.ts
+│  ├─ int64-guard.ts
+│  ├─ metrics.ts
+│  ├─ outbound.ts
+│  ├─ replay.ts
+│  ├─ ring.ts
+│  ├─ rooms.ts
+│  ├─ routing.ts
+│  ├─ server.ts
+│  └─ state.ts
+├─ events/
+│  ├─ clients.ts
+│  ├─ cluster.ts
+│  ├─ data.ts
+│  ├─ emit.ts
+│  ├─ global.ts
+│  ├─ groups.ts
+│  ├─ hub.ts
+│  ├─ index.ts
+│  ├─ queue.ts
+│  ├─ registry.ts
+│  └─ types.ts
+├─ generated/
+│  ├─ fbs/
+│  │  └─ backend.fbs
+│  ├─ rust/
+│  │  └─ backend_generated.rs
+│  ├─ ts/
+│  │  ├─ backend.ts
+│  │  ├─ big-val.ts
+│  │  ├─ complex.ts
+│  │  ├─ customer.ts
+│  │  ├─ hello.ts
+│  │  ├─ join-group.ts
+│  │  ├─ leave-group.ts
+│  │  ├─ order-billing.ts
+│  │  ├─ order-line.ts
+│  │  ├─ order.ts
+│  │  ├─ ping.ts
+│  │  ├─ pong.ts
+│  │  ├─ portfolio-position.ts
+│  │  ├─ portfolio-snapshot.ts
+│  │  ├─ quote.ts
+│  │  ├─ side.ts
+│  │  ├─ snapshot-request.ts
+│  │  ├─ subscribe.ts
+│  │  ├─ tags.ts
+│  │  ├─ trade.ts
+│  │  ├─ unsubscribe.ts
+│  │  └─ welcome.ts
+│  ├─ direct-ser.ts
+│  ├─ registry.ts
+│  ├─ ts-ser.ts
+│  └─ wire-registry.json
+├─ native/
+│  ├─ codec.ts
+│  ├─ ffi.ts
+│  └─ loader.ts
+├─ schema/
+│  └─ index.ts
+├─ transport/
+│  ├─ byte-buffer-pool.ts
+│  ├─ scratch.ts
+│  ├─ stats.ts
+│  └─ transport.ts
+└─ server.ts
+```
+
+## rust/
+
+```
+rust/
+├─ examples/
+│  └─ dump.rs
+├─ src/
+│  ├─ generated/
+│  │  ├─ backend.rs
+│  │  └─ mod.rs
+│  ├─ transcode/
+│  │  ├─ generated.rs
+│  │  └─ mod.rs
+│  ├─ ffi.rs
+│  └─ lib.rs
+├─ .npmignore
+├─ Cargo.lock
+└─ Cargo.toml
+```
+
+## public/
+
+```
+public/
+├─ bindings.ts
+├─ client.ts
+├─ events.ts
+├─ generate.ts
+├─ internal.ts
+├─ nats.ts
+└─ server.ts
+```
+
+## client/
+
+```
+client/
+├─ index.html
+└─ main.ts
+```
+
+## test/
+
+```
+test/
+├─ api.test.ts
+├─ auth.test.ts
+├─ backpressure.test.ts
+├─ bidirectional.test.ts
+├─ bindings-gen.test.ts
+├─ byte-buffer-pool.test.ts
+├─ direct.test.ts
+├─ e2e.test.ts
+├─ events-cluster.test.ts
+├─ events.test.ts
+├─ ffi.test.ts
+├─ groups.test.ts
+├─ helpers.ts
+├─ int64.test.ts
+├─ integrity.test.ts
+├─ loader.test.ts
+├─ metrics.test.ts
+├─ nats-bridge.test.ts
+├─ nats-integration.test.ts
+├─ reconnect.test.ts
+├─ ring.test.ts
+├─ rooms.test.ts
+├─ roundtrip.test.ts
+├─ security.test.ts
+├─ targeting.test.ts
+└─ wire.test.ts
+```
+
+## bench/
+
+```
+bench/
+├─ BASELINE.md
+├─ ffi-margin.ts
+├─ measure.ts
+├─ serialize.ts
+└─ throughput.ts
+```
+
+## scripts/
+
+```
+scripts/
+├─ build-prebuild.ts
+├─ check-pack.ts
+├─ gen-ai-map.ts
+├─ generate.ts
+└─ release.ts
+```
+
+## examples/
+
+```
+examples/
+├─ consumer.ts
+├─ events.ts
+├─ generic-schema.ts
+└─ nats-consumer.ts
+```
+
+## docs/
+
+```
+docs/
+├─ ai/
+│  ├─ LOCAL_DEV.md
+│  └─ TREE.md
+├─ architecture.md
+├─ events.md
+├─ generic-bindings.md
+├─ publishing.md
+└─ wire-format.md
+```
+
+## Notes
+
+- `SKIP` set in the script excludes build output (target/, dist/, client-dist/, prebuilds/, node_modules/).
+- `src/generated/`, `rust/src/generated/`, `rust/src/transcode/generated.rs` are regenerated by `bun run generate` — never hand-edit.

package/docs/architecture.md

@@ -5,25 +5,37 @@ 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
@@ -68,7 +80,7 @@ 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,
@@ -88,9 +100,22 @@ frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
   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.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
+  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.