@ignex/nova 0.1.1 → 0.1.5

package/src/native/ffi.ts

@@ -17,11 +17,16 @@
  *     `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.
+ *
+ * Generic: `bindFfi(req)` binds for ANY schema (`req` comes from a `Bindings`
+ * object — the built-in one or a user-generated one), and the bind-time
+ * self-test now ALSO verifies the cdylib's `fb_schema_fingerprint` matches the
+ * schema's fingerprint, so a schema-mismatched addon fails loudly instead of
+ * producing undecodable frames.
  */
 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 type { Bindings, DirectTables } from "../bindings/types";
+import { defaultBindings } from "../bindings/default";
 import { getAddonPath } from "./loader";
 
 export const FB_PROBE_MAGIC = 0x4947_4e58; // "IGNX"
@@ -30,14 +35,16 @@ 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). */
+  /** Wire-format version of the cdylib (must equal the bindings' WIRE_VERSION). */
   fb_wire_version(): number;
+  /** Schema fingerprint of the cdylib (must equal the bindings' SCHEMA_FINGERPRINT). */
+  fb_schema_fingerprint(): number;
 }
 
 /** Output-buffer ABI mode of the live binding (set once by `bind()`). */
 export type BufferAbiMode = "buffer-pair" | "ptr-len";
 
-interface Dl {
+export interface FfiDl {
   bindings: BunFfi;
   /** every bound symbol, callable with raw args (…fieldArgs, out, out) */
   raw: Record<string, (...args: unknown[]) => number>;
@@ -46,7 +53,16 @@ interface Dl {
   bufferAbiMode: BufferAbiMode;
 }
 
-let cachedDl: Dl | null | undefined;
+/** What the FFI binder needs from a `Bindings` object (schema-specific parts). */
+export interface FfiRequirements {
+  readonly wireVersion: number;
+  readonly wireHeaderLen: number;
+  readonly schemaFingerprint: number;
+  readonly eventNameToId: Readonly<Record<string, number>>;
+  readonly direct?: DirectTables;
+}
+
+let cachedDl: FfiDl | null | undefined;
 let bufferAbiMode: BufferAbiMode = "ptr-len";
 
 const U64_FAST = "u64_fast" as unknown as FFITypeOrString;
@@ -117,7 +133,14 @@ function adaptOut(sym: (...a: unknown[]) => number, mode: BufferAbiMode): (...a:
   };
 }
 
-function bind(): Dl {
+/**
+ * Bind the cdylib for a specific schema (`req`). Throws on any self-test
+ * failure: missing addon, `fb_probe` magic mismatch, wire-version drift,
+ * schema-fingerprint drift (stale / mismatched addon), or a broken JSON path.
+ * Direct symbols that fail their per-symbol self-test are DISABLED (their
+ * events fall back to the JSON path) rather than throwing.
+ */
+export function bindFfi(req: FfiRequirements): FfiDl {
   const path = getAddonPath();
 
   // Probe the atomic `buffer`/`buffer_length` pair once; fall back to explicit
@@ -130,8 +153,9 @@ function bind(): Dl {
     fb_serialize: { args: abi(["u32", "cstring", "ptr", "usize"]), returns: U64_FAST },
     fb_probe: { args: [], returns: "u32" },
     fb_wire_version: { args: [], returns: "u32" },
+    fb_schema_fingerprint: { args: [], returns: U64_FAST },
   };
-  for (const [name, spec] of Object.entries(directSymbols)) {
+  for (const [name, spec] of Object.entries(req.direct?.symbols ?? {})) {
     specMap[name] = { args: abi(spec.args), returns: spec.returns as FFITypeOrString };
   }
 
@@ -147,24 +171,34 @@ function bind(): Dl {
     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,
+    fb_schema_fingerprint: () => raw["fb_schema_fingerprint"]!() 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) {
+  // Wire-version drift check: a stale cdylib (built from an older envelope)
+  // must fail loudly at bind instead of producing undecodable frames.
+  if (bindings.fb_wire_version() !== req.wireVersion) {
+    throw new Error(
+      `ignex: FFI self-test failed (wire version ${bindings.fb_wire_version()} !== ${req.wireVersion}) — addon at ${path}; regenerate + rebuild`,
+    );
+  }
+  // Schema-fingerprint check: a cdylib built from a DIFFERENT schema (e.g. the
+  // built-in addon loaded by a project with its own generated bindings) must
+  // fail loudly instead of silently encoding the wrong tables.
+  if (bindings.fb_schema_fingerprint() !== req.schemaFingerprint) {
     throw new Error(
-      `ignex: FFI self-test failed (wire version ${bindings.fb_wire_version()} !== ${WIRE_VERSION}) — addon at ${path}; regenerate + rebuild`,
+      `ignex: FFI self-test failed (schema fingerprint ${bindings.fb_schema_fingerprint()} !== ${req.schemaFingerprint}) — ` +
+        `addon at ${path} was built from a different schema; build the addon from your generated rust/ crate (or unset IGNEX_FFI_PATH to use the pure-JS encoder)`,
     );
   }
   // 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 firstEvent = Object.keys(req.eventNameToId)[0] as string;
+  const firstId = req.eventNameToId[firstEvent]!;
   const scratch = new Uint8Array(2048);
   const jw = bindings.fb_serialize(firstId, "{}", scratch);
   if (jw === 0 || jw > scratch.byteLength) {
@@ -172,41 +206,64 @@ function bind(): Dl {
   }
   {
     const dv = new DataView(scratch.buffer, scratch.byteOffset, scratch.byteLength);
-    const size = dv.getUint32(scratch.byteOffset + WIRE_HEADER_LEN, true);
+    const size = dv.getUint32(scratch.byteOffset + req.wireHeaderLen, true);
     const gotId = dv.getUint32(scratch.byteOffset + 1, true);
-    if (scratch[0] !== WIRE_VERSION || gotId !== firstId || jw !== WIRE_HEADER_LEN + 4 + size) {
+    if (scratch[0] !== req.wireVersion || gotId !== firstId || jw !== req.wireHeaderLen + 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)));
+  const disabledDirect = new Set(req.direct ? req.direct.selfTest(raw, new Uint8Array(2048)) : []);
 
   return { bindings, raw, disabledDirect, bufferAbiMode };
 }
 
-function ensure(): Dl {
-  if (cachedDl === undefined) cachedDl = bind();
-  return cachedDl as Dl;
+/**
+ * Bind the cdylib for a `Bindings` object.
+ *   - `ffiMode: "required"` — bind or THROW (the built-in registry's contract).
+ *   - `ffiMode: "optional"` — used only when the user explicitly pointed at an
+ *     addon (`IGNEX_FFI_PATH`); any bind / self-test failure (missing addon,
+ *     schema mismatch, ...) returns `null`, and the transport falls back to the
+ *     pure-JS encoder. Warns once per schema fingerprint.
+ */
+const warnedOptional = new Set<number>();
+export function createFfi(bindings: Bindings): FfiDl | null {
+  if (bindings.ffiMode === "required") return bindFfi(bindings);
+  if (!process.env.IGNEX_FFI_PATH) return null; // no addon requested — pure JS
+  try {
+    return bindFfi(bindings);
+  } catch (err) {
+    if (!warnedOptional.has(bindings.schemaFingerprint)) {
+      warnedOptional.add(bindings.schemaFingerprint);
+      console.warn(`ignex: native addon unavailable for this schema — using the pure-JS encoder (${(err as Error).message})`);
+    }
+    return null;
+  }
+}
+
+function ensureDefault(): FfiDl {
+  if (cachedDl === undefined) cachedDl = bindFfi(defaultBindings);
+  return cachedDl as FfiDl;
 }
 
-/** Lazily bind once. Throws if the addon is missing or the self-test fails. */
+/** Lazily bind once (built-in registry). Throws if the addon is missing. */
 export function getFfi(): BunFfi {
-  return ensure().bindings;
+  return ensureDefault().bindings;
 }
 
-/** Output-buffer ABI mode of the live binding (lazy — triggers bind). */
+/** Output-buffer ABI mode of the live default binding (lazy — triggers bind). */
 export function getBufferAbiMode(): BufferAbiMode {
-  return ensure().bufferAbiMode;
+  return ensureDefault().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).
+ * Direct fast-path symbol (built-in registry). 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.
  */
 export function getDirectSymbol(name: string): ((...args: unknown[]) => number) | undefined {
-  const dl = ensure();
+  const dl = ensureDefault();
   if (dl.disabledDirect.has(name)) return undefined;
   const symbol = dl.raw[name];
   if (!symbol) throw new Error(`ignex: unknown direct symbol "${name}"`);

package/src/schema/index.ts

@@ -9,7 +9,7 @@
  * 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";
+import { type Static, Type } from "@sinclair/typebox";
 
 // ── Enums (union of string literals → FlatBuffer enum) ───────────────
 export const Side = Type.Union([Type.Literal("buy"), Type.Literal("sell")]);
@@ -182,12 +182,55 @@ export const JoinGroup = Type.Object({ group: Type.String() }, { additionalPrope
 
 export const LeaveGroup = Type.Object({ group: Type.String() }, { additionalProperties: false });
 
-export const SnapshotRequest = Type.Object({ topic: Type.String() }, { additionalProperties: false });
+export const SnapshotRequest = Type.Object(
+  {
+    topic: Type.String(),
+    /**
+     * Resume point: serve recorded history STRICTLY AFTER this topic seq
+     * (0 = from the beginning of retained history — the v1 behavior).
+     */
+    fromSeq: Type.Integer(),
+  },
+  { additionalProperties: false },
+);
 
 export const Ping = Type.Object({ ts: Type.Integer() }, { additionalProperties: false });
 
 export const Pong = Type.Object({ ts: Type.Integer() }, { additionalProperties: false });
 
+/**
+ * Client → server: resume missed delivery-seq frames after a gap or
+ * reconnect. The server replays everything it still holds strictly after
+ * `lastSeq` from the per-connection history ring, prefixed by a `resumed`
+ * control frame (`ok:false` when the hole is older than the ring).
+ */
+export const Resume = Type.Object(
+  { lastSeq: Type.Integer() }, // last CONTIGUOUS delivery seq the client has
+  { additionalProperties: false },
+);
+
+/** Server → client: ack before replayed frames (`ok:false` → resubscribe topics). */
+export const Resumed = Type.Object(
+  { ok: Type.Boolean(), from: Type.Integer() }, // first seq being replayed
+  { additionalProperties: false },
+);
+
+/**
+ * Request/response over the event wire (correlation id + timeout live on the
+ * caller side). `name` is the app-event name being requested; `payload` is the
+ * base64 of a full wire frame encoded with that same event's schema — the
+ * response reuses the SAME event schema both directions.
+ */
+export const RpcCall = Type.Object(
+  { id: Type.String(), name: Type.String(), payloadB64: Type.String() },
+  { additionalProperties: false },
+);
+
+export const RpcResult = Type.Object(
+  { id: Type.String(), ok: Type.Boolean(), err: Type.String(), payloadB64: Type.String() },
+  { additionalProperties: false },
+);
+
 /** Server→client identity assignment (sent right after `hello` on open). */
 export const Welcome = Type.Object(
   {
@@ -208,6 +251,10 @@ export const controlEvents = {
   snapshotRequest: SnapshotRequest,
   ping: Ping,
   pong: Pong,
+  resume: Resume,
+  resumed: Resumed,
+  rpcCall: RpcCall,
+  rpcResult: RpcResult,
 } as const;
 
 export type EventName = keyof typeof events;

package/src/server.ts

@@ -19,13 +19,15 @@ const port = Number(process.env.PORT ?? 3000);
 const natsUrl = process.env.NATS_URL;
 const server = createServer({
   port,
-  nats: natsUrl ? { servers: [natsUrl], inbound: true } : undefined,
+  ...(natsUrl ? { nats: { servers: [natsUrl], inbound: true } } : {}),
   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.>)`);
