@ignex/nova 0.1.3 → 0.1.5

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/codegen/constants.ts

@@ -9,10 +9,20 @@
  */
 
 /** Wire format version. Bump on any BREAKING envelope change. */
-export const WIRE_VERSION = 1;
+export const WIRE_VERSION = 2;
 
 /**
- * Envelope header length in bytes: `[version:1][event_id:u32 LE]`. The
- * size-prefixed FlatBuffer payload follows immediately after.
+ * 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 = 5;
+export const WIRE_HEADER_LEN = 14;
+
+/** flags bit: `seq` field carries a valid per-connection delivery sequence. */
+export const WIRE_FLAG_SEQ = 1;

package/src/codegen/direct-gen.ts

@@ -29,7 +29,13 @@ import { isDirectableEvent, plainTsType, toSnake } from "./schema-model";
 export function emitDirectSer(m: Model, ctx: EmitContext = {}): string {
   const directEvents = m.events.filter((ev) => isDirectableEvent(m, ev));
   const userMode = ctx.schemaImport === null;
-  const libImport = userMode ? (ctx.libraryImport ?? "@ignex/nova") : "";
+  let libImport = "";
+  if (userMode) {
+    libImport =
+      ctx.libraryImport === undefined || ctx.libraryImport === "@ignex/nova"
+        ? "@ignex/nova/internal"
+        : ctx.libraryImport;
+  }
 
   const enumConsts = new Map<string, string>(); // enumName -> const name
   for (const e of m.enums) {
@@ -71,7 +77,9 @@ export function emitDirectSer(m: Model, ctx: EmitContext = {}): string {
   for (const ev of directEvents) {
     const fields = fieldsOf(m, ev);
     const args = fields.flatMap(directArgTypes).concat("ptr", "usize");
-    lines.push(`  ${directSymbol(ev)}: {`);
+    // Quote the key — dotted event names ("chat.send") would otherwise emit
+    // an invalid identifier (`fb_chat.send_serialize:`).
+    lines.push(`  ${JSON.stringify(directSymbol(ev))}: {`);
     lines.push(`    args: [${args.map((a) => JSON.stringify(a)).join(", ")}],`);
     lines.push('    returns: "u64_fast",');
     lines.push("  },");
@@ -200,12 +208,12 @@ export function emitDirectSer(m: Model, ctx: EmitContext = {}): string {
   lines.push(
     "export const hasNulEncoders: Partial<Record<AnyEventName, (o: unknown) => boolean>> = {",
   );
-  for (const ev of directEvents) lines.push(`  ${ev.name}: hasNul${pascal(ev.name)},`);
+  for (const ev of directEvents) lines.push(`  ${JSON.stringify(ev.name)}: hasNul${pascal(ev.name)},`);
   lines.push("};");
   lines.push("");
 
   lines.push("export const directSymbolNames: Partial<Record<AnyEventName, string>> = {");
-  for (const ev of directEvents) lines.push(`  ${ev.name}: ${JSON.stringify(directSymbol(ev))},`);
+  for (const ev of directEvents) lines.push(`  ${JSON.stringify(ev.name)}: ${JSON.stringify(directSymbol(ev))},`);
   lines.push("};");
   lines.push("");
   lines.push(
@@ -213,7 +221,7 @@ export function emitDirectSer(m: Model, ctx: EmitContext = {}): string {
   );
   lines.push("");
   lines.push("export const directEncoders: Partial<Record<AnyEventName, DirectEncoder>> = {");
-  for (const ev of directEvents) lines.push(`  ${ev.name}: encode${pascal(ev.name)},`);
+  for (const ev of directEvents) lines.push(`  ${JSON.stringify(ev.name)}: encode${pascal(ev.name)},`);
   lines.push("};");
   lines.push("");
 
@@ -546,5 +554,11 @@ function scalarVecWrite(f: FieldDef, item: string, enumConsts: Map<string, strin
 }
 
 function pascal(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+  // "chat.send" → "ChatSend": split on non-alphanumerics so event names with
+  // dots/hyphens still produce valid identifiers (encodeChatSendPayload...).
+  return s
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
 }

package/src/codegen/registry-gen.ts

@@ -39,9 +39,13 @@ export function emitRegistry(m: Model, fingerprint: number, ctx: EmitContext = {
 
   const userMode = ctx.schemaImport === null;
   const schemaImport = userMode ? "" : (ctx.schemaImport ?? "../schema");
-  const poolImport = userMode
-    ? (ctx.libraryImport ?? "@ignex/nova")
-    : "../transport/byte-buffer-pool";
+  let poolImport = "../transport/byte-buffer-pool";
+  if (userMode) {
+    poolImport =
+      ctx.libraryImport === undefined || ctx.libraryImport === "@ignex/nova"
+        ? "@ignex/nova/internal"
+        : ctx.libraryImport;
+  }
 
   const lines: string[] = [];
   lines.push("// @ts-nocheck — generated file: not subject to hand-typed strictness gates");
@@ -72,17 +76,17 @@ export function emitRegistry(m: Model, fingerprint: number, ctx: EmitContext = {
   if (userMode) lines.push(...emitLocalTypes(m, neededTables, appEvents, controlEvents));
   lines.push("export const eventNameToId: Record<EventName, number> = {");
   for (const ev of appEvents)
-    lines.push(`  ${ev.name}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
+    lines.push(`  ${JSON.stringify(ev.name)}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
   lines.push("};");
   lines.push("");
   lines.push("export const controlEventNameToId: Record<ControlEventName, number> = {");
   for (const ev of controlEvents)
-    lines.push(`  ${ev.name}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
+    lines.push(`  ${JSON.stringify(ev.name)}: ${eventId(ev.name)}, // fnv1a32("${ev.name}")`);
   lines.push("};");
   lines.push("");
   lines.push("/** merged app + control registry (used by encodeToScratch / JS encoder). */");
   lines.push("export const anyEventNameToId: Record<string, number> = {");
-  for (const ev of m.events) lines.push(`  ${ev.name}: ${eventId(ev.name)},`);
+  for (const ev of m.events) lines.push(`  ${JSON.stringify(ev.name)}: ${eventId(ev.name)},`);
   lines.push("};");
   lines.push("");
   lines.push("export const idToEventName: Record<number, EventName> = {");

package/src/codegen/rust-glue-gen.ts

@@ -368,6 +368,9 @@ function emitDirectFn(m: Model, ev: EventDef): string {
   const table = m.tables.find((t) => t.name === ev.tableName)!;
   const id = eventId(ev.name);
   const snake = toSnake(ev.name);
+  // Dotted event names ("chat.send") must not leak into the Rust fn
+  // identifier — keep the C-ABI symbol exact via #[export_name] instead.
+  const fnId = snake.replace(/[^a-zA-Z0-9_]/g, "_");
   const decls = table.fields.map(directArgDecl).join("\n    ");
   const decodes = table.fields
     .map(directDecodeLines)
@@ -379,8 +382,8 @@ function emitDirectFn(m: Model, ev: EventDef): string {
     .join("\n            ");
   const assigns = table.fields.map(directArgAssign).join("\n                ");
   return [
-    `#[no_mangle]`,
-    `pub unsafe extern "C" fn fb_${snake}_serialize(`,
+    `#[export_name = "fb_${snake}_serialize"]`,
+    `pub unsafe extern "C" fn fb_${fnId}_serialize(`,
     `    ${decls}`,
     `    out: *mut u8,`,
     `    out_cap: usize,`,
@@ -409,6 +412,10 @@ function emitDirectFn(m: Model, ev: EventDef): string {
     `                    *out.add(0) = WIRE_VERSION;`,
     `                    let id_bytes = ${id}u32.to_le_bytes();`,
     `                    std::ptr::copy_nonoverlapping(id_bytes.as_ptr(), out.add(1), 4);`,
+    `                    // [flags:1][seq:u64 LE] — pristine (flags=0, seq=0); the`,
+    `                    // server stamps per-destination delivery seqs on send.`,
+    `                    *out.add(5) = 0;`,
+    `                    std::ptr::write_bytes(out.add(6), 0, 8);`,
     `                }`,
     `                needed`,
     `            }`,
@@ -444,7 +451,7 @@ export function emitRustGlue(m: Model, fingerprint: number): string {
   lines.push("");
   lines.push(`pub const WIRE_VERSION: u8 = ${WIRE_VERSION};`);
   lines.push(
-    `pub const WIRE_HEADER_LEN: usize = ${WIRE_HEADER_LEN}; // [version:1][event_id:u32 LE]`,
+    `pub const WIRE_HEADER_LEN: usize = ${WIRE_HEADER_LEN}; // [version:1][event_id:u32 LE][flags:1][seq:u64 LE]`,
   );
   lines.push(`pub const SCHEMA_FINGERPRINT: u64 = ${fingerprint}; // fnv1a32(canonical model)`);
   lines.push("");

package/src/codegen/schema-model.ts

@@ -199,6 +199,17 @@ function ensureTable(ctx: Ctx, schema: AnySchema, fallbackName: string): string
   return name;
 }
 
+/**
+ * Error for TypeBox field kinds that have no FlatBuffers representation. These
+ * used to be silently coerced to `string` fields (which forced JSON.stringify
+ * on the app side and put raw JSON text on the wire) — fail loudly instead.
+ */
+function unsupportedFieldType(parentName: string, jsonName: string, reason: string): Error {
+  return new Error(
+    `generateBindings: field "${jsonName}" in "${parentName}" has no FlatBuffers representation (${reason}) — model it explicitly: Type.String() for a JSON payload, a typed object/table, or a flat scalar/vector type`,
+  );
+}
+
 function resolveFieldType(
   ctx: Ctx,
   schema: AnySchema,
@@ -216,7 +227,11 @@ function resolveFieldType(
       const tableName = ensureTable(ctx, tableMember, `${parentName}${toPascal(jsonName)}`);
       return { kind: "table", tableName };
     }
-    return { kind: "string" };
+    throw unsupportedFieldType(
+      parentName,
+      jsonName,
+      "union of mixed members (only string-literal enums and single-object unions are supported)",
+    );
   }
 
   switch (schema.type) {
@@ -262,12 +277,22 @@ function resolveFieldType(
       }
     }
     case "object": {
-      if (!isObjectLike(schema)) return { kind: "string" };
+      if (!isObjectLike(schema)) {
+        throw unsupportedFieldType(
+          parentName,
+          jsonName,
+          "dynamic-key object (Type.Record / additionalProperties) has no FlatBuffers table representation",
+        );
+      }
       const tableName = ensureTable(ctx, schema, `${parentName}${toPascal(jsonName)}`);
       return { kind: "table", tableName };
     }
     default:
-      return { kind: "string" };
+      throw unsupportedFieldType(
+        parentName,
+        jsonName,
+        `unrecognized TypeBox type ${schema.type === undefined ? "(Type.Any()/Type.Unknown()?)" : `"${String(schema.type)}"`}`,
+      );
   }
 }
 

package/src/codegen/ts-ser-gen.ts

@@ -122,7 +122,7 @@ export function emitTsSer(m: Model, ctx: EmitContext = {}): string {
   lines.push("");
   lines.push("export const jsEncoders: Record<string, JsEncoder> = {");
   for (const ev of m.events)
-    lines.push(`  ${ev.name}: encode${pascal(ev.name)}Payload as JsEncoder,`);
+    lines.push(`  ${JSON.stringify(ev.name)}: encode${pascal(ev.name)}Payload as JsEncoder,`);
   lines.push("};");
   lines.push("");
   lines.push("/** Encode a payload (app or control event) → size-prefixed FlatBuffer. */");
@@ -135,7 +135,7 @@ export function emitTsSer(m: Model, ctx: EmitContext = {}): string {
   lines.push("}");
   lines.push("");
   lines.push(
-    "/** Encode a payload into a full wire frame `[version][event_id:u32][size-prefixed FB]`. */",
+    "/** Encode a payload into a full wire frame `[version][event_id:u32][flags:1][seq:u64 LE][size-prefixed FB]`. */",
   );
   lines.push(
     "export function encodeEventFrame(name: AnyEventName, o: unknown, b?: flatbuffers.Builder): Uint8Array {",
@@ -145,6 +145,9 @@ export function emitTsSer(m: Model, ctx: EmitContext = {}): string {
   lines.push("  const frame = new Uint8Array(WIRE_HEADER_LEN + payload.byteLength);");
   lines.push("  frame[0] = WIRE_VERSION;");
   lines.push("  new DataView(frame.buffer).setUint32(1, id, true);");
+  lines.push("  // pristine delivery header (flags=0, seq=0) — client-sent frames are not stamped");
+  lines.push("  frame[WIRE_HEADER_LEN - 9] = 0;");
+  lines.push("  new DataView(frame.buffer).setBigUint64(WIRE_HEADER_LEN - 8, 0n, true);");
   lines.push("  frame.set(payload, WIRE_HEADER_LEN);");
   lines.push("  return frame;");
   lines.push("}");
@@ -217,5 +220,11 @@ function ctorArg(f: FieldDef, o: string): string {
 }
 
 function pascal(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+  // "chat.send" → "ChatSend": split on non-alphanumerics so event names with
+  // dots/hyphens still produce valid identifiers (encodeChatSendPayload...).
+  return s
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
 }