@ignex/nova 0.1.1 → 0.1.5

package/src/bindings/assemble.ts

@@ -0,0 +1,73 @@
+/**
+ * `assembleBindings` — build a runtime `Bindings` from generated parts.
+ *
+ * The generated artifacts (`registry.ts`, `ts-ser.ts`, `direct-ser.ts`) are
+ * schema-specific SOURCE produced by `generateBindings` (public/generate.ts).
+ * This function wires them into the single `Bindings` object the server /
+ * client / NATS bridge accept. It is also what the built-in registry uses
+ * (`src/bindings/default.ts`).
+ */
+import type { TSchema } from "@sinclair/typebox";
+import type { Bindings, DirectTables } from "./types";
+
+/** Everything `assembleBindings` needs from the generated artifacts. */
+export interface BindingsParts {
+  readonly wireVersion: number;
+  readonly wireHeaderLen: number;
+  readonly schemaFingerprint: number;
+  readonly eventNameToId: Readonly<Record<string, number>>;
+  readonly idToEventName: Readonly<Record<number, string>>;
+  readonly anyEventNameToId: Readonly<Record<string, number>>;
+  readonly idToAnyEventName: Readonly<Record<number, string>>;
+  readonly controlEventNameToId: Readonly<Record<string, number>>;
+  readFrameHeader(bytes: Uint8Array): { name: string; id: number } | null;
+  isControlId(id: number): boolean;
+  decodePayload(id: number, bytes: Uint8Array): unknown;
+  decodeFrame(bytes: Uint8Array): { name: string; id: number; payload: unknown } | null;
+  encodeFrame(name: string, payload: unknown): Uint8Array;
+  readonly direct?: DirectTables;
+}
+
+export interface AssembleOptions {
+  /** "required" | "optional" — see `Bindings.ffiMode`. */
+  ffiMode?: "required" | "optional";
+  /** NATS subject prefix for bridges built from these bindings. */
+  subjectPrefix?: string;
+}
+
+/**
+ * Wire generated parts + the schema registry into a `Bindings` object.
+ * `schema.events` / `schema.controlEvents` are the user's TypeBox schemas —
+ * they power the `EventsOf<B>` type derivation on the public API.
+ */
+export function assembleBindings<
+  E extends Record<string, TSchema>,
+  C extends Record<string, TSchema>,
+>(
+  parts: BindingsParts,
+  schema: { events: E; controlEvents?: C },
+  opts: AssembleOptions = {},
+): Omit<Bindings, "events" | "controlEvents"> & { events: E; controlEvents: C } {
+  const controlEvents = (schema.controlEvents ?? {}) as C;
+  const controlIds = new Set<number>(Object.values(parts.controlEventNameToId));
+  return {
+    wireVersion: parts.wireVersion,
+    wireHeaderLen: parts.wireHeaderLen,
+    schemaFingerprint: parts.schemaFingerprint,
+    ...(opts.subjectPrefix !== undefined ? { subjectPrefix: opts.subjectPrefix } : {}),
+    ffiMode: opts.ffiMode ?? "optional",
+    events: schema.events,
+    controlEvents,
+    eventNameToId: parts.eventNameToId,
+    idToEventName: parts.idToEventName,
+    anyEventNameToId: parts.anyEventNameToId,
+    idToAnyEventName: parts.idToAnyEventName,
+    controlIds,
+    readFrameHeader: parts.readFrameHeader,
+    isControlId: parts.isControlId,
+    decodePayload: parts.decodePayload,
+    decodeFrame: parts.decodeFrame,
+    encodeFrame: parts.encodeFrame,
+    ...(parts.direct ? { direct: parts.direct } : {}),
+  };
+}

package/src/bindings/default.ts

