@ignex/nova 0.1.1

package/src/native/ffi.ts

@@ -0,0 +1,214 @@
+/**
+ * `bun:ffi` binding to the Rust cdylib — the ONLY place that talks to native.
+ *
+ * Bun 1.4 standard practices (per the castrum FFI guide):
+ *   - `dlopen` once, bind lazily, never `close()` (dlclose-on-GC is unsound)
+ *   - `buffer`/`buffer_length` ABI pair → the engine reads ptr + byteLength off
+ *     the SAME view at call time (atomic snapshot) — the "peak"/pointer + length
+ *     pattern. Call sites pass the view twice.
+ *   - `cstring` arg → the engine transcodes the JS string to a NUL-terminated
+ *     UTF-8 buffer (zero JS-side encoding).
+ *   - `u64_fast` return → byte counts surface as plain `number`, not BigInt.
+ *   - bind-time self-test (`fb_probe` + a JSON `fb_serialize` frame + every
+ *     direct symbol via the generated `directSelfTest`); a failing direct
+ *     symbol is DISABLED and its event falls back to the JSON path (graceful
+ *     degradation instead of a hard throw).
+ *   - `probeBufferLength()` at bind: if the Bun build rejects the
+ *     `buffer`/`buffer_length` pair, fall back to explicit `(ptr, usize)`
+ *     output pairs. The `abi()` transformer keeps the shipped specs canonical
+ *     (`(ptr, usize)` outputs) and upgrades them at bind time.
+ */
+import { dlopen, type FFITypeOrString } from "bun:ffi";
+import { directSelfTest, directSymbols } from "../generated/direct-ser";
+import { eventNameToId, WIRE_HEADER_LEN, WIRE_VERSION } from "../generated/registry";
+import type { EventName } from "../schema";
+import { getAddonPath } from "./loader";
+
+export const FB_PROBE_MAGIC = 0x4947_4e58; // "IGNX"
+
+export interface BunFfi {
+  /** (eventId, JSON string, out view) → bytes written; 0 = error; >cap = needed */
+  fb_serialize(eventId: number, json: string, out: Uint8Array): number;
+  fb_probe(): number;
+  /** Wire-format version of the cdylib (must equal generated WIRE_VERSION). */
+  fb_wire_version(): number;
+}
+
+/** Output-buffer ABI mode of the live binding (set once by `bind()`). */
+export type BufferAbiMode = "buffer-pair" | "ptr-len";
+
+interface Dl {
+  bindings: BunFfi;
+  /** every bound symbol, callable with raw args (…fieldArgs, out, out) */
+  raw: Record<string, (...args: unknown[]) => number>;
+  /** direct symbols disabled by the bind-time self-test (fall back to JSON). */
+  disabledDirect: Set<string>;
+  bufferAbiMode: BufferAbiMode;
+}
+
+let cachedDl: Dl | null | undefined;
+let bufferAbiMode: BufferAbiMode = "ptr-len";
+
+const U64_FAST = "u64_fast" as unknown as FFITypeOrString;
+
+/**
+ * Probe whether this Bun build accepts the `buffer`/`buffer_length` ABI pair in
+ * `dlopen`. Uses the diagnostic `ffi_probe_echo_view` symbol (bench-only, NOT in
+ * the shipped surface) bound with the pair and called with the same view twice —
+ * the engine reads ptr + byteLength off that object at call time. An older Bun
+ * canary threw "invalid ABI type" for `buffer_length`; on any failure we keep
+ * explicit `(ptr, usize)` pairs (castrum rule: never hardcode the pair).
+ */
+function probeBufferLength(path: string): boolean {
+  // Test hook: force the `(ptr, usize)` fallback to validate the degraded path.
+  if (process.env.IGNEX_FFI_FORCE_PTR_LEN === "1") return false;
+  try {
+    const { symbols } = dlopen(path, {
+      ffi_probe_echo_view: {
+        args: ["buffer", "buffer_length"] as unknown as readonly FFITypeOrString[],
+        // `u64_fast` returns a plain `number` (not a BigInt) for small values.
+        returns: U64_FAST,
+      },
+    });
+    const fn = (symbols as unknown as Record<string, (a: unknown, b: unknown) => unknown>).ffi_probe_echo_view;
+    const view = new Uint8Array([1, 2, 3]);
+    const out = fn?.(view, view);
+    return typeof out === "number" && out >= 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Positional pair-aware `(ptr, usize)` → `(buffer, buffer_length)` upgrade.
+ * Each `ptr` consumes its following `usize` as a length; scalar `usize` args
+ * that happen to appear (future opaque handles) pass through unchanged.
+ * Applied to canonical specs at bind time; a `buffer`/`usize` INPUT pair is
+ * left untouched (explicit JS length — no atomic-snapshot need).
+ */
+const abi = (shape: readonly string[]): readonly FFITypeOrString[] => {
+  if (bufferAbiMode !== "buffer-pair") return shape as readonly FFITypeOrString[];
+  const out: FFITypeOrString[] = [];
+  for (let i = 0; i < shape.length; i++) {
+    const t = shape[i];
+    if (t === "ptr") {
+      out.push("buffer" as unknown as FFITypeOrString);
+      out.push("buffer_length" as unknown as FFITypeOrString);
+      i++; // consume the paired `usize`
+    } else {
+      out.push(t as FFITypeOrString);
+    }
+  }
+  return out;
+};
+
+/**
+ * Mode-aware wrapper for symbols whose LAST TWO args are the output view passed
+ * twice (`…, out, out`). In `ptr-len` mode the trailing `out` becomes
+ * `out.byteLength` so the explicit `(ptr, usize)` spec receives a length number.
+ */
+function adaptOut(sym: (...a: unknown[]) => number, mode: BufferAbiMode): (...a: unknown[]) => number {
+  if (mode !== "ptr-len") return sym;
+  return (...args: unknown[]) => {
+    if (args.length === 0) return sym(...args); // fb_probe: no output pair
+    const out = args[args.length - 1] as Uint8Array;
+    args[args.length - 1] = out.byteLength;
+    return sym(...args);
+  };
+}
+
+function bind(): Dl {
+  const path = getAddonPath();
+
+  // Probe the atomic `buffer`/`buffer_length` pair once; fall back to explicit
+  // `(ptr, usize)` output pairs when the Bun build rejects it.
+  bufferAbiMode = probeBufferLength(path) ? "buffer-pair" : "ptr-len";
+
+  // Build the dlopen map from CANONICAL specs, upgrading `ptr` outputs to the
+  // `buffer`/`buffer_length` pair when supported.
+  const specMap: Record<string, { args: readonly FFITypeOrString[]; returns: FFITypeOrString }> = {
+    fb_serialize: { args: abi(["u32", "cstring", "ptr", "usize"]), returns: U64_FAST },
+    fb_probe: { args: [], returns: "u32" },
+    fb_wire_version: { args: [], returns: "u32" },
+  };
+  for (const [name, spec] of Object.entries(directSymbols)) {
+    specMap[name] = { args: abi(spec.args), returns: spec.returns as FFITypeOrString };
+  }
+
+  const { symbols } = dlopen(path, specMap as unknown as Parameters<typeof dlopen>[1]);
+
+  // Adapt every bound symbol so call sites always pass `(…, out, out)`.
+  const raw: Record<string, (...args: unknown[]) => number> = {};
+  for (const [name, sym] of Object.entries(symbols as unknown as Record<string, (...args: unknown[]) => number>)) {
+    raw[name] = adaptOut(sym, bufferAbiMode);
+  }
+
+  const bindings: BunFfi = {
+    fb_serialize: (eventId, json, out) => raw["fb_serialize"]!(eventId, json, out, out) as number,
+    fb_probe: () => raw["fb_probe"]!() as number,
+    fb_wire_version: () => raw["fb_wire_version"]!() as number,
+  };
+
+  // ── Bind-time self-tests ─────────────────────────────────────────────
+  if (bindings.fb_probe() !== FB_PROBE_MAGIC) {
+    throw new Error(`ignex: FFI self-test failed (fb_probe mismatch) — addon at ${path}`);
+  }
+  // Wire-version drift check: a stale cdylib (built from an older schema /
+  // envelope) must fail loudly at bind instead of producing undecodable frames.
+  if (bindings.fb_wire_version() !== WIRE_VERSION) {
+    throw new Error(
+      `ignex: FFI self-test failed (wire version ${bindings.fb_wire_version()} !== ${WIRE_VERSION}) — addon at ${path}; regenerate + rebuild`,
+    );
+  }
+  // JSON path sanity: `{}` → default frame for the FIRST event; verify the
+  // frame invariant `out[0]` = WIRE_VERSION, `out[1..5]` = event id AND
+  // `bytes_written === WIRE_HEADER_LEN + 4 + size_prefix`.
+  const firstEvent = Object.keys(eventNameToId)[0] as EventName;
+  const firstId = eventNameToId[firstEvent];
+  const scratch = new Uint8Array(2048);
+  const jw = bindings.fb_serialize(firstId, "{}", scratch);
+  if (jw === 0 || jw > scratch.byteLength) {
+    throw new Error(`ignex: FFI self-test failed (fb_serialize JSON) — addon at ${path}`);
+  }
+  {
+    const dv = new DataView(scratch.buffer, scratch.byteOffset, scratch.byteLength);
+    const size = dv.getUint32(scratch.byteOffset + WIRE_HEADER_LEN, true);
+    const gotId = dv.getUint32(scratch.byteOffset + 1, true);
+    if (scratch[0] !== WIRE_VERSION || gotId !== firstId || jw !== WIRE_HEADER_LEN + 4 + size) {
+      throw new Error(`ignex: FFI self-test failed (fb_serialize frame invariant) — addon at ${path}`);
+    }
+  }
+  // Direct fast-path: probe every generated symbol; disable the failures so
+  // their events gracefully fall back to the JSON path.
+  const disabledDirect = new Set(directSelfTest(raw, new Uint8Array(2048)));
+
+  return { bindings, raw, disabledDirect, bufferAbiMode };
+}
+
+function ensure(): Dl {
+  if (cachedDl === undefined) cachedDl = bind();
+  return cachedDl as Dl;
+}
+
+/** Lazily bind once. Throws if the addon is missing or the self-test fails. */
+export function getFfi(): BunFfi {
+  return ensure().bindings;
+}
+
+/** Output-buffer ABI mode of the live binding (lazy — triggers bind). */
+export function getBufferAbiMode(): BufferAbiMode {
+  return ensure().bufferAbiMode;
+}
+
+/**
+ * Direct fast-path symbol. Call it with `(…fieldArgs, outView, outView)` →
+ * bytes written (0 = error, >cap = needed). Returns undefined if the symbol is
+ * disabled by the bind-time self-test (its event falls back to the JSON path).
+ */
+export function getDirectSymbol(name: string): ((...args: unknown[]) => number) | undefined {
+  const dl = ensure();
+  if (dl.disabledDirect.has(name)) return undefined;
+  const symbol = dl.raw[name];
+  if (!symbol) throw new Error(`ignex: unknown direct symbol "${name}"`);
+  return symbol;
+}

package/src/native/loader.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Resolve the Rust cdylib path for the CURRENT platform/arch.
+ *
+ * Previously hardcoded to `rust/target/release/libignex_ffi.so` (Linux-only).
+ * Now maps `process.platform` → the correct library name (.so / .dylib / .dll)
+ * and searches, in order:
+ *   1. `IGNEX_FFI_PATH` env override (absolute path to the addon)
+ *   2. the in-repo dev build:  `<repo>/rust/target/release/<lib>`
+ *   3. the packaged npm layout: `<pkg>/prebuilds/<platform>-<arch>/<lib>`
+ *
+ * Bun is the only supported runtime; the addon must be built per-OS (see
+ * README). A clear error listing every candidate is thrown when missing.
+ */
+const LIB_NAMES: Record<string, string> = {
+  linux: "libignex_ffi.so",
+  darwin: "libignex_ffi.dylib",
+  win32: "ignex_ffi.dll",
+};
+
+/** The cdylib filename for a platform (used for tests + build tooling). */
+export function addonFilename(platform: string = process.platform): string {
+  const name = LIB_NAMES[platform];
+  if (!name) throw new Error(`ignex: unsupported platform "${platform}"`);
+  return name;
+}
+
+const here = import.meta.dir;
+
+/** Candidate addon paths in priority order (first existing wins). */
+export function addonCandidates(): string[] {
+  const file = addonFilename();
+  const tag = `${process.platform}-${process.arch}`;
+  return [
+    // in-repo dev build (repo root = src/native/../../)
+    join(here, "..", "..", "rust", "target", "release", file),
+    // packaged npm layout: <pkg-root>/prebuilds/<platform>-<arch>/<lib>
+    join(here, "..", "prebuilds", tag, file),
+    join(here, "..", "..", "prebuilds", tag, file),
+  ];
+}
+
+export function getAddonPath(): string {
+  const override = process.env.IGNEX_FFI_PATH;
+  if (override) return override;
+  for (const p of addonCandidates()) {
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    `ignex: native addon not found. Tried:\n  ${addonCandidates().join("\n  ")}\n` +
+      `Build it: cargo build --release --manifest-path rust/Cargo.toml  (or set IGNEX_FFI_PATH)`,
+  );
+}

package/src/schema/index.ts

@@ -0,0 +1,217 @@
+/**
+ * TypeBox schema — the SINGLE SOURCE OF TRUTH for the wire format.
+ *
+ * Everything else is generated from here:
+ *   - `scripts/generate.ts` → backend.fbs → flatc --ts (browser decoders) +
+ *     Rust glue (`rust/src/transcode/generated.rs`) + `src/generated/registry.ts`.
+ *
+ * The `events` registry defines the pub/sub event surface. Each event maps to
+ * a TypeBox schema; `Events[K]` is the plain-object type devs see on both the
+ * server (publish) and the FE (on) — no FlatBuffer API anywhere in sight.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+
+// ── Enums (union of string literals → FlatBuffer enum) ───────────────
+export const Side = Type.Union([Type.Literal("buy"), Type.Literal("sell")]);
+
+// ── Realtime market-data payloads ─────────────────────────────────────
+export const Trade = Type.Object(
+  {
+    symbol: Type.String(),
+    price: Type.Number(), // double
+    volume: Type.Integer(), // int64
+    side: Side, // enum
+    ts: Type.Integer(), // int64
+  },
+  { additionalProperties: false },
+);
+
+export const Quote = Type.Object(
+  {
+    symbol: Type.String(),
+    bid: Type.Number(),
+    ask: Type.Number(),
+    bidSize: Type.Integer(),
+    askSize: Type.Integer(),
+    ts: Type.Integer(),
+  },
+  { additionalProperties: false },
+);
+
+export const PortfolioPosition = Type.Object(
+  {
+    symbol: Type.String(),
+    quantity: Type.Integer(),
+    avgPrice: Type.Number(),
+    pnl: Type.Number(),
+  },
+  { additionalProperties: false },
+);
+
+export const PortfolioSnapshot = Type.Object(
+  {
+    accountId: Type.String(),
+    positions: Type.Array(PortfolioPosition), // vector of tables
+    totalValue: Type.Number(),
+    cash: Type.Number(),
+    ts: Type.Integer(),
+    updatedBy: Type.Optional(Type.String()), // optional string
+  },
+  { additionalProperties: false },
+);
+
+// ── Complex / nested payloads (integrity + nesting coverage) ──────────
+export const Tag = Type.Union([Type.Literal("hot"), Type.Literal("new"), Type.Literal("sale")]);
+
+/** Every packed-vector kind + scalars on ONE flat event (DIRECT fast path). */
+export const Complex = Type.Object(
+  {
+    id: Type.String(),
+    names: Type.Array(Type.String()), // vector-string
+    prices: Type.Array(Type.Number()), // vector-double
+    counts: Type.Array(Type.Integer()), // vector-int64
+    flags: Type.Array(Type.Boolean()), // vector-bool
+    tags: Type.Array(Tag), // vector-enum
+    active: Type.Boolean(),
+    total: Type.Number(),
+    ts: Type.Integer(),
+  },
+  { additionalProperties: false },
+);
+
+/** Nested single-object table (forces the JSON fallback path in `order`). */
+export const Customer = Type.Object(
+  {
+    id: Type.String(),
+    name: Type.String(),
+    vip: Type.Boolean(),
+    loyaltyPoints: Type.Integer(),
+    rating: Type.Number(),
+  },
+  { additionalProperties: false },
+);
+
+/** Table element with its own vector (deep nesting — not "flat"). */
+export const OrderLine = Type.Object(
+  {
+    sku: Type.String(),
+    qty: Type.Integer(),
+    unitPrice: Type.Number(),
+    tags: Type.Array(Tag), // vector-enum inside a table element
+  },
+  { additionalProperties: false },
+);
+
+/** Deeply nested event: single-object table, optional table, table-of-tables. */
+export const Order = Type.Object(
+  {
+    orderId: Type.String(),
+    customer: Customer, // nested single-object table
+    lines: Type.Array(OrderLine), // vector of tables (each with a vector-enum)
+    notes: Type.Array(Type.String()), // vector-string
+    discounts: Type.Array(Type.Number()), // vector-double
+    active: Type.Boolean(),
+    createdAt: Type.Integer(),
+    billing: Type.Optional(Customer), // optional nested table
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * An event with an EXACT int64 field: `Type.Integer({ bigint: true })` makes
+ * the field decode/encode as `bigint` on both sides, so values above 2^53
+ * round-trip losslessly (plain `number` int64s silently lose precision there).
+ */
+export const BigVal = Type.Object(
+  {
+    id: Type.String(),
+    seq: Type.BigInt(), // exact int64 — survives beyond 2^53 (maps to `long` on the wire)
+    when: Type.Integer(), // plain number (safe-integer timestamps)
+  },
+  { additionalProperties: false },
+);
+
+// ── Named schemas (referenced tables / enums) ────────────────────────
+export const schemas = {
+  Trade,
+  Quote,
+  PortfolioPosition,
+  PortfolioSnapshot,
+  Complex,
+  Customer,
+  OrderLine,
+  Order,
+  BigVal,
+} as const;
+
+// ── Event registry (source of truth for event ids + public API types) ─
+export const events = {
+  quote: Quote,
+  trade: Trade,
+  portfolio: PortfolioSnapshot,
+  complex: Complex, // DIRECT path — all packed-vector kinds
+  order: Order, // JSON fallback path — nested single-object tables
+  bigVal: BigVal, // DIRECT path — exact bigint int64 field
+} as const;
+
+// ── Control events (transport-internal — hidden from the public Events surface) ─
+//
+// These are first-class FlatBuffer tables so they ride the SAME codegen,
+// self-tests, and wire envelope as app events. The server encodes them via the
+// Rust FFI (direct path — all are flat/directable); the browser client encodes
+// them via the generated JS encoder (ts-ser). The transport layers route
+// control frames BEFORE user handlers.
+//
+// Rules enforced by the direct fast path (why fields are shaped like this):
+//   - no optional scalars / optional vectors (direct path has no Option support
+//     for them) — use required fields with a 0/[] sentinel
+export const Hello = Type.Object(
+  {
+    version: Type.Integer(), // wire version the sender supports
+    caps: Type.Array(Type.String()), // capabilities list ([] = none)
+    lastSeq: Type.Integer(), // last sequence seen (0 = none)
+  },
+  { additionalProperties: false },
+);
+
+export const Subscribe = Type.Object({ topic: Type.String() }, { additionalProperties: false });
+
+export const Unsubscribe = Type.Object({ topic: Type.String() }, { additionalProperties: false });
+
+export const JoinGroup = Type.Object({ group: Type.String() }, { additionalProperties: false });
+
+export const LeaveGroup = Type.Object({ group: Type.String() }, { additionalProperties: false });
+
+export const SnapshotRequest = Type.Object({ topic: Type.String() }, { additionalProperties: false });
+
+export const Ping = Type.Object({ ts: Type.Integer() }, { additionalProperties: false });
+
+export const Pong = Type.Object({ ts: Type.Integer() }, { additionalProperties: false });
+
+/** Server→client identity assignment (sent right after `hello` on open). */
+export const Welcome = Type.Object(
+  {
+    clientId: Type.String(), // the id assigned to this connection (auth metadata or UUID)
+    groups: Type.Array(Type.String()), // server-side groups this client belongs to
+  },
+  { additionalProperties: false },
+);
+
+/** Transport-internal event registry (name → schema). Not part of Events[K]. */
+export const controlEvents = {
+  hello: Hello,
+  welcome: Welcome,
+  subscribe: Subscribe,
+  unsubscribe: Unsubscribe,
+  joinGroup: JoinGroup,
+  leaveGroup: LeaveGroup,
+  snapshotRequest: SnapshotRequest,
+  ping: Ping,
+  pong: Pong,
+} as const;
+
+export type EventName = keyof typeof events;
+export type ControlEventName = keyof typeof controlEvents;
+export type AnyEventName = EventName | ControlEventName;
+export type Events = { [K in EventName]: Static<(typeof events)[K]> };
+export type ControlEvents = { [K in ControlEventName]: Static<(typeof controlEvents)[K]> };

package/src/server.ts

@@ -0,0 +1,87 @@
+/**
+ * Runnable demo server.
+ *
+ *   bun run serve   (after: bun run generate && cargo build --release && bun run build:client)
+ *
+ * Serves:
+ *   - /ws      → websocket (typed pub/sub events)
+ *   - /health  → health check
+ *   - /        → client/index.html + /dist/* from client-dist/ (browser demo)
+ */
+import { join } from "node:path";
+import { createServer } from "../public/server";
+
+const here = import.meta.dir;
+const CLIENT_DIR = join(here, "..", "client");
+const DIST_DIR = join(here, "..", "client-dist");
+
+const port = Number(process.env.PORT ?? 3000);
+const natsUrl = process.env.NATS_URL;
+const server = createServer({
+  port,
+  nats: natsUrl ? { servers: [natsUrl], inbound: true } : undefined,
+  fetch: (req) => serveStatic(req),
+});
+
+console.log(`ignex demo: http://localhost:${port}/  (ws: ws://localhost:${port}/ws)`);
+if (natsUrl) {
+  console.log(`ignex demo: NATS bridge → ${natsUrl} (subjects: ignex.broadcast.* / ignex.topic.* / ignex.group.*; inbound: ignex.inbound.>)`);
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+};
+
+async function serveStatic(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const rel = url.pathname === "/" ? "/index.html" : url.pathname;
+  const file = rel.startsWith("/dist/")
+    ? join(DIST_DIR, rel.slice("/dist/".length))
+    : join(CLIENT_DIR, rel);
+  const f = Bun.file(file);
+  if (!(await f.exists())) return new Response("not found", { status: 404 });
+  const ext = file.slice(file.lastIndexOf(".")).toLowerCase();
+  return new Response(f, { headers: { "content-type": CONTENT_TYPES[ext] ?? "application/octet-stream" } });
+}
+
+// Static page + pub/sub websocket share one port: /ws is upgraded by the
+// event server, everything else falls through to the static file handler.
+
+// ── push synthetic market data ─────────────────────────────────────────
+let seq = 0;
+setInterval(() => {
+  seq++;
+  server.publish("quote", {
+    symbol: "AAPL",
+    bid: 180 + Math.sin(seq / 10) * 0.5,
+    ask: 180.1 + Math.cos(seq / 10) * 0.5,
+    bidSize: 100 + (seq % 400),
+    askSize: 200 + (seq % 300),
+    ts: Date.now(),
+  });
+  server.publish("trade", {
+    symbol: seq % 2 === 0 ? "AAPL" : "MSFT",
+    price: 180 + Math.random(),
+    volume: 1 + (seq % 50),
+    side: seq % 2 === 0 ? "buy" : "sell",
+    ts: Date.now(),
+  });
+  if (seq % 5 === 0) {
+    server.publish("portfolio", {
+      accountId: "demo-1",
+      positions: [
+        { symbol: "AAPL", quantity: 100, avgPrice: 175, pnl: 500 + seq },
+        { symbol: "MSFT", quantity: 50, avgPrice: 400, pnl: -120 + seq },
+      ],
+      totalValue: 18000 + seq,
+      cash: 2500,
+      ts: Date.now(),
+      updatedBy: "ignex-demo",
+    });
+  }
+}, 0);

package/src/transport/byte-buffer-pool.ts

@@ -0,0 +1,63 @@
+/**
+ * Pooled `flatbuffers.ByteBuffer` — avoids allocating a fresh ByteBuffer (and
+ * the new `TextDecoder` its constructor creates) for every decoded frame.
+ *
+ * Why this is safe:
+ *   - `flatbuffers.ByteBuffer` stores its backing view in a stable internal
+ *     field (`bytes_`) and its read offset in `position_` (plain JS properties
+ *     in v25). The read offset also has a public `setPosition()`.
+ *   - Decoding is SYNCHRONOUS and the generated `.unpack()`/`*ToPlain` path
+ *     fully materializes the plain-object payload before `decodePayload`
+ *     returns — nothing reads the ByteBuffer afterwards, and no lazy reference
+ *     to the frame bytes escapes (strings are decoded eagerly via
+ *     `text_decoder_`, vectors are copied into fresh arrays).
+ *   - Therefore a single reused instance can be re-pointed at each new frame.
+ *
+ * Robustness: the first use verifies the internal `bytes_` field exists. If a
+ * future flatbuffers version renames it, we fall back to constructing a fresh
+ * ByteBuffer per call (the previous behavior). Browser-safe (imports only
+ * `flatbuffers`), so the generated registry (used by the client bundle) can use
+ * it.
+ */
+import * as flatbuffers from "flatbuffers";
+
+let pooled: flatbuffers.ByteBuffer | null = null;
+/** null = not probed yet; true = pooling works; false = use fresh per call. */
+let usable: boolean | null = null;
+
+function probe(): boolean {
+  const bb = new flatbuffers.ByteBuffer(new Uint8Array(1));
+  return (bb as unknown as { bytes_?: Uint8Array }).bytes_ instanceof Uint8Array;
+}
+
+/**
+ * Return a ByteBuffer viewing `bytes`, positioned at `pos` (a RELATIVE index
+ * into `bytes`, i.e. the wire envelope length — flatbuffers reads are
+ * `bytes_[offset]`, relative to the view's start, so `position_` must be
+ * relative too, NOT `bytes.byteOffset + pos`). Reuses a single pooled instance
+ * when the running flatbuffers version supports it; otherwise constructs a
+ * fresh one (also positioned) — the previous behavior.
+ */
+export function pooledByteBuffer(bytes: Uint8Array, pos: number): flatbuffers.ByteBuffer {
+  if (usable === false) {
+    const bb = new flatbuffers.ByteBuffer(bytes);
+    bb.setPosition(pos);
+    return bb;
+  }
+  if (usable === null) usable = probe();
+  if (!usable) {
+    const bb = new flatbuffers.ByteBuffer(bytes);
+    bb.setPosition(pos);
+    return bb;
+  }
+  if (!pooled) pooled = new flatbuffers.ByteBuffer(bytes);
+  (pooled as unknown as { bytes_: Uint8Array }).bytes_ = bytes;
+  pooled.setPosition(pos);
+  return pooled;
+}
+
+/** @internal test hook — force the fresh-per-call fallback path. */
+export function __forceFreshPoolForTest(force: boolean): void {
+  usable = force ? false : null;
+  pooled = null;
+}

package/src/transport/scratch.ts

@@ -0,0 +1,48 @@
+/**
+ * Reusable output scratch buffer for the zero-alloc encode path. `createScratch`
+ * owns a growable `Uint8Array` and the FFI "needed-size" grow/retry convention
+ * (`0` = error, `w > cap` = exact size). One instance is created per process in
+ * `transport.ts` and reused for every encode — no per-call allocation.
+ */
+export interface Scratch {
+  /** current backing buffer (may be reallocated by `grow`) */
+  readonly view: Uint8Array;
+  grow(needed: number): void;
+  /**
+   * Validate an FFI write count, growing + retrying once if the buffer was too
+   * small. Returns the final write size, or throws on error/retry-failure.
+   */
+  neededSize(name: string, w: number, retry: () => number): number;
+}
+
+export const MIN_CAP = 512;
+
+export function createScratch(initialCap = MIN_CAP): Scratch {
+  let buf = new Uint8Array(initialCap);
+
+  function grow(needed: number): void {
+    if (buf.byteLength >= needed) return;
+    buf = new Uint8Array(Math.max(buf.byteLength * 2, needed));
+  }
+
+  function neededSize(name: string, w: number, retry: () => number): number {
+    if (w === 0) throw new Error(`ignex: serialize failed for event "${name}"`);
+    if (w > buf.byteLength) {
+      grow(w);
+      const w2 = retry();
+      if (w2 === 0 || w2 > buf.byteLength) {
+        throw new Error(`ignex: serialize retry failed for event "${name}"`);
+      }
+      return w2;
+    }
+    return w;
+  }
+
+  return {
+    get view(): Uint8Array {
+      return buf;
+    },
+    grow,
+    neededSize,
+  };
+}