bonescript-compiler 0.3.0 → 0.5.0

package/src/emit_openapi.ts

@@ -0,0 +1,318 @@
+/**
+ * BoneScript OpenAPI 3.1 Schema Emitter
+ * Generates a complete openapi.json for each api_service module.
+ * Implements spec/09_CODEGEN.md §2 (ApiService → JSON secondary target).
+ *
+ * Produces: openapi.json at the project root.
+ */
+
+import * as IR from "./ir";
+
+// ─── Type mapping ─────────────────────────────────────────────────────────────
+
+function irTypeToJsonSchema(irType: string): Record<string, unknown> {
+  switch (irType) {
+    case "string":    return { type: "string" };
+    case "uint":      return { type: "integer", minimum: 0 };
+    case "int":       return { type: "integer" };
+    case "float":     return { type: "number" };
+    case "bool":      return { type: "boolean" };
+    case "timestamp": return { type: "string", format: "date-time" };
+    case "uuid":      return { type: "string", format: "uuid" };
+    case "bytes":     return { type: "string", format: "byte" };
+    case "json":      return {};
+    default: {
+      const listMatch = irType.match(/^list<(.+)>$/);
+      if (listMatch) return { type: "array", items: irTypeToJsonSchema(listMatch[1]) };
+      const setMatch = irType.match(/^set<(.+)>$/);
+      if (setMatch) return { type: "array", items: irTypeToJsonSchema(setMatch[1]), uniqueItems: true };
+      const optMatch = irType.match(/^optional<(.+)>$/);
+      if (optMatch) return { oneOf: [irTypeToJsonSchema(optMatch[1]), { type: "null" }] };
+      // Entity reference — use $ref
+      return { $ref: `#/components/schemas/${irType}` };
+    }
+  }
+}
+
+function modelToSchema(model: IR.IRModel): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const field of model.fields) {
+    if (field.default_value?.startsWith("GENERATED ALWAYS")) continue;
+    properties[field.name] = irTypeToJsonSchema(field.type);
+    if (!field.nullable && !field.default_value) {
+      required.push(field.name);
+    }
+  }
+
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+// ─── Main emitter ─────────────────────────────────────────────────────────────
+
+export function emitOpenApiSchema(system: IR.IRSystem): string {
+  const apiModules = system.modules.filter(m => m.kind === "api_service" && m.models.length > 0);
+  if (apiModules.length === 0) return "";
+
+  // ── Collect all schemas ──────────────────────────────────────────────────
+  const schemas: Record<string, unknown> = {};
+
+  // Standard error schema
+  schemas["Error"] = {
+    type: "object",
+    required: ["error"],
+    properties: {
+      error: {
+        type: "object",
+        required: ["code", "message"],
+        properties: {
+          code: { type: "string" },
+          message: { type: "string" },
+        },
+      },
+    },
+  };
+
+  // Paginated result wrapper
+  schemas["PaginatedResult"] = {
+    type: "object",
+    required: ["items", "total", "page", "page_size"],
+    properties: {
+      items: { type: "array", items: {} },
+      total: { type: "integer", minimum: 0 },
+      page: { type: "integer", minimum: 1 },
+      page_size: { type: "integer", minimum: 1 },
+    },
+  };
+
+  for (const mod of apiModules) {
+    for (const model of mod.models) {
+      schemas[model.name] = modelToSchema(model);
+
+      // Create input schema (omit server-set fields)
+      const createProps: Record<string, unknown> = {};
+      const createRequired: string[] = [];
+      for (const field of model.fields) {
+        if (["id", "created_at", "updated_at"].includes(field.name)) continue;
+        if (field.default_value?.startsWith("GENERATED ALWAYS")) continue;
+        createProps[field.name] = irTypeToJsonSchema(field.type);
+        if (!field.nullable && !field.default_value) createRequired.push(field.name);
+      }
+      schemas[`Create${model.name}Input`] = {
+        type: "object",
+        properties: createProps,
+        ...(createRequired.length > 0 ? { required: createRequired } : {}),
+      };
+
+      // Update input schema (all optional)
+      const updateProps: Record<string, unknown> = {};
+      for (const field of model.fields) {
+        if (["id", "created_at", "updated_at"].includes(field.name)) continue;
+        if (field.default_value?.startsWith("GENERATED ALWAYS")) continue;
+        updateProps[field.name] = irTypeToJsonSchema(field.type);
+      }
+      schemas[`Update${model.name}Input`] = {
+        type: "object",
+        properties: updateProps,
+      };
+    }
+  }
+
+  // Event payload schemas
+  for (const ev of system.events) {
+    const props: Record<string, unknown> = {};
+    for (const field of ev.payload) {
+      props[field.name] = irTypeToJsonSchema(field.type);
+    }
+    schemas[`${ev.name}Payload`] = { type: "object", properties: props };
+  }
+
+  // ── Build paths ──────────────────────────────────────────────────────────
+  const paths: Record<string, unknown> = {};
+
+  for (const mod of apiModules) {
+    const model = mod.models[0];
+    const basePath = `/${toSnakeCase(model.name)}s`;
+    const tag = mod.name;
+
+    // GET / — list
+    paths[basePath] = {
+      get: {
+        tags: [tag],
+        summary: `List ${model.name}s`,
+        security: [{ bearerAuth: [] }],
+        parameters: [
+          { name: "page", in: "query", schema: { type: "integer", minimum: 1, default: 1 } },
+          { name: "page_size", in: "query", schema: { type: "integer", minimum: 1, maximum: 100, default: 50 } },
+        ],
+        responses: {
+          "200": {
+            description: `List of ${model.name}s`,
+            content: {
+              "application/json": {
+                schema: {
+                  allOf: [
+                    { $ref: "#/components/schemas/PaginatedResult" },
+                    { properties: { items: { type: "array", items: { $ref: `#/components/schemas/${model.name}` } } } },
+                  ],
+                },
+              },
+            },
+          },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+        },
+      },
+      post: {
+        tags: [tag],
+        summary: `Create ${model.name}`,
+        security: [{ bearerAuth: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/Create${model.name}Input` },
+            },
+          },
+        },
+        responses: {
+          "201": {
+            description: `${model.name} created`,
+            content: { "application/json": { schema: { $ref: `#/components/schemas/${model.name}` } } },
+          },
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+        },
+      },
+    };
+
+    // GET /:id, PUT /:id, DELETE /:id
+    const idPath = `${basePath}/{id}`;
+    paths[idPath] = {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: [tag],
+        summary: `Get ${model.name} by id`,
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": { description: `${model.name}`, content: { "application/json": { schema: { $ref: `#/components/schemas/${model.name}` } } } },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "404": { $ref: "#/components/responses/NotFound" },
+        },
+      },
+      put: {
+        tags: [tag],
+        summary: `Update ${model.name}`,
+        security: [{ bearerAuth: [] }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: `#/components/schemas/Update${model.name}Input` } } },
+        },
+        responses: {
+          "200": { description: `Updated ${model.name}`, content: { "application/json": { schema: { $ref: `#/components/schemas/${model.name}` } } } },
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "404": { $ref: "#/components/responses/NotFound" },
+        },
+      },
+      delete: {
+        tags: [tag],
+        summary: `Delete ${model.name}`,
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "204": { description: "Deleted" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "404": { $ref: "#/components/responses/NotFound" },
+        },
+      },
+    };
+
+    // Capability endpoints
+    for (const iface of mod.interfaces) {
+      for (const method of iface.methods) {
+        if (["create", "read", "update", "delete", "list"].includes(method.name)) continue;
+
+        const capPath = `${basePath}/${method.name.replace(/_/g, "-")}`;
+        const inputProps: Record<string, unknown> = {};
+        for (const param of method.input) {
+          inputProps[param.name] = irTypeToJsonSchema(param.type);
+        }
+
+        paths[capPath] = {
+          post: {
+            tags: [tag],
+            summary: method.name.replace(/_/g, " "),
+            description: [
+              method.preconditions.length > 0 ? `**Preconditions:** ${method.preconditions.map(p => p.description).join("; ")}` : "",
+              method.effects.length > 0 ? `**Effects:** ${method.effects.map(e => `${e.target} ${e.op === "assign" ? "=" : e.op === "add" ? "+=" : "-="} ${e.value}`).join("; ")}` : "",
+              method.sync ? `**Sync:** ${method.sync}` : "",
+            ].filter(Boolean).join("\n\n"),
+            security: [{ bearerAuth: [] }],
+            requestBody: {
+              required: true,
+              content: {
+                "application/json": {
+                  schema: { type: "object", properties: inputProps },
+                },
+              },
+            },
+            responses: {
+              "200": { description: "Success", content: { "application/json": { schema: { type: "object", properties: { ok: { type: "boolean" }, action: { type: "string" } } } } } },
+              "401": { $ref: "#/components/responses/Unauthorized" },
+              "422": { description: "Precondition failed", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
+            },
+          },
+        };
+      }
+    }
+  }
+
+  // ── Assemble document ────────────────────────────────────────────────────
+  const doc = {
+    openapi: "3.1.0",
+    info: {
+      title: system.name,
+      version: system.version,
+      description: `Generated by BoneScript compiler. Source hash: ${system.source_hash}`,
+    },
+    servers: [
+      { url: "http://localhost:3000", description: "Local development" },
+    ],
+    tags: apiModules.map(m => ({ name: m.name, description: `${m.name} endpoints` })),
+    paths,
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+        },
+      },
+      schemas,
+      responses: {
+        Unauthorized: {
+          description: "Authentication required",
+          content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } },
+        },
+        NotFound: {
+          description: "Resource not found",
+          content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } },
+        },
+        BadRequest: {
+          description: "Invalid request",
+          content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } },
+        },
+      },
+    },
+  };
+
+  return JSON.stringify(doc, null, 2);
+}