@@ -0,0 +1,65 @@
+/**
+ * The built-in `Bindings` — assembled from the repo's generated artifacts
+ * (`src/generated/*` + `src/schema`). This is the default for every entrypoint
+ * (`createServer` / `createClient` / `createNatsBridge`), so all existing code
+ * keeps working without passing `bindings`.
+ *
+ * For your own schema, see `generateBindings` (public/generate.ts) —
+ * `defaultBindings` is just the first, built-in instance of the same contract.
+ */
+
+import {
+  directEncoders,
+  directSelfTest,
+  directSymbolNames,
+  directSymbols,
+  hasNulEncoders,
+} from "../generated/direct-ser";
+import {
+  anyEventNameToId,
+  controlEventNameToId,
+  decodeFrame,
+  decodePayload,
+  eventNameToId,
+  idToAnyEventName,
+  idToEventName,
+  isControlId,
+  readFrameHeader,
+  SCHEMA_FINGERPRINT,
+  WIRE_HEADER_LEN,
+  WIRE_VERSION,
+} from "../generated/registry";
+import { encodeEventFrame } from "../generated/ts-ser";
+import { controlEvents, events } from "../schema";
+import { assembleBindings } from "./assemble";
+
+// NOTE: no explicit `: Bindings` annotation on purpose — the concrete
+// `events` / `controlEvents` schema types must survive inference so
+// `DefaultBindings` (and therefore `EventNameOf` / `EventsOf` on the default
+// API) resolves to the built-in `Events` map.
+export const defaultBindings = assembleBindings(
+  {
+    wireVersion: WIRE_VERSION,
+    wireHeaderLen: WIRE_HEADER_LEN,
+    schemaFingerprint: SCHEMA_FINGERPRINT,
+    eventNameToId,
+    idToEventName,
+    anyEventNameToId,
+    idToAnyEventName,
+    controlEventNameToId,
+    readFrameHeader,
+    isControlId,
+    decodePayload,
+    decodeFrame,
+    encodeFrame: encodeEventFrame as (name: string, payload: unknown) => Uint8Array,
+    direct: {
+      symbols: directSymbols,
+      symbolNames: directSymbolNames,
+      encoders: directEncoders,
+      hasNul: hasNulEncoders,
+      selfTest: directSelfTest,
+    },
+  },
+  { events, controlEvents },
+  { ffiMode: "required", subjectPrefix: "ignex" },
+);

