@ignex/nova 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ignex-nova contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# ignex-nova
+
+TypeBox-driven **FlatBuffer transport over Bun WebSockets** with a Rust FFI
+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"] });
+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 }));
+
+// FE (browser or Bun)
+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.connect();
+```
+
+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).
+
+## Features
+
+- **Typed pub/sub, both directions** — `publish`/`publishTo`/`publishToTopic`
+  on the server, `on`/`send`/`subscribe` on the client. Control frames
+  (hello/subscribe/ping/…) ride the same codegen, routed internally.
+- **Rooms / topics** with optional **last-value replay** on subscribe
+  (`replay: { historySize }`).
+- **Backpressure** — configurable slow-consumer policy (drop-oldest /
+  drop-newest / disconnect) so a hot publish loop can't balloon memory.
+- **Auth & limits** — async `authenticate(req)` hook, origin allowlist, bearer
+  `token`, `maxConnections`, `maxMessageSize`, TLS passthrough.
+- **Resiliency** — auto-reconnect with exponential backoff + jitter,
+  auto-resubscribe, app-level heartbeat.
+- **Exact int64** — `Type.BigInt()` fields round-trip losslessly beyond 2^53;
+  optional `int64Guard` catches out-of-range numbers.
+- **Observability** — `server.getMetrics()` (counters + per-event encode path),
+  JSON `/health`, graceful `drain()`.
+- **Targeted delivery & groups** — every client has a stable id (from
+  `authenticate` metadata or an auto-UUID) so you can `publishToClient(id, …)`;
+  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`.
+- **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.
+- **Bun-only server, browser+Bun client.** Wire spec documented for independent
+  clients: [docs/wire-format.md](docs/wire-format.md).
+
+## How it works
+
+```
+src/schema/index.ts (TypeBox — source of truth: app events + control events)
+        │  scripts/generate.ts
+        ▼
+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)
+
+server:  JS object ─▶ (flat event) fields as direct FFI args ─▶ Rust
+                   └▶ (vector/nested) JSON.stringify → cstring ─▶ Rust
+browser: JS object ─▶ flatc object API (ts-ser) ─▶ size-prefixed FlatBuffer
+Rust + ts-ser both emit the same frame:
+  frame = [WIRE_VERSION:1][event_id:u32 LE][size-prefixed FlatBuffer]
+Bun: ws.send(frame) ──▶ peer: decode via generated classes → plain object
+```
+
+**Two server serialize paths** (neither uses JSON on the hot path):
+
+- **Direct fast path (zero-allocation)** — directable events: fields pushed
+  straight into generated `extern "C"` functions as FFI args, output written
+  into a single reusable scratch. Measured ~0 B/op.
+- **JSON fallback** — only for nested tables-in-tables / unions (e.g. `order`),
+  or payloads with embedded NULs. Observable via `getMetrics().pathCounts`.
+
+The **browser client** has no FFI, so outgoing frames (app + control) use the
+generated pure-JS encoder (flatc object API over a pooled builder).
+
+Key techniques (Bun 1.4 standard practices, following the castrum FFI guide):
+
+- strings as pre-encoded `(buffer, usize)` via `Buffer.write` into a cached view
+  (zero JS-side text encoding, zero allocation); vectors as packed binary blobs
+- `buffer` / `buffer_length` ABI pair for the output — the engine snapshots
+  pointer + byteLength off the same view at call time (the "peak"/pointer +
+  length pattern). `returns: 'u64_fast'` for byte counts.
+- `ws.send(Uint8Array)` copies synchronously (verified) → the shared output
+  scratch is safe to reuse immediately.
+- Rust `#[no_mangle] extern "C"` exports, `panic_guard`-wrapped, needed-size
+  convention, `thread_local` reused `FlatBufferBuilder` + `reset()` per call.
+- Bind-time self-test: `fb_probe` magic + `fb_wire_version` (stale-cdylib
+  guard) + a per-symbol direct self-test that DISABLES broken symbols
+  (graceful JSON fallback instead of a hard crash).
+- Stable event ids = FNV-1a 32-bit over the name (reorder-safe, collision-
+  checked at generate time).
+- `flatc` guarantees wire compatibility between the Rust builders and the
+  browser decoders (both derive from the same `.fbs`).
+
+## Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.4
+- Rust toolchain (`cargo`)
+- `flatc` (FlatBuffers compiler): `brew install flatbuffers`,
+  `apt install flatbuffers-compiler`, or from <https://flatbuffers.dev>.
+  Keep `flatc` and the `flatbuffers` crate/npm versions aligned.
+
+## Setup
+
+```bash
+bun install            # deps: @sinclair/typebox, flatbuffers
+bun run generate       # TypeBox → .fbs → flatc --ts/--rust → Rust glue + registry
+cargo build --release --manifest-path rust/Cargo.toml   # → <platform> libignex_ffi (.so/.dylib/.dll)
+bun run build:client   # bundle the browser demo → client-dist/
+bun test               # round-trip + FFI tests (needs generate + built addon)
+bun run lint           # oxlint — FP-discipline rules (no-var, no-param-reassign, …)
+bun run serve          # demo: http://localhost:3000/  (ws: /ws)
+```
+
+`bun run build` runs generate + build:rust + build:client together.
+`bun run build:dist` emits an npm-ready JS bundle + declarations to `dist/`.
+
+**Perf gate:** `bench/BASELINE.md` records the reference numbers. After any
+hot-path change run `bun run bench:serialize` + `bun run bench:throughput` and
+compare — fail-fast on >±5% drift in encode latency/throughput or any new
+allocations on the `quote` path (must stay ~0 B/op).
+
+## Install & use from npm
+
+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
+```
+
+```ts
+// server (Bun-only — needs the native addon, see below)
+import { createServer } from "ignex-nova/server";
+
+// client (browser + Bun) — the root entry also re-exports everything
+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() };
+```
+
+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` |
+
+**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
+# 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
+```
+
+See [docs/publishing.md](docs/publishing.md) for how the package is built,
+staged, and published to npm.
+
+## Layout
+
+| 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` |
+| `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` |
+| `src/core/` | functional modules: `server.ts`/`client.ts` composition roots, `state.ts`, `auth.ts`, `rooms.ts`, `groups.ts`, `replay.ts`, `backpressure.ts`, `outbound.ts`, `routing.ts`, `metrics.ts`, `int64-guard.ts`, client-* |
+| `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`) |
+| `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` |
+
+## 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.
+
+## Performance (min-of-N ns/op on this machine, `bun run bench:serialize`)
+
+| Payload | Rust FFI (zero-alloc) | Pure JS flatc | Rust vs JS |
+| --- | --- | --- | --- |
+| quote | **~190–270 ns** | ~500–740 ns | **~2–3× faster** |
+| portfolio (3 positions) | **~0.9–1.0 µs** | ~1.6 µs | **~1.5× faster** |
+| 200-position portfolio | **~26 µs** | ~64 µs | **~2.5× faster** |
+
+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**.
+
+## Server options (all optional)
+
+```ts
+createServer({
+  port: 3000,
+  path: "/ws",                      // websocket path
+  inbound: ["chat"],                // app events clients may SEND
+  backpressure: { highWaterMark: 1 << 20, policy: "drop-oldest", maxQueue: 256 },
+  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
+  maxConnections: 10_000,
+  maxMessageSize: 64 * 1024,
+  int64Guard: "warn",               // "off" | "throw" | "warn"
+  nats: { servers: ["nats://localhost:4222"], inbound: true }, // optional NATS bridge
+  tls: { keyFile, certFile },       // enables wss://
+});
+```
+
+## Client options (all optional)
+
+```ts
+createClient("ws://...", {
+  reconnect: { initialDelay: 250, maxDelay: 30_000, jitter: true }, // or true/false
+  heartbeatMs: 15_000, heartbeatMisses: 2,
+});
+```
+
+## Targeted sends, groups & NATS
+
+```ts
+// identity: authenticate() can pin the id + seed groups + attach metadata
+createServer({
+  port: 3000,
+  authenticate: async (req) => {
+    const user = await whoIs(req);             // e.g. from a JWT
+    return { id: user.id, groups: user.tier ? ["premium"] : [], meta: { name: user.name } };
+  },
+  nats: { servers: ["nats://localhost:4222"], inbound: true }, // optional bridge
+});
+
+// targeted sends / groups (server)
+server.publishToClient("user-42", "quote", {...});   // one client by id (not bridged)
+server.joinGroup("user-42", "eu");                   // server-side grouping
+server.publishToGroup("eu", "quote", {...});         // → ignex.group.eu.quote on NATS
+server.getClients();                                 // [{ id, groups, topics, meta, connectedAt, ip }]
+
+// clients can also join groups + learn their assigned id
+client.joinGroup("beta");
+client.leaveGroup("beta");
+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`.
+
+## Publishing to npm
+
+Publish directly from source — `bun publish` runs the release gate
+(`generate` → typecheck → lint → test) and `prepack` stages the native addon:
+
+```bash
+bun run release:dry    # plan only — print what would happen
+bun run release        # patch bump → verify → publish → commit/tag/push
+bun run release minor  # minor bump
+bun run release --version 0.2.0   # explicit version
+```
+
+CI (`.github/workflows/publish.yml`) builds `prebuilds/` for
+ubuntu/macos/macos-13, merges them, verifies, and publishes on a `v*` tag or
+`workflow_dispatch` with `NPM_TOKEN`. Full details: [docs/publishing.md](docs/publishing.md).
+
+## Notes / limits
+
+- The direct fast path covers flat types AND vectors of flat tables (packed
+  bridge). Events with nested tables-in-tables or unions fall back to JSON —
+  the path is observable via `server.getMetrics().pathCounts`.
+- Plain `number` int64 fields lose precision above ±2^53-1 — use `Type.BigInt()`
+  for exact fields, or enable `int64Guard`.
+- The output buffer is a single reusable scratch — the returned view is only
+  valid until the next `publish`; `publish` sends immediately (Bun copies), so
+  this is safe.
+- Event ids are stable FNV-1a hashes (not insertion order) — regenerate all
+  artifacts together.
+- The server is **Bun-only** (`bun:ffi`, `Bun.serve`); the client runs in
+  browser + Bun. Node server support is out of scope.
+- Full gap-based replay (per-frame sequence numbers) is a documented future
+  extension; today the server replays bounded per-topic history on subscribe.
+- Docs: [wire-format.md](docs/wire-format.md) (incl. building an independent
+  client), [architecture.md](docs/architecture.md). MIT licensed, CI on
+  ubuntu + macos.

