@ignex/nova 0.1.1 → 0.1.5

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)
 
@@ -229,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://
@@ -275,6 +341,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 +386,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,292 @@
+# 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.3
+- engines: {"bun":">=1.4"}
+- rust crate: `ignex-nova-ffi` v0.1.0
+- scripts (20): `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/
+│  │  ├─ inbound.ts
+│  │  ├─ index.ts
+│  │  ├─ real-transport.ts
+│  │  └─ types.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/
+│  ├─ 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
+│  ├─ groups.ts
+│  ├─ int64-guard.ts
+│  ├─ metrics.ts
+│  ├─ outbound.ts
+│  ├─ rate-limit.ts
+│  ├─ replay.ts
+│  ├─ resume.ts
+│  ├─ ring.ts
+│  ├─ rooms.ts
+│  ├─ routing.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-rpc.ts
+│  ├─ data.ts
+│  ├─ delivery.ts
+│  ├─ emit.ts
+│  ├─ global.ts
+│  ├─ groups.ts
+│  ├─ index.ts
+│  ├─ queue.ts
+│  ├─ registry.ts
+│  ├─ schedule.ts
+│  └─ trace.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
+│  │  ├─ resume.ts
+│  │  ├─ resumed.ts
+│  │  ├─ rpc-call.ts
+│  │  ├─ rpc-result.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
+│  └─ 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
+├─ 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
+├─ 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
+├─ 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
+```
+
+## bench/
+
+```
+bench/
+├─ BASELINE.md
+├─ dispatch.ts
+├─ 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.