package/src/bindings/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Runtime `Bindings` — the per-schema bundle that decouples the transport from
+ * ANY particular event registry.
+ *
+ * Today the transport modules import the repo's generated artifacts directly
+ * (`src/generated/registry`, `src/generated/ts-ser`, `src/generated/direct-ser`
+ * and `src/schema`). `Bindings` is the generic contract: every schema-specific
+ * piece of the wire stack (event ids, decoders, encoders, direct fast-path
+ * tables, schema metadata) is grouped into one object, and the server / client /
+ * NATS bridge accept it via `options.bindings` (defaulting to the built-in
+ * registry, so existing code keeps working unchanged).
+ *
+ * Two ways to obtain a `Bindings`:
+ *   - the built-in one: `defaultBindings` (see `src/bindings/default.ts`)
+ *   - your own schema: run `generateBindings(schema)` (public/generate.ts),
+ *     then assemble the emitted parts with `assembleBindings`
+ *     (src/bindings/assemble.ts). Everything else — encode, decode, NATS
+ *     subject naming, server/client APIs — is then typed against YOUR events.
+ */
+import type { Static, TSchema } from "@sinclair/typebox";
+
+/** Direct fast-path call signature (generated `direct-ser.ts`). */
+export type DirectCall = (...args: unknown[]) => number;
+
+/** Generated zero-alloc encoder: fields → FFI args → out buffer. */
+export type DirectEncoder = (call: DirectCall, o: unknown, out: Uint8Array) => number;
+
+/**
+ * The generated direct fast-path tables (Bun server only). Absent when the
+ * schema has no directable events or the codegen was run with `rust: false`.
+ */
+export interface DirectTables {
+  /** dlopen specs in canonical form (see `src/native/ffi.ts` `abi()`). */
+  readonly symbols: Readonly<Record<string, { args: readonly string[]; returns: string }>>;
+  /** event → FFI symbol name. */
+  readonly symbolNames: Readonly<Record<string, string>>;
+  /** event → zero-alloc encoder. */
+  readonly encoders: Readonly<Record<string, DirectEncoder>>;
+  /** event → NUL pre-scan (true routes the payload to the JSON path). */
+  readonly hasNul: Readonly<Record<string, (o: unknown) => boolean>>;
+  /** bind-time per-symbol self-test; returns the symbol names to DISABLE. */
+  readonly selfTest: (
+    raw: Record<string, (...args: unknown[]) => number>,
+    scratch: Uint8Array,
+  ) => string[];
+}
+
+/**
+ * The complete per-schema wire stack. `events` / `controlEvents` are the
+ * TypeBox schemas — from them consumers derive `EventNameOf` / `EventsOf`.
+ */
+export interface Bindings {
+  /** wire envelope version (see `scripts/constants.ts`). */
+  readonly wireVersion: number;
+  /** envelope header bytes: `[version:1][event_id:u32 LE]`. */
+  readonly wireHeaderLen: number;
+  /**
+   * Stable schema fingerprint (FNV-1a 32 over the canonical model). The Rust
+   * cdylib exports the same value (`fb_schema_fingerprint`), so a schema-
+   * mismatched addon fails the bind-time self-test instead of producing
+   * undecodable frames.
+   */
+  readonly schemaFingerprint: number;
+  /** NATS subject prefix used by bridges built from these bindings. */
+  readonly subjectPrefix?: string;
+  /**
+   * "required" — the Rust addon must exist and pass self-tests (the built-in
+   * registry: a missing addon throws). "optional" — generated for user
+   * schemas: the addon is used when `IGNEX_FFI_PATH` is set and passes
+   * self-tests; otherwise the pure-JS encoder is used (works without Rust).
+   */
+  readonly ffiMode: "required" | "optional";
+  /** app event schemas (name → TypeBox). */
+  readonly events: Readonly<Record<string, TSchema>>;
+  /** control event schemas (name → TypeBox). */
+  readonly controlEvents: Readonly<Record<string, TSchema>>;
+
+  // ── event id maps (stable FNV-1a 32 over the name) ────────────────────
+  readonly eventNameToId: Readonly<Record<string, number>>;
+  readonly idToEventName: Readonly<Record<number, string>>;
+  /** merged app + control maps (encode dispatch). */
+  readonly anyEventNameToId: Readonly<Record<string, number>>;
+  readonly idToAnyEventName: Readonly<Record<number, string>>;
+  readonly controlIds: ReadonlySet<number>;
+
+  // ── wire helpers (pure — run in browser + Bun) ────────────────────────
+  readFrameHeader(bytes: Uint8Array): { name: string; id: number } | null;
+  isControlId(id: number): boolean;
+  decodePayload(id: number, bytes: Uint8Array): unknown;
+  decodeFrame(bytes: Uint8Array): { name: string; id: number; payload: unknown } | null;
+
+  /** Pure-JS encoder: plain object → full wire frame. Works everywhere. */
+  encodeFrame(name: string, payload: unknown): Uint8Array;
+
+  /** Generated direct fast-path tables (optional — server only). */
+  readonly direct?: DirectTables;
+}
+
+// ── type-level derivation from a concrete Bindings ────────────────────────
+
+export type EventNameOf<B extends Bindings> = Extract<keyof B["events"], string>;
+export type ControlEventNameOf<B extends Bindings> = Extract<keyof B["controlEvents"], string>;
+
+/** Plain-object payload map derived from a bindings' TypeBox schemas. */
+export type EventsOf<B extends Bindings> = {
+  [K in EventNameOf<B>]: Static<B["events"][K]>;
+};
+export type ControlEventsOf<B extends Bindings> = {
+  [K in ControlEventNameOf<B>]: Static<B["controlEvents"][K]>;
+};
+
+/** The built-in registry's bindings type (see `src/bindings/default.ts`). */
+export type DefaultBindings = typeof import("./default").defaultBindings;

package/src/bridge/nats/inbound.ts