package/docs/architecture.md

@@ -0,0 +1,146 @@
+# Architecture
+
+ignex-nova is a TypeBox-driven **FlatBuffer transport over Bun WebSockets** with
+a Rust FFI serializer — hidden behind a typed pub/sub API.
+
+## Pipeline
+
+```
+src/schema/index.ts (TypeBox — single source of truth: app events + control events)
+        │  scripts/generate.ts
+        ▼
+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)
+```
+
+## 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
+`src/core/`.
+
+- **Composition roots** (`src/core/server.ts`, `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
+  object with closures over it.
+- **Action modules** are pure-ish functions `(state, ...) => ...` that read/
+  mutate the explicit state: `auth` (upgrade gate), `rooms` (membership +
+  fan-out), `replay` (per-topic history), `backpressure` (pure `decide` → send/
+  enqueue/drop/close), `outbound` (the only place that touches `ws.send` and
+  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).
+  `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,
+  prefer-const, no-param-reassign `props:false`, prefer-arrow-callback,
+  no-else-return, consistent-return, no-nested-ternary, no-loop-func, …) runs
+  in CI after `tsc`. Perf is gated by `bench/BASELINE.md` — re-run
+  `bench:serialize` + `bench:throughput` before/after hot-path changes and
+  fail-fast on >±5% drift or new allocations.
+
+## Encode paths (server)
+
+- **Direct fast path (zero-alloc)** — directable events (flat types + packed
+  vectors) are pushed straight into Rust FFI args from a reusable scratch; the
+  output is written into a single reusable buffer. ~0 B/op.
+- **JSON fallback** — nested tables/unions (e.g. `order`) serialize through
+  `JSON.stringify → fb_serialize → serde_json`. Slower + allocating; the
+  per-event encode path is observable via `server.getMetrics().pathCounts`.
+- A payload containing an embedded NUL is routed to the JSON path (the
+  `cstring` direct path would silently truncate it).
+
+## Encode path (client / browser)
+
+Browsers have no Rust FFI, so outgoing frames (app events **and** control
+frames) are encoded by `generated/ts-ser.ts` — flatc's object API (`XxxT` +
+`pack`) over a pooled `flatbuffers.Builder`. No JSON.
+
+## 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).
+  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/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` —
+  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.
+- `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),
+  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).
+- `src/core/metrics.ts`, `src/core/int64-guard.ts` — `createMetrics()` factory
+  + the exact-int64 safety net.
+- `src/transport/{transport,scratch,stats}.ts` — object → frame encoding:
+  `encodeToScratch` (direct/JSON), the reusable zero-alloc scratch, and
+  encode-path stats.
+- `src/generated/` — flatc `--ts`/`--rust` output + `registry.ts` +
+  `direct-ser.ts` + `ts-ser.ts` + `wire-registry.json` (emitted; regenerated by
+  `bun run generate`).
+- `src/schema/index.ts` — TypeBox source of truth.
+- `src/native/*` — the only place that talks to Rust: `dlopen` binding with a
+  bind-time self-test (a failing direct symbol is disabled → JSON fallback),
+  `buffer`/`buffer_length` ABI probing, per-platform addon resolution.
+- `rust/` — a cdylib exporting `#[no_mangle] extern "C"` symbols, `panic_guard`-
+  wrapped, `thread_local` reused `FlatBufferBuilder`.
+
+## Client identity, targeting & the NATS bridge
+
+- **Identity**: `authenticate(req)` may return `{ id, groups, meta }`; otherwise
+  a UUID is assigned at upgrade (`auth.ts`). Ids are de-duplicated (409 at
+  upgrade, stale-session kick at open). `state.clients: Map<id, socket>` is the
+  live registry; the server sends the `welcome` control frame so each client
+  knows its id + server-side groups.
+- **Targeting**: `publishToClient(id, …)` (single socket, not bridged),
+  `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()`.
+
+## Why it's fast
+
+- Zero-alloc server encode (reusable scratch + Bun's synchronous `ws.send`
+  copy).
+- FlatBuffers = zero-parse reads, no JSON on the hot path.
+- flatc guarantees the Rust builders and TS decoders agree byte-for-byte.
+
+## Runtime & platform constraints
+
+- **Server is Bun-only** (`bun:ffi`, `Bun.serve`). Node is not supported.
+- The native addon is per-OS (`.so`/`.dylib`/`.dll`) — see
+  `src/native/loader.ts`. Build it with `cargo build --release`.
+- The **client** works in Bun AND browsers (bundle with
+  `bun build --target=browser`).
+
+## Known limits (documented, not hidden)
+
+- Plain `number` int64 fields lose precision above ±2^53-1 — use
+  `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.

package/docs/publishing.md

@@ -0,0 +1,119 @@
+# Publishing ignex-nova to npm
+
+ignex-nova is published **from source** — the tarball contains TypeScript
+entrypoints (Bun runs `.ts` natively, so consumers need no build step), the
+generated artifacts, the `rust/` source, and prebuilt native addons. This
+mirrors how the `@ignex/*` packages in the Ignex monorepo are shipped.
+
+## Package layout (`package.json`)
+
+| 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 |
+| `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 |
+| `engines` | `{ "bun": ">=1.4" }` | Bun-only runtime |
+| `sideEffects` | `false` | safe to tree-shake / mark in bundlers |
+
+`rust/.npmignore` keeps `rust/target/` (build output), `Cargo.lock` and the
+dev example out of the tarball while still shipping the Rust **source** so
+consumers can rebuild the addon on any platform.
+
+## The release pipeline
+
+```
+bun run release            ──►  bump version
+                                  │
+                                  ├─► verify     (typecheck + lint + test)
+                                  ├─► pack:check (tarball contents gate)
+                                  ├─► bun publish
+                                  │      ├─ prepublishOnly  → generate + verify
+                                  │      └─ prepack         → prebuild (stage addon)
+                                  └─► git commit + tag vX.Y.Z (+ push)
+```
+
+### 1. Version bump
+`scripts/release.ts` supports `patch | minor | major` (default `patch`) or an
+explicit `--version`. Prereleases finalize on the next bump
+(`0.2.0-beta.1` → `0.2.0`).
+
+### 2. Verify gate
+`bun run verify` = `typecheck` + `lint` + `test`. `prepublishOnly` first runs
+`generate` so the TypeBox → `.fbs` → flatc → glue artifacts are always fresh
+in the tarball (they're gitignored, so they must be regenerated at publish).
+
+### 3. Tarball check
+`bun run pack:check` runs `bun pm pack --dry-run --json` and asserts:
+
+- required files present: entrypoints, `src/`, `rust/Cargo.toml`, docs, README, LICENSE
+- nothing heavy/private leaks: `rust/target/`, `dist/`, `node_modules/`, `client-dist/`, tests, benches
+
+### 4. Native addon staging
+`prepack` runs `bun run prebuild` → `scripts/build-prebuild.ts`:
+
+```
+cargo build --release  →  rust/target/release/libignex_ffi.{so,dylib,dll}
+    cp →  prebuilds/<platform>-<arch>/libignex_ffi.{so,dylib,dll}
+```
+
+The loader (`src/native/loader.ts`) resolves the addon in this order:
+
+1. `IGNEX_FFI_PATH` env override
+2. in-repo dev build: `<repo>/rust/target/release/<lib>`
+3. packaged layout: `<pkg>/prebuilds/<platform>-<arch>/<lib>`
+
+So consumers on a platform with a shipped prebuild need **zero setup**; others
+rebuild from the shipped `rust/` source or set `IGNEX_FFI_PATH`.
+
+### 5. Publish
+`bun publish` (equivalent to `npm publish`) with `--tag <dist-tag>`
+(default `latest`) and `--access public`.
+
+## Releasing
+
+### Manual (from a checkout)
+
+```bash
+bun run release:dry                # plan only
+bun run release                    # patch bump → publish → commit + tag + push
+bun run release minor --tag beta   # minor + dist-tag `beta`
+bun run release --version 0.2.0 --no-verify --no-check
+bun run release --no-commit        # bump + publish, no git side effects
+bun run release --no-bump --no-verify --no-commit   # retry publish as-is
+```
+
+First release from a fresh checkout needs the generated artifacts + a built
+addon — `release` handles both via `prepublishOnly`/`prepack`, but you need a
+local Rust toolchain + `flatc` (see README "Prerequisites").
+
+### CI (`.github/workflows/publish.yml`)
+
+Triggered by a `v*` tag push or `workflow_dispatch` (with optional `version`
+and `dist_tag` inputs). It builds prebuilds for **ubuntu-latest**
+(linux-x64), **macos-latest** (darwin-arm64) and **macos-13** (darwin-x64),
+merges them into `prebuilds/`, sets the version from the tag/input, runs the
+full gate, then publishes.
+
+Set the `NPM_TOKEN` repo secret (an npm access token with publish rights) for
+the publish step. Provenance/attestations can be enabled by using
+`npm publish --provenance` and an `id-token: write` permission (the workflow
+already grants it).
+
+## Pre-publish checklist
+
+- [ ] `bun run verify` passes locally
+- [ ] `bun run pack:check` shows the expected files and no `rust/target/`
+- [ ] `prebuilds/` contains the addon(s) you intend to ship
+- [ ] npm auth works: `npm whoami`, and `NPM_TOKEN` is set for CI publishes
+- [ ] version is correct (`bun run release --version X.Y.Z`)
+
+## Tarball hygiene notes
+
+- `files` is an allowlist — only the listed top-level entries are packed.
+- Nested `rust/.npmignore` excludes `rust/target/` (platform-specific build
+  output, GB-scale) and `Cargo.lock` (library crates don't commit it).
+- `prebuilds/` is empty (or absent) until `prepack`/CI stages addons, so a
+  source-only tarball is fine too — the loader just falls back to rebuild/`IGNEX_FFI_PATH`.
+- The gitignored `src/generated/` artifacts ARE packed (they're under the
+  included `src/`) — that's intentional: consumers must not need `flatc`.