package/src/emit_router.ts

@@ -81,10 +81,12 @@ export function emitStateMachineRuntime(sm: IR.IRStateMachine): string {
   lines.push(``);
   lines.push(`export function transition${sm.entity}(`);
   lines.push(`  current: ${sm.entity}State,`);
-  lines.push(`  trigger: string`);
+  lines.push(`  trigger: string,`);
+  lines.push(`  guard?: () => boolean`);
   lines.push(`): { ok: true; next: ${sm.entity}State } | { ok: false; error: string } {`);
   lines.push(`  const next = TRANSITIONS[current]?.[trigger];`);
   lines.push(`  if (!next) return { ok: false, error: \`Invalid transition: \${current} --[\${trigger}]--> ?\` };`);
+  lines.push(`  if (guard && !guard()) return { ok: false, error: \`Guard failed for transition: \${current} --[\${trigger}]--> \${next}\` };`);
   lines.push(`  return { ok: true, next };`);
   lines.push(`}`);
   lines.push(``);
@@ -115,6 +117,20 @@ export function emitEntityRouter(mod: IR.IRModule, system: IR.IRSystem): string
   lines.push(`const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;`);
   lines.push(``);
 
+  // Import broadcastToChannel if any capability uses sync: realtime
+  const hasRealtime = mod.interfaces.some(i => i.methods.some(m => m.sync === "realtime"));
+  if (hasRealtime) {
+    // Only import if websocket.ts will be generated (system has realtime_service modules)
+    const hasWebSocket = system.modules.some(m => m.kind === "realtime_service");
+    if (hasWebSocket) {
+      lines.push(`import { broadcastToChannel } from "../websocket";`);
+    } else {
+      // No WebSocket server — define a no-op stub so the route file still compiles
+      lines.push(`// No realtime_service declared — broadcastToChannel is a no-op`);
+      lines.push(`function broadcastToChannel(_channel: string, _msg: unknown, _exclude?: unknown): void {}`);
+    }
+    lines.push(``);
+  }
   const unknownFunctions = collectUnknownFunctions(mod);
   if (unknownFunctions.size > 0) {
     lines.push(`// User-defined functions referenced in effects — implement these or use extension_point`);
@@ -363,9 +379,7 @@ export function emitCapabilityEndpoint(
     lines.push(`    __client.release();`);
     lines.push(`  }`);
   } else if (method.sync === "realtime") {
-    lines.push(`    if (typeof broadcastToChannel === "function") {`);
-    lines.push(`      broadcastToChannel("${mod.name}", { type: "${method.name}", payload: req.body, actor: auth.actor_id });`);
-    lines.push(`    }`);
+    lines.push(`    broadcastToChannel("${mod.name}", { type: "${method.name}", payload: req.body, actor: auth.actor_id });`);
     lines.push(`  } catch (e: any) {`);
     lines.push(`    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });`);
     lines.push(`  }`);

package/src/emit_tests.ts

@@ -126,6 +126,19 @@ export function emitTestSuite(system: IR.IRSystem): string {
     lines.push(`});`);
     lines.push(``);
 
+    // Update test
+    const updatePayload = createFields.slice(0, 1).reduce((acc, f) => {
+      acc[f.name] = sampleValue(f.type);
+      return acc;
+    }, {} as Record<string, any>);
+    lines.push(`await test("PUT ${tablePath}/:id — updates entity", async () => {`);
+    lines.push(`  if (!__${toSnakeCase(model.name)}_id) { throw new Error("Skipped: no id from create test"); }`);
+    lines.push(`  const { status, data } = await request("PUT", \`${tablePath}/\${__${toSnakeCase(model.name)}_id}\`, ${JSON.stringify(updatePayload)});`);
+    lines.push(`  assert(status === 200, \`Expected 200, got \${status}: \${JSON.stringify(data)}\`);`);
+    lines.push(`  assert(data.id === __${toSnakeCase(model.name)}_id, "ID must match after update");`);
+    lines.push(`});`);
+    lines.push(``);
+
     // Capability tests
     for (const iface of mod.interfaces) {
       for (const method of iface.methods) {
@@ -141,6 +154,18 @@ export function emitTestSuite(system: IR.IRSystem): string {
         lines.push(`});`);
         lines.push(``);
 
+        // Idempotency test
+        if (method.idempotent) {
+          lines.push(`await test("POST ${endpoint} — idempotent (same result on repeat)", async () => {`);
+          lines.push(`  const payload = { ${toSnakeCase(model.name)}_id: __${toSnakeCase(model.name)}_id };`);
+          lines.push(`  const { status: s1, data: d1 } = await request("POST", "${endpoint}", payload);`);
+          lines.push(`  const { status: s2, data: d2 } = await request("POST", "${endpoint}", payload);`);
+          lines.push(`  assert(s1 === s2, \`Idempotency: first call \${s1}, second call \${s2}\`);`);
+          lines.push(`  assert(JSON.stringify(d1) === JSON.stringify(d2), "Idempotency: responses must be identical");`);
+          lines.push(`});`);
+          lines.push(``);
+        }
+
         if (method.preconditions.length > 0) {
           lines.push(`await test("POST ${endpoint} — returns 401 without auth", async () => {`);
           lines.push(`  const res = await fetch(\`\${BASE_URL}${endpoint}\`, { method: "POST" });`);
@@ -154,6 +179,22 @@ export function emitTestSuite(system: IR.IRSystem): string {
     // State machine tests
     for (const sm of mod.state_machines) {
       lines.push(`// State machine: ${sm.entity}`);
+
+      // Valid transition test — transition from initial state to first reachable state
+      const firstTransition = sm.transitions.find(t => t.from === sm.initial);
+      if (firstTransition) {
+        lines.push(`await test("PUT ${tablePath}/:id — valid state transition (${firstTransition.from} → ${firstTransition.to})", async () => {`);
+        lines.push(`  if (!__${toSnakeCase(model.name)}_id) { throw new Error("Skipped: no id from create test"); }`);
+        lines.push(`  const { status, data } = await request("PUT", \`${tablePath}/\${__${toSnakeCase(model.name)}_id}\`, {`);
+        lines.push(`    state: "${firstTransition.to}",`);
+        lines.push(`  });`);
+        lines.push(`  assert(status === 200, \`Expected 200 for valid transition, got \${status}: \${JSON.stringify(data)}\`);`);
+        lines.push(`  assert(data.state === "${firstTransition.to}", \`Expected state '${firstTransition.to}', got '\${data.state}'\`);`);
+        lines.push(`});`);
+        lines.push(``);
+      }
+
+      // Invalid transition test
       lines.push(`await test("PUT ${tablePath}/:id — rejects invalid state transition", async () => {`);
       lines.push(`  const { status, data } = await request("PUT", \`${tablePath}/\${__${toSnakeCase(model.name)}_id}\`, {`);
       lines.push(`    state: "__invalid_state__",`);

package/src/emitter.ts

@@ -62,6 +62,12 @@ function toSqlType(irType: string): string {
   return "JSONB";
 }
 
+/** Returns an inline SQL CHECK constraint for types that need one, or empty string. */
+function sqlCheckConstraint(irType: string): string {
+  if (irType === "uint") return " CHECK (VALUE >= 0)";
+  return "";
+}
+
 function toSnakeCase(s: string): string {
   return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
 }
@@ -126,7 +132,7 @@ export class Emitter {
 
     const fieldLines: string[] = [];
     for (const field of model.fields) {
-      let line = `  ${field.name} ${toSqlType(field.type)}`;
+      let line = `  ${field.name} ${toSqlType(field.type)}${sqlCheckConstraint(field.type)}`;
       if (!field.nullable) line += " NOT NULL";
       if (field.default_value) {
         if (field.default_value === "gen_random_uuid()") line += " DEFAULT gen_random_uuid()";
@@ -158,6 +164,16 @@ export class Emitter {
       }
     }
 
+    // Add cardinality CHECK constraints from relations
+    // has_one: enforce at most 1 child row via a partial unique index (emitted below)
+    // has_many with explicit max: enforce via CHECK on count (done via trigger — see below)
+    for (const rel of (mod as any).relations_with_cardinality || []) {
+      if (rel.cardinality && rel.cardinality.max !== "*" && typeof rel.cardinality.max === "number") {
+        // Will be enforced via trigger — placeholder comment
+        fieldLines.push(`  -- cardinality: ${rel.name} max ${rel.cardinality.max} (enforced by trigger)`);
+      }
+    }
+
     lines.push(fieldLines.join(",\n"));
     lines.push(`);`);
     lines.push(``);
@@ -176,6 +192,46 @@ export class Emitter {
       }
     }
 
+    // Cardinality enforcement
+    for (const rel of mod.relations || []) {
+      // has_one: enforce via unique index on the FK column in the child table
+      if (rel.kind === "has_one") {
+        const childTable = rel.to_table;
+        const fk = rel.foreign_key;
+        lines.push(``);
+        lines.push(`-- has_one cardinality: each ${tableName.slice(0, -1)} may have at most one ${childTable.slice(0, -1)}`);
+        lines.push(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${childTable}_${fk}_unique ON ${childTable} (${fk});`);
+      }
+
+      // has_many with explicit numeric max: enforce via a BEFORE INSERT trigger
+      if (rel.kind === "has_many" && rel.cardinality && rel.cardinality.max !== "*") {
+        const maxCount = rel.cardinality.max as number;
+        const childTable = rel.to_table;
+        const fk = rel.foreign_key;
+        const fnName = `check_${tableName}_${rel.name}_max`;
+        lines.push(``);
+        lines.push(`-- has_many cardinality: max ${maxCount} ${childTable} per ${tableName.slice(0, -1)}`);
+        lines.push(`CREATE OR REPLACE FUNCTION ${fnName}()`);
+        lines.push(`RETURNS TRIGGER AS $$`);
+        lines.push(`DECLARE`);
+        lines.push(`  current_count INTEGER;`);
+        lines.push(`BEGIN`);
+        lines.push(`  SELECT COUNT(*) INTO current_count FROM ${childTable} WHERE ${fk} = NEW.${fk};`);
+        lines.push(`  IF current_count >= ${maxCount} THEN`);
+        lines.push(`    RAISE EXCEPTION 'Cardinality violation: ${tableName.slice(0, -1)} already has ${maxCount} ${childTable} (max ${maxCount})';`);
+        lines.push(`  END IF;`);
+        lines.push(`  RETURN NEW;`);
+        lines.push(`END;`);
+        lines.push(`$$ LANGUAGE plpgsql;`);
+        lines.push(``);
+        lines.push(`DROP TRIGGER IF EXISTS trg_${fnName} ON ${childTable};`);
+        lines.push(`CREATE TRIGGER trg_${fnName}`);
+        lines.push(`  BEFORE INSERT ON ${childTable}`);
+        lines.push(`  FOR EACH ROW`);
+        lines.push(`  EXECUTE FUNCTION ${fnName}();`);
+      }
+    }
+
     // Junction tables for many_to_many
     for (const rel of mod.relations || []) {
       if (rel.kind === "many_to_many" && rel.junction_table) {
@@ -345,7 +401,7 @@ export class Emitter {
       // Implementation class
       lines.push(`export class ${mod.name} implements ${iface.name} {`);
       for (const method of iface.methods) {
-        lines.push(this.emitMethod(method));
+        lines.push(this.emitMethod(method, mod, system));
       }
       lines.push(`}`);
       lines.push(``);
@@ -359,7 +415,7 @@ export class Emitter {
     };
   }
 
-  private emitMethod(method: IR.IRMethod): string {
+  private emitMethod(method: IR.IRMethod, mod: IR.IRModule, system: IR.IRSystem): string {
     const lines: string[] = [];
     const params = method.input.map(f => `${f.name}: ${toTsType(f.type)}`).join(", ");
     const ctxParam = method.authenticated ? "ctx: RequestContext" : "";
@@ -404,8 +460,28 @@ export class Emitter {
       lines.push(``);
     }
 
-    lines.push(`    // TODO: Implementation`);
-    lines.push(`    throw new Error("Not implemented: ${method.name}");`);
+    // Real implementation — delegate to emitCapabilityBody for capabilities,
+    // or generate CRUD SQL for standard methods
+    const { emitCapabilityBody } = require("./emit_capability");
+    const { emitPipelineBody, emitAlgorithmBody } = require("./emit_composition");
+
+    if (method.pipeline) {
+      lines.push(emitPipelineBody(method, "    "));
+    } else if (method.algorithm) {
+      lines.push(emitAlgorithmBody(method, "    "));
+    } else if (method.effects.length > 0 || method.preconditions.length > 0) {
+      // Capability with effects/preconditions — use the full capability body emitter
+      try {
+        lines.push(emitCapabilityBody(method, mod, system, "    "));
+      } catch {
+        // Fallback: emit a descriptive stub if body generation fails
+        lines.push(`    // Effects: ${method.effects.map((e: any) => e.target + " " + e.op + " " + e.value).join("; ")}`);
+        lines.push(`    return { ok: false, error: { code: "NOT_IMPLEMENTED", message: "${method.name} not yet implemented" } };`);
+      }
+    } else {
+      // CRUD or simple method — emit a typed not-implemented stub
+      lines.push(`    return { ok: false, error: { code: "NOT_IMPLEMENTED", message: "${method.name} not yet implemented" } };`);
+    }
     lines.push(`  }`);
     lines.push(``);
 

package/src/ir.ts

@@ -169,6 +169,7 @@ export interface IRRelation {
   to_table: string;
   foreign_key: string;   // column name on the owning side
   junction_table?: string; // only for many_to_many
+  cardinality?: { min: number; max: number | "*" }; // optional explicit bounds
 }
 
 // ─── Invariants ──────────────────────────────────────────────────────────────

package/src/lowering.ts

@@ -58,9 +58,27 @@ export class Lowering {
       modules.push(lowerChannel(this.systemName, channel));
     }
 
+    // Build a map from event name → emitting module id by scanning all capabilities
+    // across all entities. This resolves the event source before lowering events.
+    const eventSourceMap = new Map<string, string>();
+    for (const entity of entities) {
+      const moduleId = makeId(this.systemName, "api_service", `${entity.name}Service`);
+      const relatedCaps = capabilities.filter(c =>
+        c.params.some(p => p.type.kind === "EntityRefType" && p.type.name === entity.name)
+      );
+      for (const cap of relatedCaps) {
+        for (const emit of cap.emits) {
+          if (!eventSourceMap.has(emit.eventName)) {
+            eventSourceMap.set(emit.eventName, moduleId);
+          }
+        }
+      }
+    }
+
     // Events
     for (const ev of eventDecls) {
-      events.push(lowerEvent(this.systemName, ev));
+      const source = eventSourceMap.get(ev.name) || "unknown";
+      events.push(lowerEvent(this.systemName, ev, source));
     }
 
     // Flows

package/src/lowering_channels.ts

@@ -73,18 +73,19 @@ export function lowerChannel(systemName: string, channel: AST.ChannelDeclNode):
       ordering:    channel.ordering    || "fifo",
       persistence: channel.persistence || "none",
       max_size:    channel.maxSize     || 10000,
+      ...(channel.filter ? { filter: serializeExpr(channel.filter) } : {}),
     },
   };
 }
 
 // ─── Event Lowering ───────────────────────────────────────────────────────────
 
-export function lowerEvent(systemName: string, ev: AST.EventDeclNode): IR.IREvent {
+export function lowerEvent(systemName: string, ev: AST.EventDeclNode, source: string): IR.IREvent {
   return {
     id: makeId(systemName, "event", ev.name),
     name: ev.name,
     payload: ev.payload.map(lowerFieldHelper),
-    source: "unknown",
+    source,
     delivery: (ev.delivery as IR.IRDeliveryMode) || "at_least_once",
     ordering: "fifo",
     ttl_ms: parseDurationMs(ev.ttl),