@@ -0,0 +1,46 @@
+/**
+ * Inbound pipeline — the bridge's NATS→clients forward. Subscribes a subject
+ * and, for each arriving frame: reads the envelope header (cheap), rejects
+ * transport-internal control frames and non-allowlisted events, then decodes
+ * the payload and hands `{name, payload}` to the wired `onInbound` callback.
+ *
+ * Decode failures are counted in `stats.bridgeInboundErrors`, never thrown —
+ * the WS hot path must not depend on broker input being well-formed.
+ */
+import type { Bindings } from "../../bindings/types";
+import type { NatsBridgeStats, NatsTransport } from "./types";
+
+export function subscribeInboundSubject(deps: {
+  transport: NatsTransport;
+  bindings: Bindings;
+  stats: NatsBridgeStats;
+  subject: string;
+  /** allowlist; `null` = forward every app event */
+  allowlist: Set<string> | null;
+  /** set once by the server (the fan-out-to-clients callback) */
+  getOnInbound(): ((name: string, payload: unknown) => void) | null;
+}): () => void {
+  const { transport, bindings, stats, subject, allowlist } = deps;
+  return transport.subscribe(subject, (data) => {
+    // header-first: reject junk/control frames before any payload decode
+    const header = bindings.readFrameHeader(data);
+    if (!header) {
+      stats.bridgeInboundErrors++;
+      return;
+    }
+    if (bindings.isControlId(header.id)) {
+      stats.bridgeInboundErrors++; // never forward transport-internal frames
+      return;
+    }
+    if (allowlist && !allowlist.has(header.name)) return;
+    let payload: unknown;
+    try {
+      payload = bindings.decodePayload(header.id, data);
+    } catch {
+      stats.bridgeInboundErrors++;
+      return;
+    }
+    stats.bridgeInbound++;
+    deps.getOnInbound()?.(header.name, payload);
+  });
+}

package/src/bridge/nats/index.ts

@@ -0,0 +1,131 @@
+/**
+ * NATS bridge — bidirectional FlatBuffer transport over NATS (composition
+ * root). Decomposed by concern:
+ *
+ *   types.ts          — options / stats / NatsTransport / NatsBridge contracts
+ *   real-transport.ts — the eager, non-blocking connection with retry loop
+ *   inbound.ts        — the NATS→clients decode + filter pipeline
+ *
+ * OUTBOUND: the server encodes each event ONCE (Rust FFI → scratch), fans the
+ * same frame out to WS clients, then hands a COPY to `bridge.publish(subject,
+ * frame)` so other applications consume the identical wire bytes. Best-effort:
+ * if NATS is down the frame is dropped and counted in `bridgeErrors` — it
+ * never blocks or throws on the WS hot path.
+ *
+ * INBOUND: when `inbound` is enabled the bridge subscribes to `{prefix}.
+ * inbound.>` and forwards decodable app events to `onInbound` (wired by the
+ * server to fan out to clients). Control frames and unknown ids are dropped.
+ *
+ * HORIZONTAL SCALING: when `bridgeClientEvents` is set, the server re-publishes
+ * every accepted client-sent event to `{prefix}.inbound.<event>` so OTHER
+ * server instances (and BE consumers) receive it. Loop prevention: frames that
+ * arrive via NATS are forwarded through `onInbound` and never re-bridged.
+ *
+ * GENERIC: decodes inbound frames with the given `Bindings` (default: the
+ * built-in registry), so the bridge works for ANY schema. Tests can inject an
+ * `NatsTransport` fake — no broker needed in CI.
+ */
+import { defaultBindings } from "../../bindings/default";
+import type { Bindings } from "../../bindings/types";
+import { createSubjectBuilder } from "../subjects";
+import { subscribeInboundSubject } from "./inbound";
+import { createRealTransport } from "./real-transport";
+import type {
+  NatsBridge,
+  NatsBridgeOptions,
+  NatsBridgeStats,
+  NatsBridgeStatus,
+  NatsTransport,
+} from "./types";
+
+export type {
+  NatsBridge,
+  NatsBridgeOptions,
+  NatsBridgeStats,
+  NatsBridgeStatus,
+  NatsTransport,
+} from "./types";
+
+export function createNatsBridge(
+  opts: NatsBridgeOptions = {},
+  transport?: NatsTransport,
+  bindings?: Bindings,
+): NatsBridge {
+  const b = bindings ?? opts.bindings ?? defaultBindings;
+  const t = transport ?? createRealTransport(opts);
+  const subjects = createSubjectBuilder(opts.subjectPrefix ?? b.subjectPrefix ?? "ignex");
+  const stats: NatsBridgeStats = {
+    bridged: 0,
+    bridgedBytes: 0,
+    bridgeErrors: 0,
+    bridgeInbound: 0,
+    bridgeInboundErrors: 0,
+  };
+  let closed = false;
+  let onInbound: ((name: string, payload: unknown) => void) | null = null;
+  // stable accessor (the callback slot is set once by the server later)
+  const getOnInbound = (): ((name: string, payload: unknown) => void) | null => onInbound;
+  const allowlist = opts.inboundEvents ? new Set(opts.inboundEvents) : null;
+
+  // inbound subscriptions (lazy — the transport queues them until connected)
+  const unsubs: Array<() => void> = [];
+  if (opts.inbound) {
+    const subjectsList = opts.inboundSubjects?.length
+      ? opts.inboundSubjects
+      : [subjects.inboundPrefix()];
+    for (const subject of subjectsList) {
+      unsubs.push(
+        subscribeInboundSubject({
+          transport: t,
+          bindings: b,
+          stats,
+          subject,
+          allowlist,
+          getOnInbound,
+        }),
+      );
+    }
+  }
+
+  return {
+    get status(): NatsBridgeStatus {
+      if (closed) return "closed";
+      return t.connected ? "connected" : "connecting";
+    },
+    get subjects() {
+      return subjects;
+    },
+    get stats() {
+      return stats;
+    },
+    get clientEvents(): boolean {
+      return opts.bridgeClientEvents ?? false;
+    },
+    publish(subject, frame) {
+      if (!t.connected) {
+        stats.bridgeErrors++;
+        return;
+      }
+      // the frame view is a reused scratch — copy before handing to NATS
+      const copy = frame.slice();
+      try {
+        t.publish(subject, copy);
+        stats.bridged++;
+        stats.bridgedBytes += copy.byteLength;
+      } catch {
+        stats.bridgeErrors++;
+      }
+    },
+    setOnInbound(cb) {
+      onInbound = cb;
+    },
+    subscribeRaw(subject, cb) {
+      return t.subscribe(subject, (data) => cb(data));
+    },
+    async close() {
+      closed = true;
+      for (const u of unsubs) u();
+      await t.close();
+    },
+  };
+}

