@ignex/nova 0.1.1 → 0.1.3

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,7 +182,10 @@ 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() },
+  { additionalProperties: false },
+);
 
 export const Ping = Type.Object({ ts: Type.Integer() }, { additionalProperties: false });
 

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/stats.ts

@@ -8,8 +8,8 @@
  * increment — no Map.get + Map.set churn per encode.
  */
 export interface EncodeStats {
-  bump(name: string, path: "direct" | "json"): void;
-  get(): { direct: Record<string, number>; json: Record<string, number> };
+  bump(name: string, path: "direct" | "json" | "js"): void;
+  get(): { direct: Record<string, number>; json: Record<string, number>; js: Record<string, number> };
 }
 
 /** Mutable counter box — allocated once per (event, path), incremented in place. */
@@ -26,10 +26,14 @@ function toObj(m: Map<string, Counter>): Record<string, number> {
 export function createStats(): EncodeStats {
   const direct = new Map<string, Counter>();
   const json = new Map<string, Counter>();
+  const js = new Map<string, Counter>();
 
   return {
     bump(name, path) {
-      const m = path === "direct" ? direct : json;
+      let m: Map<string, Counter>;
+      if (path === "direct") m = direct;
+      else if (path === "json") m = json;
+      else m = js;
       let c = m.get(name);
       if (!c) {
         c = { n: 0 };
@@ -38,7 +42,7 @@ export function createStats(): EncodeStats {
       c.n++;
     },
     get() {
-      return { direct: toObj(direct), json: toObj(json) };
+      return { direct: toObj(direct), json: toObj(json), js: toObj(js) };
     },
   };
 }

package/src/transport/transport.ts

@@ -1,29 +1,48 @@
 /**
- * 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.
+ *
+ * `createTransport(bindings)` is a per-schema factory: it owns its own scratch +
+ * stats + 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 compatibility.
  */
-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 { defaultBindings } from "../bindings/default";
+import type { Bindings, DirectEncoder } from "../bindings/types";
+import { createFfi, type FfiDl } 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();
+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>;
+  };
+}
 
 /**
  * Resolved direct-path record for one event — populated lazily on first encode
@@ -32,75 +51,137 @@ const stats = createStats();
  */
 interface ResolvedDirect {
   /** generated zero-alloc encoder (absent for JSON-only events) */
-  encoder?: (call: (...args: unknown[]) => number, o: unknown, out: Uint8Array) => number;
+  encoder?: DirectEncoder;
   /** resolved FFI symbol (undefined = symbol disabled → JSON fallback) */
-  call?: (...args: unknown[]) => number;
+  call: ((...args: unknown[]) => number) | undefined;
   /** per-event NUL pre-scan (absent when the event has no string fields) */
   hasNul?: (o: unknown) => boolean;
 }
-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];
+
+export function createTransport(bindings: Bindings): Transport {
+  const scratch = createScratch();
+  const stats = createStats();
+  const resolvedDirect = new Map<string, ResolvedDirect>();
+
+  // 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;
+  };
+
+  const guard = bindings.ffiMode === "optional";
+
+  function resolveDirect(name: string): ResolvedDirect {
+    let r = resolvedDirect.get(name);
+    if (r === undefined) {
+      r = { call: undefined };
+      const encoder = bindings.direct?.encoders[name];
+      if (encoder) {
+        r.encoder = encoder;
+        const dl = getFfiDl();
+        const symName = bindings.direct?.symbolNames[name];
+        r.call = dl ? dl.raw[symName ?? ""] : undefined;
+        const hasNul = bindings.direct?.hasNul[name];
+        if (hasNul !== undefined) r.hasNul = hasNul;
+      }
+      resolvedDirect.set(name, r);
     }
-    resolvedDirect.set(name, r);
+    return r;
   }
-  return r;
-}
 
-/**
- * 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");
+  function encodeToScratch(name: string, 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)) {
+        if (!guard) {
+          // required mode — zero-alloc hot path, no try/catch
+          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");
+          return scratch.view.subarray(0, w);
+        }
+        try {
+          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");
+          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 = getFfiDl();
+    if (dl) {
+      // JSON fallback (vector/nested events, or a disabled direct symbol).
+      const id = bindings.anyEventNameToId[name];
+      if (id === undefined) throw new Error(`ignex: unknown event "${name}"`);
+      const json = JSON.stringify(payload);
+      const ffi2 = dl.bindings;
+      scratch.grow(Math.max(MIN_CAP, json.length * 2 + 128));
+      const w = scratch.neededSize(name, ffi2.fb_serialize(id, json, scratch.view), () =>
+        ffi2.fb_serialize(id, json, scratch.view),
+      );
+      stats.bump(name, "json");
       return scratch.view.subarray(0, w);
     }
+
+    // JS-only mode (user schema, no native addon) — the pure-JS encoder.
+    const frame = bindings.encodeFrame(name, payload);
+    stats.bump(name, "js");
+    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: () => stats.get(),
+  };
 }
 
-// ── 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 const defaultTransport: Transport = createTransport(defaultBindings);
 
-export function getEncodeStats(): { direct: Record<string, number>; json: Record<string, number> } {
-  return stats.get();
+/** 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();
 }