bonescript-compiler 0.5.3 → 0.5.5

package/src/lowering.ts

@@ -1,168 +1,556 @@
-/**
- * BoneScript Lowering — Stage 4 of the compilation pipeline.
- * Converts typed AST into the Architecture IR (spec/07_IR_SPEC.md).
- *
- * This file is the orchestrator. The actual lowering logic lives in:
- *   lowering_helpers.ts   — makeId, parseDurationMs, serializeExpr/Type
- *   lowering_entities.ts  — lowerEntity, lowerCapability, lowerField, makeCrudMethod
- *   lowering_channels.ts  — lowerStore, lowerChannel, lowerEvent, lowerFlow
- */
-
-import * as AST from "./ast";
-import * as IR from "./ir";
-import { makeId, serializeExpr, serializeType } from "./lowering_helpers";
-import { lowerEntity, lowerCapability } from "./lowering_entities";
-import { lowerStore, lowerChannel, lowerEvent, lowerFlow } from "./lowering_channels";
-
-export class Lowering {
-  private systemName: string = "";
-
-  lower(program: AST.ProgramNode, sourceHash: string): IR.IRSystem[] {
-    return program.systems.map(sys => this.lowerSystem(sys, sourceHash));
-  }
-
-  private lowerSystem(sys: AST.SystemDeclNode, sourceHash: string): IR.IRSystem {
-    this.systemName = sys.name;
-
-    const modules:    IR.IRModule[]    = [];
-    const events:     IR.IREvent[]     = [];
-    const flows:      IR.IRFlow[]      = [];
-    const invariants: IR.IRInvariant[] = [];
-
-    // Partition declarations by kind
-    const entities     = sys.declarations.filter((d): d is AST.EntityDeclNode     => d.kind === "EntityDecl");
-    const capabilities = sys.declarations.filter((d): d is AST.CapabilityDeclNode => d.kind === "CapabilityDecl");
-    const channels     = sys.declarations.filter((d): d is AST.ChannelDeclNode    => d.kind === "ChannelDecl");
-    const stores       = sys.declarations.filter((d): d is AST.StoreDeclNode      => d.kind === "StoreDecl");
-    const eventDecls   = sys.declarations.filter((d): d is AST.EventDeclNode      => d.kind === "EventDecl");
-    const constraints  = sys.declarations.filter((d): d is AST.ConstraintDeclNode => d.kind === "ConstraintDecl");
-    const policies     = sys.declarations.filter((d): d is AST.PolicyDeclNode     => d.kind === "PolicyDecl");
-    const flowDecls    = sys.declarations.filter((d): d is AST.FlowDeclNode       => d.kind === "FlowDecl");
-    const extensionPoints = sys.declarations.filter((d): d is AST.ExtensionPointDeclNode => d.kind === "ExtensionPointDecl");
-
-    // Stores → data_store modules
-    for (const store of stores) {
-      modules.push(lowerStore(this.systemName, store));
-    }
-
-    // Entities → api_service modules (with CRUD + related capabilities)
-    for (const entity of entities) {
-      const relatedCaps = capabilities.filter(c =>
-        c.params.some(p => p.type.kind === "EntityRefType" && p.type.name === entity.name)
-      );
-      modules.push(lowerEntity(this.systemName, entity, relatedCaps, stores));
-    }
-
-    // Standalone capabilities (no entity params) → utility api_service module
-    // These include algorithm capabilities, pure-function capabilities, etc.
-    const attachedCaps = new Set(
-      entities.flatMap(entity =>
-        capabilities.filter(c =>
-          c.params.some(p => p.type.kind === "EntityRefType" && p.type.name === entity.name)
-        )
-      )
-    );
-    const standaloneCaps = capabilities.filter(c => !attachedCaps.has(c));
-    if (standaloneCaps.length > 0) {
-      const utilMethods = standaloneCaps.map(cap => lowerCapability(cap));
-      modules.push({
-        id: makeId(this.systemName, "api_service", "UtilityService"),
-        kind: "api_service",
-        name: "UtilityService",
-        interfaces: [{ name: "IUtilityService", methods: utilMethods }],
-        models: [],
-        events: [],
-        state_machines: [],
-        relations: [],
-        dependencies: [],
-        config: { authenticated: false, auth_method: "none" },
-      });
-    }
-
-    // Channels → realtime_service modules
-    for (const channel of channels) {
-      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) {
-      const source = eventSourceMap.get(ev.name) || "unknown";
-      events.push(lowerEvent(this.systemName, ev, source));
-    }
-
-    // Flows
-    for (const flow of flowDecls) {
-      flows.push(lowerFlow(this.systemName, flow));
-    }
-
-    // Constraints → invariants
-    for (const c of constraints) {
-      invariants.push({
-        id: makeId(this.systemName, "invariant", c.name),
-        expression: serializeExpr(c.expr),
-        scope: "global",
-      });
-    }
-
-    // Gateway module (always present per ontology)
-    const gatewayConfig: Record<string, string | number | boolean> = {
-      rate_limit: 1000,
-      cors: true,
-      tls: true,
-    };
-    if (policies.length > 0) {
-      const mainPolicy = policies[0];
-      if (mainPolicy.rateLimit) gatewayConfig["rate_limit"] = mainPolicy.rateLimit.count;
-      if (mainPolicy.encryption) gatewayConfig["encryption"] = mainPolicy.encryption;
-    }
-    modules.push({
-      id: makeId(this.systemName, "gateway", "APIGateway"),
-      kind: "gateway",
-      name: "APIGateway",
-      interfaces: [],
-      models: [],
-      events: [],
-      state_machines: [],
-      relations: [],
-      dependencies: modules
-        .filter(m => m.kind === "api_service" || m.kind === "realtime_service")
-        .map(m => m.id),
-      config: gatewayConfig,
-    });
-
-    return {
-      name: sys.name,
-      version: "1.0.0",
-      source_hash: sourceHash,
-      domain: sys.domain,
-      modules,
-      events,
-      flows,
-      invariants,
-      resolution: {},
-      extension_points: extensionPoints.map(ep => ({
-        name: ep.name,
-        params: ep.params.map(p => ({ name: p.name, type: serializeType(p.type) })),
-        returns: ep.returns ? serializeType(ep.returns) : null,
-        stable: ep.stable,
-      })),
-    };
-  }
-}
+/**
+ * bone ir Lowering — Stage 4 of the compilation pipeline.
+ * Converts typed AST into the Architecture IR (spec/07_IR_SPEC.md).
+ *
+ * Rules:
+ * - One module per semantic component
+ * - All IDs are deterministic (derived from system name + component name)
+ * - All ontology-entailed fields are inserted
+ * - Effects are serialized in declaration order
+ */
+
+import { createHash } from "crypto";
+import * as AST from "./ast";
+import * as IR from "./ir";
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+// ─── Deterministic ID Generation ─────────────────────────────────────────────
+
+function makeId(systemName: string, kind: string, name: string): string {
+  const input = `${systemName}.${kind}.${name}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+
+// ─── Duration Parsing ────────────────────────────────────────────────────────
+
+function parseDurationMs(dur: string | null): number | null {
+  if (!dur) return null;
+  const match = dur.match(/^(\d+)(ms|s|m|h|d)$/);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  switch (match[2]) {
+    case "ms": return value;
+    case "s": return value * 1000;
+    case "m": return value * 60_000;
+    case "h": return value * 3_600_000;
+    case "d": return value * 86_400_000;
+    default: return null;
+  }
+}
+
+// ─── Type Expression Serialization ───────────────────────────────────────────
+
+function serializeType(t: AST.TypeExprNode): string {
+  switch (t.kind) {
+    case "PrimitiveType": return t.name;
+    case "GenericType": return `${t.name}<${t.typeArgs.map(serializeType).join(", ")}>`;
+    case "EntityRefType": return t.name;
+    case "TupleType": return `(${t.elements.map(serializeType).join(", ")})`;
+    case "UnionType": return t.members.map(serializeType).join(" | ");
+  }
+}
+
+// ─── Expression Serialization ────────────────────────────────────────────────
+
+function serializeExpr(e: AST.ExprNode): string {
+  switch (e.kind) {
+    case "Literal":
+      if (e.type === "string") return `"${e.value}"`;
+      if (e.type === "list") return `[${(e.value as AST.ExprNode[]).map(serializeExpr).join(", ")}]`;
+      return String(e.value);
+    case "FieldRef":
+      return e.path.join(".");
+    case "BinaryExpr":
+      return `(${serializeExpr(e.left)} ${e.op} ${serializeExpr(e.right)})`;
+    case "UnaryExpr":
+      return `(${e.op} ${serializeExpr(e.operand)})`;
+    case "CallExpr":
+      return `${e.name}(${e.args.map(serializeExpr).join(", ")})`;
+    case "TernaryExpr":
+      return `(${serializeExpr(e.condition)} ? ${serializeExpr(e.consequent)} : ${serializeExpr(e.alternate)})`;
+  }
+}
+
+// ─── Lowering Engine ─────────────────────────────────────────────────────────
+
+export class Lowering {
+  private systemName: string = "";
+
+  lower(program: AST.ProgramNode, sourceHash: string): IR.IRSystem[] {
+    const systems: IR.IRSystem[] = [];
+
+    for (const sys of program.systems) {
+      systems.push(this.lowerSystem(sys, sourceHash));
+    }
+
+    return systems;
+  }
+
+  private lowerSystem(sys: AST.SystemDeclNode, sourceHash: string): IR.IRSystem {
+    this.systemName = sys.name;
+
+    const modules: IR.IRModule[] = [];
+    const events: IR.IREvent[] = [];
+    const flows: IR.IRFlow[] = [];
+    const invariants: IR.IRInvariant[] = [];
+
+    // Collect declarations by type
+    const entities = sys.declarations.filter((d): d is AST.EntityDeclNode => d.kind === "EntityDecl");
+    const capabilities = sys.declarations.filter((d): d is AST.CapabilityDeclNode => d.kind === "CapabilityDecl");
+    const channels = sys.declarations.filter((d): d is AST.ChannelDeclNode => d.kind === "ChannelDecl");
+    const stores = sys.declarations.filter((d): d is AST.StoreDeclNode => d.kind === "StoreDecl");
+    const eventDecls = sys.declarations.filter((d): d is AST.EventDeclNode => d.kind === "EventDecl");
+    const constraints = sys.declarations.filter((d): d is AST.ConstraintDeclNode => d.kind === "ConstraintDecl");
+    const policies = sys.declarations.filter((d): d is AST.PolicyDeclNode => d.kind === "PolicyDecl");
+    const flowDecls = sys.declarations.filter((d): d is AST.FlowDeclNode => d.kind === "FlowDecl");
+    const extensionPoints = sys.declarations.filter((d): d is AST.ExtensionPointDeclNode => d.kind === "ExtensionPointDecl");
+
+    // Lower stores → data_store modules
+    for (const store of stores) {
+      modules.push(this.lowerStore(store));
+    }
+
+    // Lower entities → api_service modules (with CRUD + capabilities)
+    for (const entity of entities) {
+      const relatedCaps = capabilities.filter(c =>
+        c.params.some(p => p.type.kind === "EntityRefType" && p.type.name === entity.name)
+      );
+      modules.push(this.lowerEntity(entity, relatedCaps, stores));
+    }
+
+    // Lower channels → realtime_service modules
+    for (const channel of channels) {
+      modules.push(this.lowerChannel(channel));
+    }
+
+    // Lower events
+    for (const ev of eventDecls) {
+      events.push(this.lowerEvent(ev));
+    }
+
+    // Lower flows
+    for (const flow of flowDecls) {
+      flows.push(this.lowerFlow(flow));
+    }
+
+    // Lower constraints → invariants
+    for (const c of constraints) {
+      invariants.push({
+        id: makeId(this.systemName, "invariant", c.name),
+        expression: serializeExpr(c.expr),
+        scope: "global",
+      });
+    }
+
+    // Add gateway module (ontology: always present)
+    const gatewayConfig: Record<string, string | number | boolean> = {
+      rate_limit: 1000,
+      cors: true,
+      tls: true,
+    };
+    if (policies.length > 0) {
+      const mainPolicy = policies[0];
+      if (mainPolicy.rateLimit) {
+        gatewayConfig["rate_limit"] = mainPolicy.rateLimit.count;
+      }
+      if (mainPolicy.encryption) {
+        gatewayConfig["encryption"] = mainPolicy.encryption;
+      }
+    }
+    modules.push({
+      id: makeId(this.systemName, "gateway", "APIGateway"),
+      kind: "gateway",
+      name: "APIGateway",
+      interfaces: [],
+      models: [],
+      events: [],
+      state_machines: [],
+      relations: [],
+      dependencies: modules.filter(m => m.kind === "api_service" || m.kind === "realtime_service").map(m => m.id),
+      config: gatewayConfig,
+    });
+
+    return {
+      name: sys.name,
+      version: "1.0.0",
+      source_hash: sourceHash,
+      domain: sys.domain,
+      modules,
+      events,
+      flows,
+      invariants,
+      resolution: {},
+      extension_points: extensionPoints.map(ep => ({
+        name: ep.name,
+        params: ep.params.map(p => ({ name: p.name, type: serializeType(p.type) })),
+        returns: ep.returns ? serializeType(ep.returns) : null,
+        stable: ep.stable,
+      })),
+    };
+  }
+
+  // ─── Store Lowering ────────────────────────────────────────────────────────
+
+  private lowerStore(store: AST.StoreDeclNode): IR.IRModule {
+    // Strip "Store" suffix from model name so SellerStore → Seller → table "sellers"
+    const entityName = store.name.replace(/Store$/, "") || store.name;
+    const model: IR.IRModel = {
+      name: entityName,
+      fields: store.schema.map(f => this.lowerField(f)),
+      primary_key: "id",
+      indexes: [],
+      constraints: [],
+    };
+
+    // Add id field if not present
+    if (!model.fields.find(f => f.name === "id")) {
+      model.fields.unshift({
+        name: "id", type: "uuid", nullable: false, unique: true, indexed: true, default_value: "gen_random_uuid()",
+      });
+    }
+
+    return {
+      id: makeId(this.systemName, "data_store", store.name),
+      kind: "data_store",
+      name: store.name,
+      interfaces: [],
+      models: [model],
+      events: [],
+      state_machines: [],
+      relations: [],
+      dependencies: [],
+      config: {
+        engine: store.engine || "postgresql",
+        replicas: store.replicas || 1,
+        ...(store.retention ? { retention_ms: parseDurationMs(store.retention) || 0 } : {}),
+        ...(store.partition ? { partition_key: store.partition } : {}),
+      },
+    };
+  }
+
+  // ─── Entity Lowering ───────────────────────────────────────────────────────
+
+  private lowerEntity(entity: AST.EntityDeclNode, capabilities: AST.CapabilityDeclNode[], stores: AST.StoreDeclNode[]): IR.IRModule {
+    const moduleId = makeId(this.systemName, "api_service", `${entity.name}Service`);
+
+    // Build model from entity fields + ontology entailments
+    const fields: IR.IRField[] = [
+      { name: "id", type: "uuid", nullable: false, unique: true, indexed: true, default_value: "gen_random_uuid()" },
+      { name: "created_at", type: "timestamp", nullable: false, unique: false, indexed: true, default_value: "now()" },
+      { name: "updated_at", type: "timestamp", nullable: false, unique: false, indexed: false, default_value: "now()" },
+    ];
+    for (const f of entity.owns) {
+      fields.push(this.lowerField(f));
+    }
+
+    // Add derived fields as generated columns (stored: false = virtual)
+    const derivedFields: IR.IRField[] = entity.derived.map(d => ({
+      name: d.name,
+      type: "json", // type inferred at runtime
+      nullable: true,
+      unique: false,
+      indexed: false,
+      default_value: `GENERATED ALWAYS AS (${serializeExpr(d.expr)}) STORED`,
+    }));
+
+    // Build indexes from entity index declarations
+    const indexes: IR.IRIndex[] = [];
+    for (const idx of entity.indexes) {
+      indexes.push({ fields: idx, unique: false });
+    }
+
+    // Build constraints from entity constraints
+    const modelConstraints: IR.IRModelConstraint[] = [];
+    for (const c of entity.constraints) {
+      const serialized = serializeExpr(c);
+      // Detect unique constraints
+      if (c.kind === "FieldRef" && c.path[c.path.length - 1] === "unique") {
+        const field = c.path.slice(0, -1).join(".");
+        modelConstraints.push({ kind: "unique", target: field, params: {} });
+        indexes.push({ fields: [field], unique: true });
+      } else {
+        modelConstraints.push({ kind: "check", target: entity.name, params: { expression: serialized } });
+      }
+    }
+
+    const model: IR.IRModel = {
+      name: entity.name,
+      fields: [...fields, ...derivedFields],
+      primary_key: "id",
+      indexes,
+      constraints: modelConstraints,
+    };
+
+    // Build state machine if entity has states
+    const stateMachines: IR.IRStateMachine[] = [];
+    if (entity.states) {
+      const states = entity.states.nodes.map(n => n.name);
+      const transitions: IR.IRTransition[] = [];
+      for (const node of entity.states.nodes) {
+        for (const target of node.transitions) {
+          transitions.push({ from: node.name, to: target, trigger: `${node.name}_to_${target}`, guard: null });
+        }
+        for (const target of node.branches) {
+          transitions.push({ from: node.name, to: target, trigger: `${node.name}_to_${target}`, guard: null });
+        }
+      }
+      stateMachines.push({
+        entity: entity.name,
+        states,
+        initial: states[0],
+        transitions,
+      });
+    }
+
+    // Build interface from capabilities
+    const methods: IR.IRMethod[] = [];
+
+    // CRUD methods (always generated for entities)
+    methods.push(this.makeCrudMethod("create", entity.name, fields));
+    methods.push(this.makeCrudMethod("read", entity.name, fields));
+    methods.push(this.makeCrudMethod("update", entity.name, fields));
+    methods.push(this.makeCrudMethod("delete", entity.name, fields));
+    methods.push(this.makeCrudMethod("list", entity.name, fields));
+
+    // Capability-derived methods
+    for (const cap of capabilities) {
+      methods.push(this.lowerCapability(cap));
+    }
+
+    const iface: IR.IRInterface = {
+      name: `I${entity.name}Service`,
+      methods,
+    };
+
+    // Find related store
+    const relatedStore = stores.find(s => s.name.toLowerCase().includes(entity.name.toLowerCase()));
+    const deps: string[] = [];
+    if (relatedStore) {
+      deps.push(makeId(this.systemName, "data_store", relatedStore.name));
+    }
+
+    // Lower relations
+    const relations: IR.IRRelation[] = entity.relations.map(rel => {
+      const fromTable = toSnakeCase(entity.name) + "s";
+      const toTable = toSnakeCase(rel.target) + "s";
+      let foreignKey: string;
+      let junctionTable: string | undefined;
+
+      switch (rel.relationType) {
+        case "belongs_to":
+          foreignKey = toSnakeCase(rel.target) + "_id";
+          break;
+        case "has_one":
+        case "has_many":
+          foreignKey = toSnakeCase(entity.name) + "_id";
+          break;
+        case "many_to_many":
+          foreignKey = toSnakeCase(entity.name) + "_id";
+          junctionTable = [fromTable, toTable].sort().join("_");
+          break;
+        default:
+          foreignKey = toSnakeCase(rel.target) + "_id";
+      }
+
+      return {
+        name: rel.name,
+        kind: rel.relationType,
+        from_entity: entity.name,
+        to_entity: rel.target,
+        from_table: fromTable,
+        to_table: toTable,
+        foreign_key: foreignKey,
+        junction_table: junctionTable,
+      };
+    });
+
+    return {
+      id: moduleId,
+      kind: "api_service",
+      name: `${entity.name}Service`,
+      interfaces: [iface],
+      models: [model],
+      events: [],
+      state_machines: stateMachines,
+      relations,
+      dependencies: deps,
+      config: {
+        authenticated: entity.auth !== null && entity.auth !== "none",
+        auth_method: entity.auth || "none",
+      },
+    };
+  }
+
+  private makeCrudMethod(op: string, entityName: string, fields: IR.IRField[]): IR.IRMethod {
+    const input: IR.IRField[] = op === "create" || op === "update"
+      ? fields.filter(f => f.name !== "id" && f.name !== "created_at" && f.name !== "updated_at")
+      : op === "list"
+        ? [
+            { name: "page", type: "uint", nullable: true, unique: false, indexed: false, default_value: "1" },
+            { name: "page_size", type: "uint", nullable: true, unique: false, indexed: false, default_value: "50" },
+          ]
+        : [{ name: "id", type: "uuid", nullable: false, unique: true, indexed: true, default_value: null }];
+
+    return {
+      name: op,
+      input,
+      output: op === "list" ? `list<${entityName}>` : op === "delete" ? "bool" : entityName,
+      preconditions: [],
+      effects: [],
+      emissions: [],
+      idempotent: op === "read" || op === "list",
+      authenticated: true,
+      timeout_ms: 30000,
+      retry: null,
+      pipeline: null,
+      algorithm: null,
+      sync: null,
+    };
+  }
+
+  private lowerCapability(cap: AST.CapabilityDeclNode): IR.IRMethod {
+    const input: IR.IRField[] = cap.params.map(p => ({
+      name: p.name,
+      type: serializeType(p.type),
+      nullable: false,
+      unique: false,
+      indexed: false,
+      default_value: null,
+    }));
+
+    const preconditions: IR.IRPrecondition[] = cap.requires.map(r => ({
+      expression: serializeExpr(r),
+      description: serializeExpr(r),
+    }));
+
+    const effects: IR.IREffect[] = cap.effects.map(e => ({
+      target: e.target.path.join("."),
+      op: e.op === "=" ? "assign" as const : e.op === "+=" ? "add" as const : "remove" as const,
+      value: serializeExpr(e.value),
+    }));
+
+    const emissions = cap.emits.map(e => e.eventName);
+
+    // Lower pipeline if present
+    let pipeline: IR.IRPipeline | null = null;
+    if (cap.pipeline) {
+      pipeline = {
+        parallel: cap.pipeline.parallel,
+        steps: cap.pipeline.steps.map(step => ({
+          call_name: step.call.name,
+          call_args: step.call.args.map(a => serializeExpr(a)),
+          bind_as: step.bindAs,
+        })),
+        on_error: cap.pipeline.onError ? {
+          action: cap.pipeline.onError.action,
+          call_name: cap.pipeline.onError.call?.name || null,
+          call_args: cap.pipeline.onError.call?.args.map(a => serializeExpr(a)) || [],
+        } : null,
+      };
+    }
+
+    // Lower algorithm if present
+    let algorithm: IR.IRAlgorithm | null = null;
+    if (cap.algorithm) {
+      algorithm = {
+        catalog_name: cap.algorithm.name,
+        bindings: cap.algorithm.using.map(b => ({
+          param: b.param,
+          value: serializeExpr(b.value),
+        })),
+      };
+    }
+
+    return {
+      name: cap.name,
+      input,
+      output: cap.returns ? serializeType(cap.returns) : "result<void, error>",
+      preconditions,
+      effects,
+      emissions,
+      idempotent: cap.idempotent || false,
+      authenticated: true,
+      timeout_ms: parseDurationMs(cap.timeout) || 30000,
+      retry: cap.retry ? {
+        max_attempts: cap.retry.maxAttempts || 3,
+        backoff: (cap.retry.backoff as IR.IRRetryPolicy["backoff"]) || "exponential",
+        interval_ms: parseDurationMs(cap.retry.interval) || 1000,
+      } : null,
+      pipeline,
+      algorithm,
+      sync: cap.sync,
+    };
+  }
+
+  // ─── Channel Lowering ──────────────────────────────────────────────────────
+
+  private lowerChannel(channel: AST.ChannelDeclNode): IR.IRModule {
+    return {
+      id: makeId(this.systemName, "realtime_service", channel.name),
+      kind: "realtime_service",
+      name: channel.name,
+      interfaces: [{
+        name: `I${channel.name}Channel`,
+        methods: [
+          { name: "connect", input: [], output: "connection", preconditions: [], effects: [], emissions: [], idempotent: false, authenticated: true, timeout_ms: 5000, retry: null, pipeline: null, algorithm: null, sync: null },
+          { name: "subscribe", input: [{ name: "topic", type: "string", nullable: false, unique: false, indexed: false, default_value: null }], output: "subscription", preconditions: [], effects: [], emissions: [], idempotent: true, authenticated: true, timeout_ms: 5000, retry: null, pipeline: null, algorithm: null, sync: null },
+          { name: "publish", input: [{ name: "message", type: "json", nullable: false, unique: false, indexed: false, default_value: null }], output: "void", preconditions: [], effects: [], emissions: [], idempotent: false, authenticated: true, timeout_ms: 5000, retry: null, pipeline: null, algorithm: null, sync: null },
+        ],
+      }],
+      models: [],
+      events: [],
+      state_machines: [],
+      relations: [],
+      dependencies: [],
+      config: {
+        transport: channel.transport || "websocket",
+        ordering: channel.ordering || "fifo",
+        persistence: channel.persistence || "none",
+        max_size: channel.maxSize || 10000,
+      },
+    };
+  }
+
+  // ─── Event Lowering ────────────────────────────────────────────────────────
+
+  private lowerEvent(ev: AST.EventDeclNode): IR.IREvent {
+    return {
+      id: makeId(this.systemName, "event", ev.name),
+      name: ev.name,
+      payload: ev.payload.map(f => this.lowerField(f)),
+      source: "unknown", // resolved during dependency resolution
+      delivery: (ev.delivery as IR.IRDeliveryMode) || "at_least_once",
+      ordering: "fifo",
+      ttl_ms: parseDurationMs(ev.ttl),
+    };
+  }
+
+  // ─── Flow Lowering ─────────────────────────────────────────────────────────
+
+  private lowerFlow(flow: AST.FlowDeclNode): IR.IRFlow {
+    return {
+      name: flow.name,
+      steps: flow.steps.map(s => ({
+        name: s.name,
+        action: `${s.action.name}(${s.action.args.map(serializeExpr).join(", ")})`,
+        compensation: s.compensate ? `${s.compensate.name}(${s.compensate.args.map(serializeExpr).join(", ")})` : null,
+      })),
+    };
+  }
+
+  // ─── Field Lowering ────────────────────────────────────────────────────────
+
+  private lowerField(f: AST.FieldNode): IR.IRField {
+    return {
+      name: f.name,
+      type: serializeType(f.type),
+      nullable: f.type.kind === "GenericType" && f.type.name === "optional",
+      unique: false,
+      indexed: false,
+      default_value: f.defaultValue ? serializeExpr(f.defaultValue) : null,
+    };
+  }
+}