package/src/bridge/nats/real-transport.ts

@@ -0,0 +1,133 @@
+/**
+ * Real NATS transport — an eager, non-blocking `NatsConnection` wrapper with
+ * an initial-connect retry loop, so a server can start while NATS is down.
+ *
+ * Subscriptions are RE-SYNCED on every (re)connect: the desired subject set
+ * is kept locally and replayed onto whichever connection is current —
+ * nats.js re-subscribes automatically after a reconnect, but the resync
+ * guards against edge cases (e.g. a replaced connection).
+ */
+import { connect, type NatsConnection } from "nats";
+import type { NatsBridgeOptions, NatsTransport } from "./types";
+
+interface PendingSub {
+  subject: string;
+  cb: (data: Uint8Array) => void;
+}
+
+export function createRealTransport(opts: NatsBridgeOptions): NatsTransport {
+  let nc: NatsConnection | null = null;
+  let connected = false;
+  let closed = false;
+  // desired subscriptions — replayed on every (re)connect via sync()
+  const subs: Array<PendingSub> = [];
+  let unsubs: Array<() => void> = [];
+
+  /** Tear down the current subscription iterators and re-subscribe all. */
+  const sync = (): void => {
+    for (const u of unsubs) u();
+    unsubs = [];
+    if (!nc) return;
+    for (const s of subs) {
+      const sub = nc.subscribe(s.subject);
+      unsubs.push(() => sub.unsubscribe());
+      void (async () => {
+        try {
+          for await (const m of sub) s.cb(new Uint8Array(m.data));
+        } catch {
+          // subscription ended / connection closed
+        }
+      })();
+    }
+  };
+
+  /** Track connection liveness + trigger resyncs from nats.js status events. */
+  const attachStatus = (conn: NatsConnection): void => {
+    void conn
+      .closed()
+      .then(() => {
+        connected = false;
+        if (nc === conn) nc = null;
+      })
+      .catch(() => {
+        connected = false;
+      });
+    void (async () => {
+      try {
+        for await (const st of conn.status()) {
+          if (st.type === "disconnect") connected = false;
+          else if (st.type === "reconnect") {
+            connected = true;
+            sync(); // nats.js re-subscribes automatically; resync to be safe
+          }
+        }
+      } catch {
+        connected = false;
+      }
+    })();
+  };
+
+  let connecting = false;
+  const tryConnect = async (): Promise<void> => {
+    // one attempt at a time; a live connection (even mid-reconnect, which
+    // nats.js drives internally) is never replaced by a duplicate dial
+    if (closed || connecting || nc !== null) return;
+    connecting = true;
+    try {
+      const conn = await connect({
+        servers: opts.servers ?? ["nats://localhost:4222"],
+        ...(opts.token !== undefined ? { token: opts.token } : {}),
+        timeout: opts.connectTimeout ?? 5000,
+        reconnect: opts.reconnect ?? true,
+        maxReconnectAttempts: -1,
+      });
+      nc = conn;
+      connected = true;
+      attachStatus(conn);
+      sync();
+    } catch {
+      connected = false;
+    } finally {
+      connecting = false;
+    }
+  };
+
+  // background retry loop — the caller NEVER awaits a dial
+  void (async () => {
+    while (!closed) {
+      if (nc === null) await tryConnect();
+      await Bun.sleep(opts.connectRetryMs ?? 2000);
+    }
+  })();
+
+  return {
+    get connected() {
+      return connected;
+    },
+    publish(subject, data) {
+      if (!nc) throw new Error("nats: not connected");
+      nc.publish(subject, data);
+    },
+    subscribe(subject, cb) {
+      subs.push({ subject, cb });
+      sync();
+      return () => {
+        const i = subs.findIndex((s) => s.subject === subject && s.cb === cb);
+        if (i >= 0) subs.splice(i, 1);
+        sync();
+      };
+    },
+    async close() {
+      closed = true;
+      if (nc) {
+        try {
+          await nc.close();
+        } catch {
+          // already closed
+        }
+      }
+      nc = null;
+      connected = false;
+    },
+  };
+}

