bonescript-compiler 0.5.8 → 0.6.1

package/src/emit_nakama.ts

@@ -1,576 +1,576 @@
-/**
- * BoneScript Nakama Emitter
- *
- * Generates a Nakama TypeScript runtime module from an IRSystem.
- * Output is a self-contained src/index.ts that registers:
- *   - nk.registerRpc()  for every capability  (capability -> RPC)
- *   - nk.registerMatch() for every realtime_service module (channel -> match handler)
- *   - Storage helpers    for every entity/model (entity -> storage object)
- *   - Event hooks        for every event emission (event -> stream send)
- *
- * Deploy with: nakama migrate up && nakama --runtime.path ./build
- * Docs: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/
- */
-
-import * as IR from "./ir";
-import { EmittedFile } from "./emitter";
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-function toSnakeCase(s: string): string {
-  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
-}
-
-function toCamelCase(s: string): string {
-  return s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
-}
-
-function toPascalCase(s: string): string {
-  const c = toCamelCase(s);
-  return c.charAt(0).toUpperCase() + c.slice(1);
-}
-
-const TS_TYPE_MAP: Record<string, string> = {
-  string: "string",
-  uint: "number",
-  int: "number",
-  float: "number",
-  bool: "boolean",
-  timestamp: "string",   // ISO string — Nakama runtime has no Date
-  uuid: "string",
-  bytes: "string",       // base64 in Nakama
-  json: "unknown",
-};
-
-function toTsType(irType: string): string {
-  if (TS_TYPE_MAP[irType]) return TS_TYPE_MAP[irType];
-  const listMatch = irType.match(/^list<(.+)>$/);
-  if (listMatch) return `${toTsType(listMatch[1])}[]`;
-  const setMatch = irType.match(/^set<(.+)>$/);
-  if (setMatch) return `${toTsType(setMatch[1])}[]`;
-  const optMatch = irType.match(/^optional<(.+)>$/);
-  if (optMatch) return `${toTsType(optMatch[1])} | null`;
-  return irType;
-}
-
-// ─── Package.json ─────────────────────────────────────────────────────────────
-
-function emitNakamaPackageJson(system: IR.IRSystem): string {
-  return JSON.stringify({
-    name: toSnakeCase(system.name),
-    version: system.version,
-    private: true,
-    scripts: {
-      build: "npx tsc",
-      dev: "npx tsc --watch",
-    },
-    devDependencies: {
-      "@heroiclabs/nakama-runtime": "1.16.0",
-      typescript: "5.3.3",
-      "ts-node": "10.9.2",
-    },
-  }, null, 2);
-}
-
-// ─── tsconfig.json ────────────────────────────────────────────────────────────
-
-function emitNakamaTsConfig(): string {
-  return JSON.stringify({
-    compilerOptions: {
-      target: "ES2020",
-      module: "commonjs",
-      lib: ["ES2020"],
-      outDir: "./build",
-      rootDir: "./src",
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-    },
-    include: ["src/**/*"],
-    exclude: ["node_modules", "build"],
-  }, null, 2);
-}
-
-// ─── Storage helpers ──────────────────────────────────────────────────────────
-// One collection per entity. Nakama storage: collection/key/userId pattern.
-
-function emitStorageHelpers(system: IR.IRSystem): string {
-  const lines: string[] = [];
-  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
-  lines.push(`// Storage helpers — one Nakama storage collection per entity.`);
-  lines.push(``);
-  lines.push(`const nkRuntime: nkruntime.Nakama = (globalThis as any).__nk;`);
-  lines.push(``);
-
-  for (const mod of system.modules) {
-    for (const model of mod.models) {
-      const collection = toSnakeCase(model.name) + "s";
-      const typeName = toPascalCase(model.name);
-
-      // TypeScript interface
-      lines.push(`export interface ${typeName} {`);
-      for (const field of model.fields) {
-        const nullable = field.nullable ? " | null" : "";
-        lines.push(`  ${field.name}: ${toTsType(field.type)}${nullable};`);
-      }
-      lines.push(`}`);
-      lines.push(``);
-
-      // read
-      lines.push(`export function read${typeName}(nk: nkruntime.Nakama, userId: string, id: string): ${typeName} | null {`);
-      lines.push(`  const objs = nk.storageRead([{ collection: "${collection}", key: id, userId }]);`);
-      lines.push(`  if (objs.length === 0) return null;`);
-      lines.push(`  return JSON.parse(objs[0].value) as ${typeName};`);
-      lines.push(`}`);
-      lines.push(``);
-
-      // write
-      lines.push(`export function write${typeName}(nk: nkruntime.Nakama, userId: string, obj: ${typeName}): void {`);
-      lines.push(`  nk.storageWrite([{`);
-      lines.push(`    collection: "${collection}",`);
-      lines.push(`    key: (obj as any).id ?? userId,`);
-      lines.push(`    userId,`);
-      lines.push(`    value: JSON.stringify(obj),`);
-      lines.push(`    permissionRead: 1,`);
-      lines.push(`    permissionWrite: 0,`);
-      lines.push(`  }]);`);
-      lines.push(`}`);
-      lines.push(``);
-
-      // delete
-      lines.push(`export function delete${typeName}(nk: nkruntime.Nakama, userId: string, id: string): void {`);
-      lines.push(`  nk.storageDelete([{ collection: "${collection}", key: id, userId }]);`);
-      lines.push(`}`);
-      lines.push(``);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-// ─── RPC handlers (capabilities) ─────────────────────────────────────────────
-
-function emitRpcHandlers(system: IR.IRSystem): string {
-  const lines: string[] = [];
-  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
-  lines.push(`// RPC handlers — one nk.registerRpc() per capability.`);
-  lines.push(``);
-  lines.push(`import * as storage from "./storage";`);
-  lines.push(``);
-
-  for (const mod of system.modules) {
-    for (const iface of mod.interfaces) {
-      for (const method of iface.methods) {
-        const rpcId = `${toSnakeCase(mod.name)}/${toSnakeCase(method.name)}`;
-        const fnName = `rpc${toPascalCase(mod.name)}${toPascalCase(method.name)}`;
-
-        lines.push(`// RPC: ${rpcId}`);
-        lines.push(`// Capability: ${method.name} on ${mod.name}`);
-        if (method.preconditions.length > 0) {
-          lines.push(`// Preconditions: ${method.preconditions.map(p => p.description).join(", ")}`);
-        }
-        lines.push(`const ${fnName}: nkruntime.RpcFunction = (`);
-        lines.push(`  ctx: nkruntime.Context,`);
-        lines.push(`  logger: nkruntime.Logger,`);
-        lines.push(`  nk: nkruntime.Nakama,`);
-        lines.push(`  payload: string`);
-        lines.push(`): string => {`);
-
-        // Auth guard
-        if (method.authenticated) {
-          lines.push(`  if (!ctx.userId) {`);
-          lines.push(`    throw Error("Authentication required");`);
-          lines.push(`  }`);
-        }
-
-        // Parse payload
-        if (method.input.length > 0) {
-          const inputType = method.input.map(f => `${f.name}: ${toTsType(f.type)}`).join("; ");
-          lines.push(`  const input: { ${inputType} } = payload ? JSON.parse(payload) : {};`);
-        }
-
-        // Precondition stubs
-        if (method.preconditions.length > 0) {
-          lines.push(``);
-          lines.push(`  // Preconditions`);
-          for (const pre of method.preconditions) {
-            lines.push(`  // CHECK: ${pre.description}`);
-            lines.push(`  // if (!(${pre.expression})) throw Error("Precondition failed: ${pre.description.replace(/"/g, "'")}"); `);
-          }
-        }
-
-        // Effect stubs
-        if (method.effects.length > 0) {
-          lines.push(``);
-          lines.push(`  // Effects`);
-          for (const eff of method.effects) {
-            const op = eff.op === "assign" ? "=" : eff.op === "add" ? "+=" : "-=";
-            lines.push(`  // EFFECT: ${eff.target} ${op} ${eff.value}`);
-          }
-        }
-
-        // Event emissions via Nakama streams
-        if (method.emissions.length > 0) {
-          lines.push(``);
-          lines.push(`  // Event emissions — broadcast to stream subscribers`);
-          for (const ev of method.emissions) {
-            lines.push(`  nk.streamSend(`);
-            lines.push(`    { mode: 1, subject: ctx.userId ?? "", label: "${ev}" },`);
-            lines.push(`    JSON.stringify({ event: "${ev}", actor: ctx.userId, ts: Date.now() }),`);
-            lines.push(`    undefined,`);
-            lines.push(`    true`);
-            lines.push(`  );`);
-          }
-        }
-
-        lines.push(``);
-        lines.push(`  logger.info("rpc_called", "${rpcId}", ctx.userId ?? "anon");`);
-        lines.push(`  return JSON.stringify({ ok: true, action: "${method.name}" });`);
-        lines.push(`};`);
-        lines.push(``);
-
-        // Export the function name and rpc id for registration
-        lines.push(`export const ${fnName}Id = "${rpcId}";`);
-        lines.push(`export { ${fnName} };`);
-        lines.push(``);
-      }
-    }
-  }
-
-  return lines.join("\n");
-}
-
-// ─── Match handler (realtime channels) ───────────────────────────────────────
-
-function emitMatchHandlers(system: IR.IRSystem): string {
-  const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
-  if (realtimeMods.length === 0) return "";
-
-  const lines: string[] = [];
-  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
-  lines.push(`// Match handlers — one per realtime_service module.`);
-  lines.push(``);
-
-  for (const mod of realtimeMods) {
-    const handlerName = `${toCamelCase(mod.name)}MatchHandler`;
-    const matchName = toSnakeCase(mod.name);
-
-    lines.push(`// Match handler for channel: ${mod.name}`);
-    lines.push(`const ${handlerName}: nkruntime.MatchHandler = {`);
-    lines.push(``);
-
-    // matchInit
-    lines.push(`  matchInit(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    params: { [key: string]: string }`);
-    lines.push(`  ): { state: unknown; tickRate: number; label: string } {`);
-    lines.push(`    logger.info("match_init", "${matchName}");`);
-    lines.push(`    return {`);
-    lines.push(`      state: { players: {}, tick: 0 },`);
-    lines.push(`      tickRate: ${mod.config["tick_rate"] ?? 10},`);
-    lines.push(`      label: "${matchName}",`);
-    lines.push(`    };`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchJoinAttempt
-    lines.push(`  matchJoinAttempt(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    presence: nkruntime.Presence,`);
-    lines.push(`    metadata: { [key: string]: any }`);
-    lines.push(`  ): { state: unknown; accept: boolean; rejectMessage?: string } {`);
-    lines.push(`    return { state, accept: true };`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchJoin
-    lines.push(`  matchJoin(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    presences: nkruntime.Presence[]`);
-    lines.push(`  ): { state: unknown } | null {`);
-    lines.push(`    const s = state as any;`);
-    lines.push(`    for (const p of presences) {`);
-    lines.push(`      s.players[p.userId] = { userId: p.userId, sessionId: p.sessionId, joinedAt: Date.now() };`);
-    lines.push(`    }`);
-    lines.push(`    dispatcher.broadcastMessage(1, JSON.stringify({ type: "player_joined", players: Object.keys(s.players) }), null, null, true);`);
-    lines.push(`    return { state: s };`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchLeave
-    lines.push(`  matchLeave(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    presences: nkruntime.Presence[]`);
-    lines.push(`  ): { state: unknown } | null {`);
-    lines.push(`    const s = state as any;`);
-    lines.push(`    for (const p of presences) delete s.players[p.userId];`);
-    lines.push(`    if (Object.keys(s.players).length === 0) return null; // end match`);
-    lines.push(`    return { state: s };`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchLoop
-    lines.push(`  matchLoop(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    messages: nkruntime.MatchMessage[]`);
-    lines.push(`  ): { state: unknown } | null {`);
-    lines.push(`    const s = state as any;`);
-    lines.push(`    s.tick = tick;`);
-    lines.push(`    for (const msg of messages) {`);
-    lines.push(`      // Route incoming messages to capability handlers`);
-    lines.push(`      try {`);
-    lines.push(`        const data = JSON.parse(nk.binaryToString(msg.data));`);
-    lines.push(`        dispatcher.broadcastMessage(msg.opCode, msg.data, null, msg.sender, true);`);
-    lines.push(`      } catch (e) {`);
-    lines.push(`        logger.error("match_message_error", String(e));`);
-    lines.push(`      }`);
-    lines.push(`    }`);
-    lines.push(`    return { state: s };`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchTerminate
-    lines.push(`  matchTerminate(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    graceSeconds: number`);
-    lines.push(`  ): { state: unknown } | null {`);
-    lines.push(`    dispatcher.broadcastMessage(0, JSON.stringify({ type: "match_terminated" }), null, null, true);`);
-    lines.push(`    return null;`);
-    lines.push(`  },`);
-    lines.push(``);
-
-    // matchSignal
-    lines.push(`  matchSignal(`);
-    lines.push(`    ctx: nkruntime.Context,`);
-    lines.push(`    logger: nkruntime.Logger,`);
-    lines.push(`    nk: nkruntime.Nakama,`);
-    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
-    lines.push(`    tick: number,`);
-    lines.push(`    state: unknown,`);
-    lines.push(`    data: string`);
-    lines.push(`  ): { state: unknown; data: string } {`);
-    lines.push(`    return { state, data };`);
-    lines.push(`  },`);
-    lines.push(`};`);
-    lines.push(``);
-    lines.push(`export const ${handlerName}Name = "${matchName}";`);
-    lines.push(`export { ${handlerName} };`);
-    lines.push(``);
-  }
-
-  return lines.join("\n");
-}
-
-// ─── Main entry point (InitModule) ───────────────────────────────────────────
-
-function emitNakamaIndex(system: IR.IRSystem): string {
-  const lines: string[] = [];
-  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
-  lines.push(`// Nakama TypeScript runtime module for: ${system.name}`);
-  lines.push(`// Deploy: copy build/ to Nakama runtime path and restart.`);
-  lines.push(``);
-  lines.push(`import * as rpc from "./rpc";`);
-
-  const hasRealtime = system.modules.some(m => m.kind === "realtime_service");
-  if (hasRealtime) {
-    lines.push(`import * as match from "./match";`);
-  }
-
-  lines.push(``);
-  lines.push(`function InitModule(`);
-  lines.push(`  ctx: nkruntime.Context,`);
-  lines.push(`  logger: nkruntime.Logger,`);
-  lines.push(`  nk: nkruntime.Nakama,`);
-  lines.push(`  initializer: nkruntime.Initializer`);
-  lines.push(`): Error | void {`);
-  lines.push(`  logger.info("init_module", "${system.name} v${system.version}");`);
-  lines.push(``);
-
-  // Register all RPCs
-  const allMethods: { mod: IR.IRModule; method: IR.IRMethod }[] = [];
-  for (const mod of system.modules) {
-    for (const iface of mod.interfaces) {
-      for (const method of iface.methods) {
-        allMethods.push({ mod, method });
-      }
-    }
-  }
-
-  if (allMethods.length > 0) {
-    lines.push(`  // Register RPC handlers`);
-    for (const { mod, method } of allMethods) {
-      const fnName = `rpc${toPascalCase(mod.name)}${toPascalCase(method.name)}`;
-      lines.push(`  initializer.registerRpc(rpc.${fnName}Id, rpc.${fnName});`);
-    }
-    lines.push(``);
-  }
-
-  // Register match handlers
-  if (hasRealtime) {
-    const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
-    lines.push(`  // Register match handlers`);
-    for (const mod of realtimeMods) {
-      const handlerName = `${toCamelCase(mod.name)}MatchHandler`;
-      lines.push(`  initializer.registerMatch(match.${handlerName}Name, match.${handlerName});`);
-    }
-    lines.push(``);
-  }
-
-  lines.push(`  logger.info("init_complete", "${allMethods.length} RPCs, ${hasRealtime ? system.modules.filter(m => m.kind === "realtime_service").length : 0} match handlers");`);
-  lines.push(`}`);
-  lines.push(``);
-  lines.push(`// Required Nakama module export`);
-  lines.push(`(globalThis as any).InitModule = InitModule;`);
-
-  return lines.join("\n");
-}
-
-// ─── README ───────────────────────────────────────────────────────────────────
-
-function emitNakamaReadme(system: IR.IRSystem): string {
-  const rpcs: string[] = [];
-  for (const mod of system.modules) {
-    for (const iface of mod.interfaces) {
-      for (const method of iface.methods) {
-        rpcs.push(`- \`${toSnakeCase(mod.name)}/${toSnakeCase(method.name)}\``);
-      }
-    }
-  }
-  const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
-
-  return `# ${system.name} — Nakama Backend
-
-Generated by BoneScript compiler (target: nakama). Source hash: ${system.source_hash}
-
-## Quick Start
-
-\`\`\`bash
-# Install deps
-npm install
-
-# Build TypeScript -> JS
-npm run build
-
-# Start Nakama with this module
-docker run --rm -v $(pwd)/build:/nakama/data/modules \\
-  heroiclabs/nakama:latest
-\`\`\`
-
-## RPC Endpoints
-
-Call these from any Nakama client SDK:
-
-${rpcs.join("\n")}
-
-## Match Handlers
-
-${realtimeMods.length > 0
-  ? realtimeMods.map(m => `- \`${toSnakeCase(m.name)}\` (tick rate: ${m.config["tick_rate"] ?? 10}/s)`).join("\n")
-  : "_No realtime channels declared._"}
-
-## Storage Collections
-
-${system.modules.flatMap(m => m.models).map(m => `- \`${toSnakeCase(m.name)}s\``).join("\n") || "_No entities declared._"}
-
-## Auth
-
-All authenticated RPCs require a valid Nakama session token.
-Use any Nakama client SDK to authenticate before calling RPCs.
-`;
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────────
-
-export interface NakamaEmittedFile {
-  path: string;
-  content: string;
-  language: "typescript" | "json" | "markdown";
-  source_module: string;
-}
-
-export class NakamaEmitter {
-  emit(system: IR.IRSystem): NakamaEmittedFile[] {
-    const files: NakamaEmittedFile[] = [];
-
-    files.push({
-      path: "package.json",
-      content: emitNakamaPackageJson(system),
-      language: "json",
-      source_module: "root",
-    });
-
-    files.push({
-      path: "tsconfig.json",
-      content: emitNakamaTsConfig(),
-      language: "json",
-      source_module: "root",
-    });
-
-    files.push({
-      path: "src/storage.ts",
-      content: emitStorageHelpers(system),
-      language: "typescript",
-      source_module: "storage",
-    });
-
-    files.push({
-      path: "src/rpc.ts",
-      content: emitRpcHandlers(system),
-      language: "typescript",
-      source_module: "rpc",
-    });
-
-    const matchContent = emitMatchHandlers(system);
-    if (matchContent) {
-      files.push({
-        path: "src/match.ts",
-        content: matchContent,
-        language: "typescript",
-        source_module: "match",
-      });
-    }
-
-    files.push({
-      path: "src/index.ts",
-      content: emitNakamaIndex(system),
-      language: "typescript",
-      source_module: "root",
-    });
-
-    files.push({
-      path: "README.md",
-      content: emitNakamaReadme(system),
-      language: "markdown",
-      source_module: "root",
-    });
-
-    return files;
-  }
-}
+/**
+ * BoneScript Nakama Emitter
+ *
+ * Generates a Nakama TypeScript runtime module from an IRSystem.
+ * Output is a self-contained src/index.ts that registers:
+ *   - nk.registerRpc()  for every capability  (capability -> RPC)
+ *   - nk.registerMatch() for every realtime_service module (channel -> match handler)
+ *   - Storage helpers    for every entity/model (entity -> storage object)
+ *   - Event hooks        for every event emission (event -> stream send)
+ *
+ * Deploy with: nakama migrate up && nakama --runtime.path ./build
+ * Docs: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/
+ */
+
+import * as IR from "./ir";
+import { EmittedFile } from "./emitter";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+function toCamelCase(s: string): string {
+  return s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function toPascalCase(s: string): string {
+  const c = toCamelCase(s);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+}
+
+const TS_TYPE_MAP: Record<string, string> = {
+  string: "string",
+  uint: "number",
+  int: "number",
+  float: "number",
+  bool: "boolean",
+  timestamp: "string",   // ISO string — Nakama runtime has no Date
+  uuid: "string",
+  bytes: "string",       // base64 in Nakama
+  json: "unknown",
+};
+
+function toTsType(irType: string): string {
+  if (TS_TYPE_MAP[irType]) return TS_TYPE_MAP[irType];
+  const listMatch = irType.match(/^list<(.+)>$/);
+  if (listMatch) return `${toTsType(listMatch[1])}[]`;
+  const setMatch = irType.match(/^set<(.+)>$/);
+  if (setMatch) return `${toTsType(setMatch[1])}[]`;
+  const optMatch = irType.match(/^optional<(.+)>$/);
+  if (optMatch) return `${toTsType(optMatch[1])} | null`;
+  return irType;
+}
+
+// ─── Package.json ─────────────────────────────────────────────────────────────
+
+function emitNakamaPackageJson(system: IR.IRSystem): string {
+  return JSON.stringify({
+    name: toSnakeCase(system.name),
+    version: system.version,
+    private: true,
+    scripts: {
+      build: "npx tsc",
+      dev: "npx tsc --watch",
+    },
+    devDependencies: {
+      "@heroiclabs/nakama-runtime": "1.16.0",
+      typescript: "5.3.3",
+      "ts-node": "10.9.2",
+    },
+  }, null, 2);
+}
+
+// ─── tsconfig.json ────────────────────────────────────────────────────────────
+
+function emitNakamaTsConfig(): string {
+  return JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      module: "commonjs",
+      lib: ["ES2020"],
+      outDir: "./build",
+      rootDir: "./src",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ["src/**/*"],
+    exclude: ["node_modules", "build"],
+  }, null, 2);
+}
+
+// ─── Storage helpers ──────────────────────────────────────────────────────────
+// One collection per entity. Nakama storage: collection/key/userId pattern.
+
+function emitStorageHelpers(system: IR.IRSystem): string {
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Storage helpers — one Nakama storage collection per entity.`);
+  lines.push(``);
+  lines.push(`const nkRuntime: nkruntime.Nakama = (globalThis as any).__nk;`);
+  lines.push(``);
+
+  for (const mod of system.modules) {
+    for (const model of mod.models) {
+      const collection = toSnakeCase(model.name) + "s";
+      const typeName = toPascalCase(model.name);
+
+      // TypeScript interface
+      lines.push(`export interface ${typeName} {`);
+      for (const field of model.fields) {
+        const nullable = field.nullable ? " | null" : "";
+        lines.push(`  ${field.name}: ${toTsType(field.type)}${nullable};`);
+      }
+      lines.push(`}`);
+      lines.push(``);
+
+      // read
+      lines.push(`export function read${typeName}(nk: nkruntime.Nakama, userId: string, id: string): ${typeName} | null {`);
+      lines.push(`  const objs = nk.storageRead([{ collection: "${collection}", key: id, userId }]);`);
+      lines.push(`  if (objs.length === 0) return null;`);
+      lines.push(`  return JSON.parse(objs[0].value) as ${typeName};`);
+      lines.push(`}`);
+      lines.push(``);
+
+      // write
+      lines.push(`export function write${typeName}(nk: nkruntime.Nakama, userId: string, obj: ${typeName}): void {`);
+      lines.push(`  nk.storageWrite([{`);
+      lines.push(`    collection: "${collection}",`);
+      lines.push(`    key: (obj as any).id ?? userId,`);
+      lines.push(`    userId,`);
+      lines.push(`    value: JSON.stringify(obj),`);
+      lines.push(`    permissionRead: 1,`);
+      lines.push(`    permissionWrite: 0,`);
+      lines.push(`  }]);`);
+      lines.push(`}`);
+      lines.push(``);
+
+      // delete
+      lines.push(`export function delete${typeName}(nk: nkruntime.Nakama, userId: string, id: string): void {`);
+      lines.push(`  nk.storageDelete([{ collection: "${collection}", key: id, userId }]);`);
+      lines.push(`}`);
+      lines.push(``);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ─── RPC handlers (capabilities) ─────────────────────────────────────────────
+
+function emitRpcHandlers(system: IR.IRSystem): string {
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// RPC handlers — one nk.registerRpc() per capability.`);
+  lines.push(``);
+  lines.push(`import * as storage from "./storage";`);
+  lines.push(``);
+
+  for (const mod of system.modules) {
+    for (const iface of mod.interfaces) {
+      for (const method of iface.methods) {
+        const rpcId = `${toSnakeCase(mod.name)}/${toSnakeCase(method.name)}`;
+        const fnName = `rpc${toPascalCase(mod.name)}${toPascalCase(method.name)}`;
+
+        lines.push(`// RPC: ${rpcId}`);
+        lines.push(`// Capability: ${method.name} on ${mod.name}`);
+        if (method.preconditions.length > 0) {
+          lines.push(`// Preconditions: ${method.preconditions.map(p => p.description).join(", ")}`);
+        }
+        lines.push(`const ${fnName}: nkruntime.RpcFunction = (`);
+        lines.push(`  ctx: nkruntime.Context,`);
+        lines.push(`  logger: nkruntime.Logger,`);
+        lines.push(`  nk: nkruntime.Nakama,`);
+        lines.push(`  payload: string`);
+        lines.push(`): string => {`);
+
+        // Auth guard
+        if (method.authenticated) {
+          lines.push(`  if (!ctx.userId) {`);
+          lines.push(`    throw Error("Authentication required");`);
+          lines.push(`  }`);
+        }
+
+        // Parse payload
+        if (method.input.length > 0) {
+          const inputType = method.input.map(f => `${f.name}: ${toTsType(f.type)}`).join("; ");
+          lines.push(`  const input: { ${inputType} } = payload ? JSON.parse(payload) : {};`);
+        }
+
+        // Precondition stubs
+        if (method.preconditions.length > 0) {
+          lines.push(``);
+          lines.push(`  // Preconditions`);
+          for (const pre of method.preconditions) {
+            lines.push(`  // CHECK: ${pre.description}`);
+            lines.push(`  // if (!(${pre.expression})) throw Error("Precondition failed: ${pre.description.replace(/"/g, "'")}"); `);
+          }
+        }
+
+        // Effect stubs
+        if (method.effects.length > 0) {
+          lines.push(``);
+          lines.push(`  // Effects`);
+          for (const eff of method.effects) {
+            const op = eff.op === "assign" ? "=" : eff.op === "add" ? "+=" : "-=";
+            lines.push(`  // EFFECT: ${eff.target} ${op} ${eff.value}`);
+          }
+        }
+
+        // Event emissions via Nakama streams
+        if (method.emissions.length > 0) {
+          lines.push(``);
+          lines.push(`  // Event emissions — broadcast to stream subscribers`);
+          for (const ev of method.emissions) {
+            lines.push(`  nk.streamSend(`);
+            lines.push(`    { mode: 1, subject: ctx.userId ?? "", label: "${ev}" },`);
+            lines.push(`    JSON.stringify({ event: "${ev}", actor: ctx.userId, ts: Date.now() }),`);
+            lines.push(`    undefined,`);
+            lines.push(`    true`);
+            lines.push(`  );`);
+          }
+        }
+
+        lines.push(``);
+        lines.push(`  logger.info("rpc_called", "${rpcId}", ctx.userId ?? "anon");`);
+        lines.push(`  return JSON.stringify({ ok: true, action: "${method.name}" });`);
+        lines.push(`};`);
+        lines.push(``);
+
+        // Export the function name and rpc id for registration
+        lines.push(`export const ${fnName}Id = "${rpcId}";`);
+        lines.push(`export { ${fnName} };`);
+        lines.push(``);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Match handler (realtime channels) ───────────────────────────────────────
+
+function emitMatchHandlers(system: IR.IRSystem): string {
+  const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
+  if (realtimeMods.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Match handlers — one per realtime_service module.`);
+  lines.push(``);
+
+  for (const mod of realtimeMods) {
+    const handlerName = `${toCamelCase(mod.name)}MatchHandler`;
+    const matchName = toSnakeCase(mod.name);
+
+    lines.push(`// Match handler for channel: ${mod.name}`);
+    lines.push(`const ${handlerName}: nkruntime.MatchHandler = {`);
+    lines.push(``);
+
+    // matchInit
+    lines.push(`  matchInit(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    params: { [key: string]: string }`);
+    lines.push(`  ): { state: unknown; tickRate: number; label: string } {`);
+    lines.push(`    logger.info("match_init", "${matchName}");`);
+    lines.push(`    return {`);
+    lines.push(`      state: { players: {}, tick: 0 },`);
+    lines.push(`      tickRate: ${mod.config["tick_rate"] ?? 10},`);
+    lines.push(`      label: "${matchName}",`);
+    lines.push(`    };`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchJoinAttempt
+    lines.push(`  matchJoinAttempt(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    presence: nkruntime.Presence,`);
+    lines.push(`    metadata: { [key: string]: any }`);
+    lines.push(`  ): { state: unknown; accept: boolean; rejectMessage?: string } {`);
+    lines.push(`    return { state, accept: true };`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchJoin
+    lines.push(`  matchJoin(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    presences: nkruntime.Presence[]`);
+    lines.push(`  ): { state: unknown } | null {`);
+    lines.push(`    const s = state as any;`);
+    lines.push(`    for (const p of presences) {`);
+    lines.push(`      s.players[p.userId] = { userId: p.userId, sessionId: p.sessionId, joinedAt: Date.now() };`);
+    lines.push(`    }`);
+    lines.push(`    dispatcher.broadcastMessage(1, JSON.stringify({ type: "player_joined", players: Object.keys(s.players) }), null, null, true);`);
+    lines.push(`    return { state: s };`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchLeave
+    lines.push(`  matchLeave(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    presences: nkruntime.Presence[]`);
+    lines.push(`  ): { state: unknown } | null {`);
+    lines.push(`    const s = state as any;`);
+    lines.push(`    for (const p of presences) delete s.players[p.userId];`);
+    lines.push(`    if (Object.keys(s.players).length === 0) return null; // end match`);
+    lines.push(`    return { state: s };`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchLoop
+    lines.push(`  matchLoop(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    messages: nkruntime.MatchMessage[]`);
+    lines.push(`  ): { state: unknown } | null {`);
+    lines.push(`    const s = state as any;`);
+    lines.push(`    s.tick = tick;`);
+    lines.push(`    for (const msg of messages) {`);
+    lines.push(`      // Route incoming messages to capability handlers`);
+    lines.push(`      try {`);
+    lines.push(`        const data = JSON.parse(nk.binaryToString(msg.data));`);
+    lines.push(`        dispatcher.broadcastMessage(msg.opCode, msg.data, null, msg.sender, true);`);
+    lines.push(`      } catch (e) {`);
+    lines.push(`        logger.error("match_message_error", String(e));`);
+    lines.push(`      }`);
+    lines.push(`    }`);
+    lines.push(`    return { state: s };`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchTerminate
+    lines.push(`  matchTerminate(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    graceSeconds: number`);
+    lines.push(`  ): { state: unknown } | null {`);
+    lines.push(`    dispatcher.broadcastMessage(0, JSON.stringify({ type: "match_terminated" }), null, null, true);`);
+    lines.push(`    return null;`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // matchSignal
+    lines.push(`  matchSignal(`);
+    lines.push(`    ctx: nkruntime.Context,`);
+    lines.push(`    logger: nkruntime.Logger,`);
+    lines.push(`    nk: nkruntime.Nakama,`);
+    lines.push(`    dispatcher: nkruntime.MatchDispatcher,`);
+    lines.push(`    tick: number,`);
+    lines.push(`    state: unknown,`);
+    lines.push(`    data: string`);
+    lines.push(`  ): { state: unknown; data: string } {`);
+    lines.push(`    return { state, data };`);
+    lines.push(`  },`);
+    lines.push(`};`);
+    lines.push(``);
+    lines.push(`export const ${handlerName}Name = "${matchName}";`);
+    lines.push(`export { ${handlerName} };`);
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Main entry point (InitModule) ───────────────────────────────────────────
+
+function emitNakamaIndex(system: IR.IRSystem): string {
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Nakama TypeScript runtime module for: ${system.name}`);
+  lines.push(`// Deploy: copy build/ to Nakama runtime path and restart.`);
+  lines.push(``);
+  lines.push(`import * as rpc from "./rpc";`);
+
+  const hasRealtime = system.modules.some(m => m.kind === "realtime_service");
+  if (hasRealtime) {
+    lines.push(`import * as match from "./match";`);
+  }
+
+  lines.push(``);
+  lines.push(`function InitModule(`);
+  lines.push(`  ctx: nkruntime.Context,`);
+  lines.push(`  logger: nkruntime.Logger,`);
+  lines.push(`  nk: nkruntime.Nakama,`);
+  lines.push(`  initializer: nkruntime.Initializer`);
+  lines.push(`): Error | void {`);
+  lines.push(`  logger.info("init_module", "${system.name} v${system.version}");`);
+  lines.push(``);
+
+  // Register all RPCs
+  const allMethods: { mod: IR.IRModule; method: IR.IRMethod }[] = [];
+  for (const mod of system.modules) {
+    for (const iface of mod.interfaces) {
+      for (const method of iface.methods) {
+        allMethods.push({ mod, method });
+      }
+    }
+  }
+
+  if (allMethods.length > 0) {
+    lines.push(`  // Register RPC handlers`);
+    for (const { mod, method } of allMethods) {
+      const fnName = `rpc${toPascalCase(mod.name)}${toPascalCase(method.name)}`;
+      lines.push(`  initializer.registerRpc(rpc.${fnName}Id, rpc.${fnName});`);
+    }
+    lines.push(``);
+  }
+
+  // Register match handlers
+  if (hasRealtime) {
+    const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
+    lines.push(`  // Register match handlers`);
+    for (const mod of realtimeMods) {
+      const handlerName = `${toCamelCase(mod.name)}MatchHandler`;
+      lines.push(`  initializer.registerMatch(match.${handlerName}Name, match.${handlerName});`);
+    }
+    lines.push(``);
+  }
+
+  lines.push(`  logger.info("init_complete", "${allMethods.length} RPCs, ${hasRealtime ? system.modules.filter(m => m.kind === "realtime_service").length : 0} match handlers");`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`// Required Nakama module export`);
+  lines.push(`(globalThis as any).InitModule = InitModule;`);
+
+  return lines.join("\n");
+}
+
+// ─── README ───────────────────────────────────────────────────────────────────
+
+function emitNakamaReadme(system: IR.IRSystem): string {
+  const rpcs: string[] = [];
+  for (const mod of system.modules) {
+    for (const iface of mod.interfaces) {
+      for (const method of iface.methods) {
+        rpcs.push(`- \`${toSnakeCase(mod.name)}/${toSnakeCase(method.name)}\``);
+      }
+    }
+  }
+  const realtimeMods = system.modules.filter(m => m.kind === "realtime_service");
+
+  return `# ${system.name} — Nakama Backend
+
+Generated by BoneScript compiler (target: nakama). Source hash: ${system.source_hash}
+
+## Quick Start
+
+\`\`\`bash
+# Install deps
+npm install
+
+# Build TypeScript -> JS
+npm run build
+
+# Start Nakama with this module
+docker run --rm -v $(pwd)/build:/nakama/data/modules \\
+  heroiclabs/nakama:latest
+\`\`\`
+
+## RPC Endpoints
+
+Call these from any Nakama client SDK:
+
+${rpcs.join("\n")}
+
+## Match Handlers
+
+${realtimeMods.length > 0
+  ? realtimeMods.map(m => `- \`${toSnakeCase(m.name)}\` (tick rate: ${m.config["tick_rate"] ?? 10}/s)`).join("\n")
+  : "_No realtime channels declared._"}
+
+## Storage Collections
+
+${system.modules.flatMap(m => m.models).map(m => `- \`${toSnakeCase(m.name)}s\``).join("\n") || "_No entities declared._"}
+
+## Auth
+
+All authenticated RPCs require a valid Nakama session token.
+Use any Nakama client SDK to authenticate before calling RPCs.
+`;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface NakamaEmittedFile {
+  path: string;
+  content: string;
+  language: "typescript" | "json" | "markdown";
+  source_module: string;
+}
+
+export class NakamaEmitter {
+  emit(system: IR.IRSystem): NakamaEmittedFile[] {
+    const files: NakamaEmittedFile[] = [];
+
+    files.push({
+      path: "package.json",
+      content: emitNakamaPackageJson(system),
+      language: "json",
+      source_module: "root",
+    });
+
+    files.push({
+      path: "tsconfig.json",
+      content: emitNakamaTsConfig(),
+      language: "json",
+      source_module: "root",
+    });
+
+    files.push({
+      path: "src/storage.ts",
+      content: emitStorageHelpers(system),
+      language: "typescript",
+      source_module: "storage",
+    });
+
+    files.push({
+      path: "src/rpc.ts",
+      content: emitRpcHandlers(system),
+      language: "typescript",
+      source_module: "rpc",
+    });
+
+    const matchContent = emitMatchHandlers(system);
+    if (matchContent) {
+      files.push({
+        path: "src/match.ts",
+        content: matchContent,
+        language: "typescript",
+        source_module: "match",
+      });
+    }
+
+    files.push({
+      path: "src/index.ts",
+      content: emitNakamaIndex(system),
+      language: "typescript",
+      source_module: "root",
+    });
+
+    files.push({
+      path: "README.md",
+      content: emitNakamaReadme(system),
+      language: "markdown",
+      source_module: "root",
+    });
+
+    return files;
+  }
+}