+  console.log(
+    `ignex demo: NATS bridge → ${natsUrl} (subjects: ignex.broadcast.* / ignex.topic.* / ignex.group.*; inbound: ignex.inbound.>)`,
+  );
 }
 
 const CONTENT_TYPES: Record<string, string> = {
@@ -46,7 +48,9 @@ async function serveStatic(req: Request): Promise<Response> {
   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" } });
+  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

package/src/transport/transport.ts

@@ -1,106 +1,227 @@
 /**
- * Internal transport: JS object → wire frame via Rust FFI.
- * frame = `[1-byte event_id][size-prefixed FlatBuffer]` — fully produced by Rust.
+ * Internal transport: JS object → wire frame via Rust FFI (or the pure-JS
+ * encoder for user schemas without a native addon).
+ * frame = `[WIRE_VERSION:1][event_id:u32 LE][size-prefixed FlatBuffer]` — fully
+ * produced by Rust (envelope header is WIRE_HEADER_LEN = 5 bytes).
  *
- * Two paths:
+ * Three paths:
  *   - DIRECT (flat events, generated): fields pushed straight into Rust as FFI
  *     args from a zero-alloc encoder — no JSON, no intermediate array, and a
  *     single reusable output scratch (`encodeToScratch`).
  *   - JSON fallback (events with vectors / nested tables): object → JSON →
  *     `fb_serialize` → Rust parses and builds (still allocates — documented).
+ *   - JS fallback (user schemas without a native addon): the generated pure-JS
+ *     encoder (`bindings.encodeFrame`) — correct everywhere, slower, and the
+ *     default when `ffiMode: "optional"` and no addon is available.
+ *
+ * ALL per-event dispatch state is resolved EAGERLY at `createTransport()`
+ * (instantiation time), not lazily on first encode: every known event name —
+ * app AND control — gets an {@link EncodeRecord} up front, holding its event
+ * id, generated encoder, NUL pre-scan and (once the addon binds) its direct
+ * FFI symbol + encode-path counters. The hot path is then one Map hit plus a
+ * couple of monomorphic field reads/increments — no lazy-init branches, no
+ * second stats Map, no per-encode counter allocation.
+ *
+ * `createTransport(bindings)` is a per-schema factory: it owns its own scratch
+ * + records + FFI binding, so several servers with different schemas can
+ * coexist. The module-level `defaultTransport` (built-in registry, Rust
+ * required) keeps the historical singleton behavior — `encodeToScratch` /
+ * `encodeEvent` / `getEncodeStats` remain re-exported for backwards compat.
  */
-import { directEncoders, directSymbolNames, hasNulEncoders } from "../generated/direct-ser";
-import { anyEventNameToId } from "../generated/registry";
-import type { AnyEventName } from "../schema";
-import { getDirectSymbol, getFfi } from "../native/ffi";
-import { createScratch, MIN_CAP } from "./scratch";
-import { createStats } from "./stats";
 
-// Single reusable output scratch + encode-path stats, created once per process
-// and reused for every encode (the zero-alloc hot path). Safe to reuse right
-// after `ws.send` — Bun copies binary frames synchronously (verified
-// empirically). These are intentionally module-level singletons: threading
-// them through every encode call would only add parameter churn to the hot
-// path for no functional gain.
-const scratch = createScratch();
-const stats = createStats();
+import { defaultBindings } from "../bindings/default";
+import type { Bindings, DirectEncoder } from "../bindings/types";
+import { createFfi, type FfiDl } from "../native/ffi";
+import { createScratch, MIN_CAP } from "./scratch";
 
-/**
- * Resolved direct-path record for one event — populated lazily on first encode
- * and immutable afterwards (a direct symbol that was disabled by the bind-time
- * self-test never re-enables, so caching the resolved call is safe).
- */
-interface ResolvedDirect {
+/** Everything the hot path needs for one event — built once at instantiation. */
+interface EncodeRecord {
+  /** stable wire id (anyEventNameToId) — used by the JSON fallback */
+  readonly id: number;
   /** generated zero-alloc encoder (absent for JSON-only events) */
-  encoder?: (call: (...args: unknown[]) => number, o: unknown, out: Uint8Array) => number;
-  /** resolved FFI symbol (undefined = symbol disabled → JSON fallback) */
-  call?: (...args: unknown[]) => number;
+  readonly encoder: DirectEncoder | undefined;
+  /** FFI symbol name in the addon (absent when there is no direct table) */
+  readonly symName: string | undefined;
   /** per-event NUL pre-scan (absent when the event has no string fields) */
-  hasNul?: (o: unknown) => boolean;
+  readonly hasNul: ((o: unknown) => boolean) | undefined;
+  /**
+   * Resolved FFI symbol: undefined = not yet bound OR disabled/JSON-only.
+   * Flipped to a function once the addon binds; set back to undefined when a
+   * runtime failure (`ffiMode: "optional"`) permanently demotes this event to
+   * the JSON path.
+   */
+  call: ((...args: unknown[]) => number) | undefined;
+  /** encode-path counters — incremented IN PLACE on the record (no Maps) */
+  directCount: number;
+  jsonCount: number;
+  jsCount: number;
 }
-const resolvedDirect = new Map<string, ResolvedDirect>();
-
-function resolveDirect(name: AnyEventName): ResolvedDirect {
-  let r = resolvedDirect.get(name);
-  if (r === undefined) {
-    r = {};
-    const encoder = directEncoders[name];
-    if (encoder) {
-      r.encoder = encoder;
-      r.call = getDirectSymbol(directSymbolNames[name]!);
-      r.hasNul = hasNulEncoders[name];
-    }
-    resolvedDirect.set(name, r);
-  }
-  return r;
+
+export interface Transport {
+  /**
+   * Zero-allocation encode into the transport's shared output scratch. The
+   * returned view is only valid until the next call — publish/send it
+   * immediately (Bun copies). Accepts app events AND control events.
+   */
+  encodeToScratch(name: string, payload: unknown): Uint8Array;
+  /** Owned copy (safe to hold) — used by tests/bench. One allocation. */
+  encodeEvent(name: string, payload: unknown): Uint8Array;
+  /** encode-path stats (direct vs json vs js). */
+  getEncodeStats(): {
+    direct: Record<string, number>;
+    json: Record<string, number>;
+    js: Record<string, number>;
+  };
 }
 
-/**
- * Zero-allocation encode into the shared output scratch. The returned view is
- * only valid until the next call — publish/send it immediately (Bun copies).
- * Accepts app events AND control events (hello/subscribe/ping/...) — the
- * server encodes both through the Rust FFI.
- */
-export function encodeToScratch(name: AnyEventName, payload: unknown): Uint8Array {
-  const r = resolveDirect(name);
-  const encoder = r.encoder;
-  if (encoder && r.call) {
-    // `call` is undefined when the bind-time self-test disabled the symbol —
-    // fall through to the JSON path (graceful degradation). Embedded NULs route
-    // to JSON too: the `cstring` direct path truncates them (silent data loss),
-    // the JSON path preserves them exactly.
-    if (!(r.hasNul?.(payload) ?? false)) {
-      scratch.grow(MIN_CAP);
-      const w = scratch.neededSize(name, encoder(r.call, payload, scratch.view), () => encoder(r.call!, payload, scratch.view));
-      stats.bump(name, "direct");
+export function createTransport(bindings: Bindings): Transport {
+  const scratch = createScratch();
+
+  // ── instantiation-time resolution: one record per known event ────────────
+  const records = new Map<string, EncodeRecord>();
+  for (const name of Object.keys(bindings.anyEventNameToId)) {
+    const direct = bindings.direct;
+    const encoder = direct?.encoders[name];
+    const hasNul = direct?.hasNul[name];
+    records.set(name, {
+      id: bindings.anyEventNameToId[name] as number,
+      encoder,
+      ...(encoder !== undefined ? { symName: direct?.symbolNames[name] } : { symName: undefined }),
+      hasNul,
+      call: undefined,
+      directCount: 0,
+      jsonCount: 0,
+      jsCount: 0,
+    });
+  }
+
+  // Lazily bound once: undefined = not yet resolved, null = JS-only mode,
+  // FfiDl = bound addon. For ffiMode "required" the bind throws (missing /
+  // mismatched addon fails on first encode, as before); for "optional" it
+  // resolves to null and the JS encoder is used.
+  let ffi: FfiDl | null | undefined;
+  const getFfiDl = (): FfiDl | null => {
+    if (ffi === undefined) ffi = createFfi(bindings);
+    return ffi;
+  };
+
+  /**
+   * Bind the addon once and fan the resolved symbols out across ALL records
+   * in a single pass — the first encode pays the dlopen + self-test, every
+   * later encode sees a plain populated field. Self-test-disabled symbols are
+   * left undefined (their events take the JSON path).
+   */
+  const bindSymbols = (): void => {
+    const dl = getFfiDl();
+    if (dl === null) return;
+    const disabled = dl.disabledDirect;
+    for (const r of records.values()) {
+      if (r.encoder === undefined || r.symName === undefined) continue;
+      if (disabled.has(r.symName)) continue;
+      const sym = dl.raw[r.symName];
+      if (sym !== undefined) r.call = sym;
+    }
+  };
+
+  function encodeToScratch(name: string, payload: unknown): Uint8Array {
+    const r = records.get(name);
+    if (r === undefined) throw new Error(`ignex: unknown event "${name}"`);
+    const encoder = r.encoder;
+    if (encoder !== undefined) {
+      if (r.call === undefined && ffi === undefined) bindSymbols();
+      const call = r.call;
+      if (call !== undefined) {
+        // Embedded NULs route to JSON: the `cstring` direct path truncates
+        // them (silent data loss); the JSON path preserves them exactly.
+        if (!(r.hasNul?.(payload) ?? false)) {
+          if (bindings.ffiMode !== "optional") {
+            // required mode — zero-alloc hot path, no try/catch
+            scratch.grow(MIN_CAP);
+            const w = scratch.neededSize(name, encoder(call, payload, scratch.view), () =>
+              encoder(r.call as (...args: unknown[]) => number, payload, scratch.view),
+            );
+            r.directCount++;
+            return scratch.view.subarray(0, w);
+          }
+          try {
+            scratch.grow(MIN_CAP);
+            const w = scratch.neededSize(name, encoder(call, payload, scratch.view), () =>
+              encoder(r.call as (...args: unknown[]) => number, payload, scratch.view),
+            );
+            r.directCount++;
+            return scratch.view.subarray(0, w);
+          } catch {
+            // optional mode: a direct-call failure (e.g. ABI drift at runtime)
+            // permanently demotes this event to the JSON path.
+            r.call = undefined;
+          }
+        }
+      }
+    }
+
+    const dl = ffi === undefined ? getFfiDl() : ffi;
+    if (dl !== null) {
+      // JSON fallback (vector/nested events, or a disabled direct symbol).
+      const json = JSON.stringify(payload);
+      scratch.grow(Math.max(MIN_CAP, json.length * 2 + 128));
+      const w = scratch.neededSize(name, dl.bindings.fb_serialize(r.id, json, scratch.view), () =>
+        dl.bindings.fb_serialize(r.id, json, scratch.view),
+      );
+      r.jsonCount++;
       return scratch.view.subarray(0, w);
     }
+
+    // JS-only mode (user schema, no native addon) — the pure-JS encoder.
+    const frame = bindings.encodeFrame(name, payload);
+    r.jsCount++;
+    return frame;
   }
 
-  // JSON fallback (vector/nested events, or a disabled direct symbol).
-  const id = anyEventNameToId[name];
-  if (id === undefined) throw new Error(`ignex: unknown event "${name}"`);
+  function encodeEvent(name: string, payload: unknown): Uint8Array {
+    const frame = encodeToScratch(name, payload);
+    const owned = new Uint8Array(frame.byteLength);
+    owned.set(frame);
+    return owned;
+  }
 
-  const json = JSON.stringify(payload);
-  const ffi = getFfi();
-  scratch.grow(Math.max(MIN_CAP, json.length * 2 + 128));
-  const w = scratch.neededSize(name, ffi.fb_serialize(id, json, scratch.view), () => ffi.fb_serialize(id, json, scratch.view));
-  stats.bump(name, "json");
-  return scratch.view.subarray(0, w);
+  return {
+    encodeToScratch,
+    encodeEvent,
+    getEncodeStats() {
+      const direct: Record<string, number> = {};
+      const json: Record<string, number> = {};
+      const js: Record<string, number> = {};
+      for (const [name, r] of records) {
+        if (r.directCount > 0) direct[name] = r.directCount;
+        if (r.jsonCount > 0) json[name] = r.jsonCount;
+        if (r.jsCount > 0) js[name] = r.jsCount;
+      }
+      return { direct, json, js };
+    },
+  };
 }
 
-// ── encode-path stats (direct vs JSON) ─────────────────────────────────
-// Accumulated per event name across the process (typical deployments run one
-// server per process). Surfaced via `getEncodeStats()` / `server.metrics()`.
+// ── default transport (built-in registry) ──────────────────────────────────
+// Module-level singleton — the historical zero-alloc hot path. Re-exported
+// below so existing imports (`outbound.ts` migration aside) keep working.
 
-export function getEncodeStats(): { direct: Record<string, number>; json: Record<string, number> } {
-  return stats.get();
+export const defaultTransport: Transport = createTransport(defaultBindings);
+
+/** Zero-allocation encode into the shared output scratch (built-in registry). */
+export function encodeToScratch(name: string, payload: unknown): Uint8Array {
+  return defaultTransport.encodeToScratch(name, payload);
 }
 
 /** Owned copy (safe to hold) — used by tests/bench. One allocation. */
-export function encodeEvent(name: AnyEventName, payload: unknown): Uint8Array {
-  const frame = encodeToScratch(name, payload);
-  const owned = new Uint8Array(frame.byteLength);
-  owned.set(frame);
-  return owned;
+export function encodeEvent(name: string, payload: unknown): Uint8Array {
+  return defaultTransport.encodeEvent(name, payload);
+}
+
+/** encode-path stats for the built-in registry (direct vs JSON). */
+export function getEncodeStats(): {
+  direct: Record<string, number>;
+  json: Record<string, number>;
+  js: Record<string, number>;
+} {
+  return defaultTransport.getEncodeStats();
 }