package/src/bridge/nats/types.ts

@@ -0,0 +1,80 @@
+/**
+ * NATS bridge contracts — options, stats, and the transport/bridge surfaces.
+ *
+ * Type + contract module: the runtime lives in `real-transport.ts` (the
+ * eager connection) and `index.ts` (the bridge itself).
+ */
+import type { SubjectBuilder } from "../subjects";
+import type { Bindings } from "../../bindings/types";
+
+export type NatsBridgeStatus = "connected" | "connecting" | "closed";
+
+export interface NatsBridgeOptions {
+  /** NATS servers, default ["nats://localhost:4222"] */
+  servers?: string[];
+  /** subject prefix, default "ignex" (or the bindings' subjectPrefix) */
+  subjectPrefix?: string;
+  /**
+   * The wire stack used to decode inbound frames (default: built-in registry).
+   * Pass your own generated bindings so the bridge decodes YOUR events.
+   */
+  bindings?: Bindings;
+  /** connect timeout (ms), default 5000 */
+  connectTimeout?: number;
+  /** how long to wait before retrying a failed initial connect (ms), default 2000 */
+  connectRetryMs?: number;
+  /** reconnect handled by nats.js (core NATS, no durable queues), default true */
+  reconnect?: boolean;
+  /** optional NATS token (auth) */
+  token?: string;
+  /** subscribe to inbound subjects and forward events to clients, default false */
+  inbound?: boolean;
+  /** inbound subjects (default `{prefix}.inbound.>`), requires `inbound` */
+  inboundSubjects?: string[];
+  /** only forward these inbound events (default: every app event) */
+  inboundEvents?: string[];
+  /**
+   * Re-publish every accepted client-sent event to `{prefix}.inbound.<event>`
+   * so other servers in the cluster (and BE consumers) receive it, default
+   * false. See the horizontal-scaling docs.
+   */
+  bridgeClientEvents?: boolean;
+}
+
+/** Counters folded into `server.getMetrics()`. */
+export interface NatsBridgeStats {
+  bridged: number;
+  bridgedBytes: number;
+  bridgeErrors: number;
+  bridgeInbound: number;
+  bridgeInboundErrors: number;
+}
+
+/** Minimal transport — a real NATS connection or a test fake. */
+export interface NatsTransport {
+  readonly connected: boolean;
+  /** synchronously send bytes; throws when not connected (bridge catches + counts) */
+  publish(subject: string, data: Uint8Array): void;
+  /** subscribe; `cb` receives message bytes; returns an unsubscribe function */
+  subscribe(subject: string, cb: (data: Uint8Array) => void): () => void;
+  close(): Promise<void>;
+}
+
+export interface NatsBridge {
+  readonly status: NatsBridgeStatus;
+  readonly subjects: SubjectBuilder;
+  readonly stats: NatsBridgeStats;
+  /** whether client-sent events are re-published to `{prefix}.inbound.<event>` */
+  readonly clientEvents: boolean;
+  /** publish a frame to `subject` (copies the bytes — safe after scratch reuse) */
+  publish(subject: string, frame: Uint8Array): void;
+  /**
+   * Raw byte subscription (used by the events cluster layer). Unlike the
+   * inbound path this does NOT decode or forward — bytes are handed to `cb`
+   * verbatim, re-subscribed automatically after a NATS reconnect.
+   */
+  subscribeRaw(subject: string, cb: (data: Uint8Array) => void): () => void;
+  /** wire the inbound → clients forward (set once by the server) */
+  setOnInbound(cb: (name: string, payload: unknown) => void): void;
+  close(): Promise<void>;
+}

