@ignex/nova 0.1.1 → 0.1.3

package/src/codegen/direct-gen.ts

@@ -0,0 +1,550 @@
+import type { EmitContext, EventDef, FieldDef, Model } from "./schema-model";
+import { isDirectableEvent, plainTsType, toSnake } from "./schema-model";
+
+/**
+ * Emits `src/generated/direct-ser.ts` — the Bun-side of the zero-allocation direct
+ * fast path. For every DIRECTABLE event type (flat, or with packed vectors of
+ * flat elements) it generates:
+ *   - `directSymbols`: `dlopen` specs in CANONICAL form. Strings are `cstring`
+ *     ARGs (the engine transcodes them in-engine — zero JS encode, and Rust
+ *     borrows via `CStr::from_ptr` with no `from_utf8` validation); vectors are
+ *     `(buffer, usize)` of a packed binary blob; out is `(ptr, usize)` —
+ *     upgraded to the `(buffer, buffer_length)` atomic pair at bind time by the
+ *     `abi()` transformer in `src/native/ffi.ts` when the Bun build supports
+ *     it. NO JSON.
+ *   - `directEncoders`: per-event fns that push the object's fields straight
+ *     into the (reusable) out buffer — no intermediate args array.
+ *   - `directSymbolNames`: event → FFI symbol name.
+ *   - `directSamples` + `directSelfTest`: per-event sample vectors and a
+ *     bind-time self-test that verifies each direct symbol's frame layout
+ *     (`out[0]` event id + size-prefix invariant) — a signature drift fails at
+ *     bind, not under load. Returns the list of disabled symbols.
+ *   - per-enum index lookup consts (string enum → u32).
+ *
+ * `ctx.schemaImport === null` (user-mode codegen) emits self-contained local
+ * payload types + imports the runtime helpers from `ctx.libraryImport`
+ * (default `"ignex-nova"`) instead of the repo's relative modules.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: string-emitting codegen is inherently branchy
+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") : "";
+
+  const enumConsts = new Map<string, string>(); // enumName -> const name
+  for (const e of m.enums) {
+    if (
+      directEvents.some((ev) => fieldsOf(m, ev).some((f) => isEnumKind(f) && f.enumName === e.name))
+    ) {
+      enumConsts.set(e.name, `${toSnake(e.name).toUpperCase()}`);
+    }
+  }
+
+  // payload interfaces needed by the direct encoders (event roots + flat
+  // vector-table elements) in user mode
+  const directTables = collectDirectTables(m, directEvents);
+
+  const lines: string[] = [];
+  lines.push("// @ts-nocheck — generated file: not subject to hand-typed strictness gates");
+  lines.push("// @generated by src/codegen/direct-gen.ts — DO NOT EDIT");
+  if (userMode) {
+    lines.push(
+      `import { encodeUtf8Into, ensureCapacity, utf8Len, checkInt64 } from ${JSON.stringify(libImport)};`,
+    );
+  } else {
+    lines.push('import { encodeUtf8Into, ensureCapacity, utf8Len } from "../native/codec";');
+    lines.push('import { checkInt64 } from "../core/int64-guard";');
+  }
+  lines.push('import { anyEventNameToId, WIRE_VERSION, WIRE_HEADER_LEN } from "./registry";');
+  if (!userMode) {
+    lines.push('import type { AnyEventName, ControlEvents, Events } from "../schema";');
+  }
+  lines.push("");
+  if (userMode) lines.push(...emitLocalTypes(m, directTables, directEvents));
+  lines.push("export type DirectCall = (...args: unknown[]) => number;");
+  lines.push("");
+
+  lines.push("/** dlopen specs for the direct fast-path symbols (canonical form — the");
+  lines.push(" * output tail `(ptr, usize)` is upgraded to `(buffer, buffer_length)` by");
+  lines.push(" * the `abi()` transformer in `src/native/ffi.ts` when supported). */");
+  lines.push("export const directSymbols = {");
+  for (const ev of directEvents) {
+    const fields = fieldsOf(m, ev);
+    const args = fields.flatMap(directArgTypes).concat("ptr", "usize");
+    lines.push(`  ${directSymbol(ev)}: {`);
+    lines.push(`    args: [${args.map((a) => JSON.stringify(a)).join(", ")}],`);
+    lines.push('    returns: "u64_fast",');
+    lines.push("  },");
+  }
+  lines.push("} as const;");
+  lines.push("");
+
+  lines.push("/** sample objects for the bind-time self-test (representative values). */");
+  lines.push("const directSamples: Record<string, unknown> = {");
+  for (const ev of directEvents) {
+    const fields = fieldsOf(m, ev);
+    const vals = fields
+      .map((f) => `${JSON.stringify(f.jsonName)}: ${sampleValue(m, f)}`)
+      .join(", ");
+    lines.push(`  ${JSON.stringify(ev.name)}: { ${vals} },`);
+  }
+  lines.push("} as const;");
+  lines.push("");
+
+  const needsVector = directEvents.some((ev) => fieldsOf(m, ev).some((f) => isVectorKind(f.kind)));
+  if (needsVector) {
+    lines.push("/** grow the packer scratch, write the u32 count, return the DataView. */");
+    lines.push(
+      "function packHeader(holder: { v: Uint8Array }, dv: { v: DataView }, total: number, count: number): DataView {",
+    );
+    lines.push(
+      "  if (holder.v.byteLength < total) { holder.v = ensureCapacity(holder.v, total); dv.v = new DataView(holder.v.buffer); }",
+    );
+    lines.push("  const b = dv.v;");
+    lines.push("  b.setUint32(0, count, true);");
+    lines.push("  return b;");
+    lines.push("}");
+    lines.push("");
+  }
+
+  for (const [enumName, constName] of enumConsts) {
+    const e = m.enums.find((e) => e.name === enumName)!;
+    const entries = e.values.map((v) => `${v}: ${e.values.indexOf(v)}`).join(", ");
+    lines.push(`const ${constName} = { ${entries} } as const;`);
+  }
+  if (enumConsts.size > 0) lines.push("");
+
+  for (const ev of directEvents) {
+    const fields = fieldsOf(m, ev);
+    for (const f of fields) {
+      if (isVectorKind(f.kind)) {
+        lines.push(`const ${holderName(ev, f)} = { v: new Uint8Array(1024) };`);
+        lines.push(`const ${dvName(ev, f)} = { v: new DataView(${holderName(ev, f)}.v.buffer) };`);
+      }
+    }
+    for (const f of fields) {
+      if (isVectorKind(f.kind)) lines.push(...emitPacker(m, ev, f, enumConsts));
+    }
+    lines.push("/** zero-alloc encoder: fields straight into the (reusable) out buffer. */");
+    lines.push(
+      `export function encode${pascal(ev.name)}(call: DirectCall, o: unknown, out: Uint8Array): number {`,
+    );
+    lines.push(
+      `  const p = o as ${ev.control ? "ControlEvents" : "Events"}[${JSON.stringify(ev.name)}];`,
+    );
+    for (const f of fields) {
+      if (f.kind === "int64" && !f.bigint) {
+        // lossless-int64 guard (no-op unless enabled — see src/int64-guard.ts)
+        lines.push(`  checkInt64(${JSON.stringify(`${ev.name}.${f.jsonName}`)}, p.${f.jsonName});`);
+      }
+      const prep = prepLines(ev, f);
+      if (prep) lines.push(`  ${prep}`);
+    }
+    const args = fields.map((f) => argExpr(ev, f, enumConsts)).join(", ");
+    lines.push(`  return call(${args}, out, out) as number;`);
+    lines.push("}");
+    lines.push("");
+  }
+
+  // per-direct-event NUL pre-scan — route payloads containing an embedded NUL
+  // to the JSON path (the `cstring` direct path would silently truncate them).
+  for (const ev of directEvents) {
+    const table = m.tables.find((t) => t.name === ev.tableName)!;
+    const checks: string[] = [];
+    const add = (expr: string) => checks.push(`    ${expr}`);
+    for (const f of table.fields) {
+      const j = f.jsonName;
+      switch (f.kind) {
+        case "string":
+          add(`(typeof p.${j} === "string" && p.${j}.includes("\\0"))`);
+          break;
+        case "vector-string":
+          add(`(p.${j} ?? []).some((s) => typeof s === "string" && s.includes("\\0"))`);
+          break;
+        case "vector-table": {
+          const elem = m.tables.find((e) => e.name === f.tableName)!;
+          for (const ef of elem.fields) {
+            if (ef.kind === "string") {
+              add(
+                `(p.${j} ?? []).some((e) => typeof e.${ef.jsonName} === "string" && e.${ef.jsonName}.includes("\\0"))`,
+              );
+            } else if (ef.kind === "vector-string") {
+              add(
+                `(p.${j} ?? []).some((e) => (e.${ef.jsonName} ?? []).some((s) => typeof s === "string" && s.includes("\\0")))`,
+              );
+            }
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    lines.push(`function hasNul${pascal(ev.name)}(o: unknown): boolean {`);
+    lines.push(
+      `  const p = o as ${ev.control ? "ControlEvents" : "Events"}[${JSON.stringify(ev.name)}];`,
+    );
+    if (checks.length === 0) {
+      lines.push("  return false;");
+    } else {
+      lines.push("  return (");
+      lines.push(checks.join(" ||\n"));
+      lines.push("  );");
+    }
+    lines.push("}");
+    lines.push("");
+  }
+  lines.push(
+    "/** per-event NUL pre-scan — true routes the payload to the JSON path (cstring truncates `\\0`). */",
+  );
+  lines.push(
+    "export const hasNulEncoders: Partial<Record<AnyEventName, (o: unknown) => boolean>> = {",
+  );
+  for (const ev of directEvents) lines.push(`  ${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))},`);
+  lines.push("};");
+  lines.push("");
+  lines.push(
+    "export type DirectEncoder = (call: DirectCall, o: unknown, out: Uint8Array) => number;",
+  );
+  lines.push("");
+  lines.push("export const directEncoders: Partial<Record<AnyEventName, DirectEncoder>> = {");
+  for (const ev of directEvents) lines.push(`  ${ev.name}: encode${pascal(ev.name)},`);
+  lines.push("};");
+  lines.push("");
+
+  lines.push("/**");
+  lines.push(" * Bind-time self-test for the direct fast-path symbols. Encodes each");
+  lines.push(" * sample into `scratch` and verifies the frame invariant");
+  lines.push(" * `out[0]` = WIRE_VERSION, `out[1..5]` = event id AND");
+  lines.push(" * `bytes_written === WIRE_HEADER_LEN + 4 + size_prefix`");
+  lines.push(" * (envelope header + 4-byte size prefix + flatbuffer). A signature drift,");
+  lines.push(" * ABI mismatch, or encoder bug surfaces here instead of under load.");
+  lines.push(" * Returns the list of symbol names to DISABLE (route via JSON path).");
+  lines.push(" *");
+  lines.push(" * `raw` must be the adapted symbol map (mode-aware) from ffi.ts.");
+  lines.push(" */");
+  lines.push(
+    "export function directSelfTest(raw: Record<string, (...args: unknown[]) => number>, scratch: Uint8Array): string[] {",
+  );
+  lines.push("  const disabled: string[] = [];");
+  lines.push("  const dv = new DataView(scratch.buffer, scratch.byteOffset, scratch.byteLength);");
+  lines.push("  for (const [name, sample] of Object.entries(directSamples)) {");
+  lines.push("    const symName = directSymbolNames[name as AnyEventName];");
+  lines.push("    const enc = directEncoders[name as AnyEventName];");
+  lines.push("    if (!symName || !enc) continue;");
+  lines.push("    const call = raw[symName];");
+  lines.push("    if (!call) { disabled.push(symName); continue; }");
+  lines.push("    try {");
+  lines.push("      const w = enc(call, sample, scratch) as number;");
+  lines.push("      if (w === 0) { disabled.push(symName); continue; }");
+  lines.push("      if (w > scratch.byteLength) continue; // needed-size path — not a failure");
+  lines.push("      const size = dv.getUint32(scratch.byteOffset + WIRE_HEADER_LEN, true);");
+  lines.push("      const gotId = dv.getUint32(scratch.byteOffset + 1, true);");
+  lines.push(
+    "      if (scratch[0] !== WIRE_VERSION || gotId !== anyEventNameToId[name] || w !== WIRE_HEADER_LEN + 4 + size) disabled.push(symName);",
+  );
+  lines.push("    } catch {");
+  lines.push("      disabled.push(symName);");
+  lines.push("    }");
+  lines.push("  }");
+  lines.push("  return disabled;");
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/** Local payload types for the direct encoders (user-mode codegen). */
+function emitLocalTypes(
+  m: Model,
+  tables: Model["tables"],
+  directEvents: Model["events"],
+): string[] {
+  const lines: string[] = [];
+  for (const t of tables) {
+    lines.push(`export interface ${t.name}Payload {`);
+    for (const f of t.fields)
+      lines.push(`  ${f.jsonName}${f.required ? "" : "?"}: ${plainTsType(m, f)};`);
+    lines.push("}");
+    lines.push("");
+  }
+  const appNames = directEvents
+    .filter((e) => !e.control)
+    .map((e) => `"${e.name}"`)
+    .join(" | ");
+  const ctlNames = directEvents
+    .filter((e) => e.control)
+    .map((e) => `"${e.name}"`)
+    .join(" | ");
+  lines.push(`export type EventName = ${appNames};`);
+  lines.push(`export type ControlEventName = ${ctlNames};`);
+  lines.push(`export type AnyEventName = EventName | ControlEventName;`);
+  lines.push("");
+  lines.push("export type Events = {");
+  for (const ev of directEvents.filter((e) => !e.control))
+    lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Payload;`);
+  lines.push("};");
+  lines.push("export type ControlEvents = {");
+  for (const ev of directEvents.filter((e) => e.control))
+    lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Payload;`);
+  lines.push("};");
+  lines.push("");
+  return lines;
+}
+
+/** Tables referenced by the direct encoders (event roots + flat vector-table elements). */
+function collectDirectTables(m: Model, directEvents: EventDef[]): Model["tables"] {
+  const needed = new Set<string>();
+  const visit = (name: string) => {
+    if (needed.has(name)) return;
+    needed.add(name);
+    const t = m.tables.find((t) => t.name === name)!;
+    for (const f of t.fields) {
+      if (f.kind === "vector-table") visit(f.tableName!);
+    }
+  };
+  for (const ev of directEvents) visit(ev.tableName);
+  return m.tables.filter((t) => needed.has(t.name));
+}
+
+/** Representative sample value for a field kind (used by the generated self-test). */
+function sampleValue(m: Model, f: FieldDef): string {
+  switch (f.kind) {
+    case "string":
+      return JSON.stringify("SELFTEST");
+    case "double":
+      return "1.5";
+    case "int64":
+      return "123456";
+    case "bool":
+      return "true";
+    case "enum":
+      return JSON.stringify(m.enums.find((e) => e.name === f.enumName)!.values[0]);
+    case "vector-double":
+      return "[1.5, 2.5]";
+    case "vector-int64":
+      return "[10, 20]";
+    case "vector-bool":
+      return "[true, false]";
+    case "vector-enum":
+      return `[${JSON.stringify(m.enums.find((e) => e.name === f.enumName)!.values[0])}]`;
+    case "vector-string":
+      return '["a", "b"]';
+    case "vector-table": {
+      const t = m.tables.find((t) => t.name === f.tableName)!;
+      const fields = t.fields
+        .map((ef) => `${JSON.stringify(ef.jsonName)}: ${sampleValue(m, ef)}`)
+        .join(", ");
+      return `[{ ${fields} }]`;
+    }
+    default:
+      throw new Error(`direct sample: unsupported field kind ${f.kind}`);
+  }
+}
+
+function fieldsOf(m: Model, ev: EventDef): FieldDef[] {
+  return m.tables.find((t) => t.name === ev.tableName)!.fields;
+}
+
+function directSymbol(ev: EventDef): string {
+  return `fb_${toSnake(ev.name)}_serialize`;
+}
+
+function isEnumKind(f: FieldDef): boolean {
+  return f.kind === "enum" || f.kind === "vector-enum";
+}
+
+function isVectorKind(kind: string): boolean {
+  return [
+    "vector-table",
+    "vector-string",
+    "vector-double",
+    "vector-int64",
+    "vector-bool",
+    "vector-enum",
+  ].includes(kind);
+}
+
+function directArgTypes(f: FieldDef): string[] {
+  switch (f.kind) {
+    case "string":
+      // cstring ARG — the engine transcodes the JS string in-engine.
+      return ["cstring"];
+    case "vector-table":
+    case "vector-string":
+    case "vector-double":
+    case "vector-int64":
+    case "vector-bool":
+    case "vector-enum":
+      return ["buffer", "usize"];
+    case "double":
+      return ["f64"];
+    case "int64":
+      return ["i64"];
+    case "bool":
+      return ["u8"];
+    case "enum":
+      return ["u32"];
+    default:
+      throw new Error(`direct-args: unsupported field kind ${f.kind}`);
+  }
+}
+
+function holderName(ev: EventDef, f: FieldDef): string {
+  return `${toSnake(ev.name)}_${f.fbName}Holder`;
+}
+
+function dvName(ev: EventDef, f: FieldDef): string {
+  return `${toSnake(ev.name)}_${f.fbName}Dv`;
+}
+
+/** statement(s) before the call — packing a vector (strings cross as cstring args). */
+function prepLines(ev: EventDef, f: FieldDef): string {
+  const j = f.jsonName;
+  switch (f.kind) {
+    case "string":
+      return ""; // no prep — the JS string crosses directly as a cstring arg
+    default:
+      if (isVectorKind(f.kind)) {
+        return `const ${f.fbName}Len = ${packerName(ev, f)}(p.${j}, ${holderName(ev, f)}, ${dvName(ev, f)});`;
+      }
+      return "";
+  }
+}
+
+function argExpr(ev: EventDef, f: FieldDef, enumConsts: Map<string, string>): string {
+  const j = `p.${f.jsonName}`;
+  const h = holderName(ev, f);
+  switch (f.kind) {
+    case "string":
+      // cstring arg: pass the JS string directly; null/undefined → null (NULL
+      // ptr, Rust treats as absent). Verified empirically: '' is NOT conflated —
+      // Bun passes a non-NULL pointer to an empty NUL-terminated string, so Rust
+      // keeps Some("") and empty-vs-absent round-trips distinctly.
+      return f.required ? j : `${j} ?? null`;
+    case "double":
+    case "int64":
+      return j;
+    case "bool":
+      return `${j} ? 1 : 0`;
+    case "enum":
+      return `${enumConsts.get(f.enumName!)}[${j}]`;
+    default:
+      if (isVectorKind(f.kind)) return `${h}.v, ${f.fbName}Len`;
+      throw new Error(`direct-args: unsupported field kind ${f.kind}`);
+  }
+}
+
+function packerName(ev: EventDef, f: FieldDef): string {
+  return `pack${pascal(ev.name)}${pascal(f.fbName)}`;
+}
+
+/** Emit a packer fn that writes the vector into a growable scratch (zero-alloc). */
+function emitPacker(
+  m: Model,
+  ev: EventDef,
+  f: FieldDef,
+  enumConsts: Map<string, string>,
+): string[] {
+  const fn = packerName(ev, f);
+  const itemsType = `${ev.control ? "ControlEvents" : "Events"}[${JSON.stringify(ev.name)}][${JSON.stringify(f.jsonName)}]`;
+  const lines: string[] = [];
+  lines.push(
+    `function ${fn}(items: ${itemsType}, holder: { v: Uint8Array }, dv: { v: DataView }): number {`,
+  );
+
+  if (f.kind === "vector-table") {
+    const elem = m.tables.find((t) => t.name === f.tableName)!;
+    lines.push(`  let total = 4;`);
+    lines.push(`  for (const p of items) total += ${elem.fields.map(packedSizeExpr).join(" + ")};`);
+    lines.push(`  const b = packHeader(holder, dv, total, items.length);`);
+    lines.push(`  let off = 4;`);
+    lines.push(`  for (const p of items) {`);
+    for (const ef of elem.fields) lines.push(`    ${packedWriteExpr(ef, "p", enumConsts)}`);
+    lines.push(`  }`);
+  } else {
+    const per = (
+      {
+        "vector-double": "8",
+        "vector-int64": "8",
+        "vector-bool": "1",
+        "vector-enum": "4",
+        "vector-string": "0",
+      } as Record<string, string>
+    )[f.kind]!;
+    const sizeExpr = f.kind === "vector-string" ? `4 + utf8Len(x)` : per;
+    lines.push(`  let total = 4;`);
+    lines.push(`  for (const x of items) total += ${sizeExpr};`);
+    lines.push(`  const b = packHeader(holder, dv, total, items.length);`);
+    lines.push(`  let off = 4;`);
+    lines.push(`  for (const x of items) {`);
+    lines.push(`    ${scalarVecWrite(f, "x", enumConsts)}`);
+    lines.push(`  }`);
+  }
+  lines.push(`  return total;`);
+  lines.push(`}`);
+  lines.push("");
+  return lines;
+}
+
+function packedSizeExpr(ef: FieldDef): string {
+  switch (ef.kind) {
+    case "string":
+      return `4 + utf8Len(p.${ef.jsonName})`;
+    case "double":
+    case "int64":
+      return "8";
+    case "bool":
+      return "1";
+    case "enum":
+      return "4";
+    default:
+      throw new Error(`packed element: unsupported field kind ${ef.kind}`);
+  }
+}
+
+function packedWriteExpr(ef: FieldDef, item: string, enumConsts: Map<string, string>): string {
+  const v = `${item}.${ef.jsonName}`;
+  switch (ef.kind) {
+    case "string":
+      return `const ${ef.fbName}L = encodeUtf8Into(${v}, holder.v, off + 4); b.setUint32(off, ${ef.fbName}L, true); off += 4; off += ${ef.fbName}L;`;
+    case "double":
+      return `b.setFloat64(off, ${v}, true); off += 8;`;
+    case "int64":
+      return `b.setInt32(off, ${v} | 0, true); b.setInt32(off + 4, Math.floor(${v} / 0x100000000), true); off += 8;`;
+    case "bool":
+      // NOTE: DataView.setUint8 has NO littleEndian param (8-bit) — do not pass `true`.
+      return `b.setUint8(off, ${v} ? 1 : 0); off += 1;`;
+    case "enum":
+      return `b.setUint32(off, ${enumConsts.get(ef.enumName!)}[${v}], true); off += 4;`;
+    default:
+      throw new Error(`packed element: unsupported field kind ${ef.kind}`);
+  }
+}
+
+function scalarVecWrite(f: FieldDef, item: string, enumConsts: Map<string, string>): string {
+  switch (f.kind) {
+    case "vector-double":
+      return `b.setFloat64(off, ${item}, true); off += 8;`;
+    case "vector-int64":
+      return `b.setInt32(off, ${item} | 0, true); b.setInt32(off + 4, Math.floor(${item} / 0x100000000), true); off += 8;`;
+    case "vector-bool":
+      // NOTE: DataView.setUint8 has NO littleEndian param (8-bit) — do not pass `true`.
+      return `b.setUint8(off, ${item} ? 1 : 0); off += 1;`;
+    case "vector-string":
+      return `const l = encodeUtf8Into(${item}, holder.v, off + 4); b.setUint32(off, l, true); off += 4; off += l;`;
+    case "vector-enum":
+      return `b.setUint32(off, ${enumConsts.get(f.enumName!)}[${item}], true); off += 4;`;
+    default:
+      throw new Error(`scalar vector: unsupported kind ${f.kind}`);
+  }
+}
+
+function pascal(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/codegen/fingerprint.ts

@@ -0,0 +1,44 @@
+/**
+ * Schema fingerprint — a stable FNV-1a 32-bit hash over the CANONICAL model
+ * (event registry + table shapes + enums + wire version). Emitted into BOTH
+ * the generated TS registry (`SCHEMA_FINGERPRINT`) and the generated Rust glue
+ * (`SCHEMA_FINGERPRINT` → exposed as `fb_schema_fingerprint()`), so a cdylib
+ * built from a DIFFERENT schema fails the bind-time self-test instead of
+ * producing frames the client can't decode.
+ *
+ * The value only needs to be stable per schema (any collision would just
+ * produce a false bind failure — harmless); it is NOT security.
+ */
+
+import { fnv1a32 } from "./hash";
+import type { Model } from "./schema-model";
+
+/** Stable comparator: ascending by name. */
+function byName(a: { name: string }, b: { name: string }): number {
+  if (a.name < b.name) return -1;
+  if (a.name > b.name) return 1;
+  return 0;
+}
+
+export function schemaFingerprint(m: Model, wireVersion: number): number {
+  const lines: string[] = [`wire=${wireVersion}`];
+  for (const e of [...m.events].sort(byName)) {
+    lines.push(`event:${e.name}:${e.tableName}:${e.control ? "control" : "app"}`);
+  }
+  for (const t of [...m.tables].sort(byName)) {
+    lines.push(`table:${t.name}`);
+    for (const f of [...t.fields].sort((a, b) => {
+      if (a.fbName < b.fbName) return -1;
+      if (a.fbName > b.fbName) return 1;
+      return 0;
+    })) {
+      lines.push(
+        `  ${f.fbName}:${f.kind}:${f.required}:${f.enumName ?? ""}:${f.tableName ?? ""}:${f.bigint ? "bigint" : ""}`,
+      );
+    }
+  }
+  for (const e of [...m.enums].sort(byName)) {
+    lines.push(`enum:${e.name}=${e.values.join(",")}`);
+  }
+  return fnv1a32(lines.join("\n"));
+}

package/src/codegen/hash.ts

@@ -0,0 +1,25 @@
+/**
+ * Stable event-id hashing. Event ids were previously the insertion order of
+ * the `events` registry — a schema reorder silently changed every id and
+ * broke every connected client. Switching to FNV-1a 32-bit over the event
+ * name makes ids stable across reordering / field additions, which is what a
+ * versioned wire format needs.
+ *
+ * Collisions are astronomically unlikely for a handful of names and are
+ * additionally rejected at generate time (`scripts/generate.ts`).
+ */
+
+/** FNV-1a 32-bit (unsigned) — the standard 32-bit variant, seed 2166136261. */
+export function fnv1a32(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+/** Stable event id for an event name (FNV-1a 32-bit of the name). */
+export function eventId(name: string): number {
+  return fnv1a32(name);
+}