package/src/bridge/subjects.ts

@@ -18,6 +18,8 @@ export interface SubjectBuilder {
   group(group: string, name: string): string;
   /** wildcard subject the server subscribes to for inbound events */
   inboundPrefix(): string;
+  /** concrete inbound subject for one event — used to re-publish client events into the cluster */
+  inboundEvent(name: string): string;
 }
 
 export function createSubjectBuilder(prefix = "ignex"): SubjectBuilder {
@@ -26,5 +28,6 @@ export function createSubjectBuilder(prefix = "ignex"): SubjectBuilder {
     topic: (topic, name) => `${prefix}.topic.${topic}.${name}`,
     group: (group, name) => `${prefix}.group.${group}.${name}`,
     inboundPrefix: () => `${prefix}.inbound.>`,
+    inboundEvent: (name) => `${prefix}.inbound.${name}`,
   };
 }

package/src/codegen/constants.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared wire-format constants. These are the SINGLE source of truth for the
+ * transport envelope — every emitter (TS registry, Rust glue, direct serde)
+ * imports them so the TS and Rust sides stay in sync by construction.
+ *
+ * The Rust `fb_wire_version()` export is checked against `WIRE_VERSION` at
+ * bind time (`src/native/ffi.ts`) to catch any drift between a stale cdylib
+ * and the generated artifacts.
+ */
+
+/** Wire format version. Bump on any BREAKING envelope change. */
+export const WIRE_VERSION = 2;
+
+/**
+ * Envelope header length in bytes:
+ *   [version:1][event_id:u32 LE][flags:1][seq:u64 LE]
+ * The size-prefixed FlatBuffer payload follows immediately after.
+ *
+ * `flags` bit0 = seq-valid: the server stamps a per-CONNECTION delivery seq on
+ * every frame it writes to a socket (mutated in place just before `ws.send`,
+ * which copies). Clients use it for gap detection + resume. Frames that were
+ * not per-destination stamped (client-encoded, replay history copies before
+ * stamping) carry flags=0 / seq=0.
+ */
+export const WIRE_HEADER_LEN = 14;
+
+/** flags bit: `seq` field carries a valid per-connection delivery sequence. */
+export const WIRE_FLAG_SEQ = 1;