redscript-mc 1.2.30 → 2.1.0

package/src/hir/monomorphize.ts

@@ -0,0 +1,416 @@
+/**
+ * HIR Monomorphization — Phase 2c: Generic functions
+ *
+ * For each generic function `fn foo<T>(...)`, each unique instantiation
+ * `foo<int>`, `foo<float>` etc. produces a concrete copy with a mangled name.
+ *
+ * Algorithm:
+ * 1. Walk the HIR module collecting all call sites to generic functions.
+ * 2. For each unique (fnName, typeArgs) pair, clone the generic HIRFunction,
+ *    substitute all occurrences of the type params, and add to module.functions.
+ * 3. Rewrite every call site: `foo<int>(x, y)` → `foo_int(x, y)`.
+ * 4. Remove original generic function definitions from the output.
+ *
+ * Type arg → suffix mapping:
+ *   int      → "int"
+ *   float    → "float"
+ *   bool     → "bool"
+ *   string   → "string"
+ *   (others) → use struct/enum name
+ */
+
+import type {
+  HIRModule, HIRFunction, HIRParam, HIRExpr, HIRStmt, HIRBlock,
+  TypeNode,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function monomorphize(module: HIRModule): HIRModule {
+  const mono = new Monomorphizer(module)
+  return mono.run()
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Return a stable string suffix for a type argument, used in mangled names. */
+function typeSuffix(t: TypeNode): string {
+  switch (t.kind) {
+    case 'named': return t.name
+    case 'struct': return t.name
+    case 'enum':   return t.name
+    case 'array':  return `arr_${typeSuffix(t.elem)}`
+    case 'tuple':  return `tup_${t.elements.map(typeSuffix).join('_')}`
+    case 'option': return `opt_${typeSuffix(t.inner)}`
+    default:       return 'unknown'
+  }
+}
+
+/** Produce the mangled name for a specialization, e.g. "max_int". */
+function mangledName(fnName: string, typeArgs: TypeNode[]): string {
+  return `${fnName}_${typeArgs.map(typeSuffix).join('_')}`
+}
+
+/** Build a substitution map: type param name → concrete type. */
+function buildSubst(typeParams: string[], typeArgs: TypeNode[]): Map<string, TypeNode> {
+  const subst = new Map<string, TypeNode>()
+  for (let i = 0; i < typeParams.length; i++) {
+    subst.set(typeParams[i], typeArgs[i])
+  }
+  return subst
+}
+
+/** Apply substitution to a TypeNode (replacing struct-kind nodes whose name
+ *  matches a type param with the concrete type). */
+function substType(t: TypeNode, subst: Map<string, TypeNode>): TypeNode {
+  switch (t.kind) {
+    case 'struct': {
+      const replacement = subst.get(t.name)
+      if (replacement) return replacement
+      return t
+    }
+    case 'array':
+      return { kind: 'array', elem: substType(t.elem, subst) }
+    case 'tuple':
+      return { kind: 'tuple', elements: t.elements.map(e => substType(e, subst)) }
+    case 'option':
+      return { kind: 'option', inner: substType(t.inner, subst) }
+    case 'function_type':
+      return { kind: 'function_type', params: t.params.map(p => substType(p, subst)), return: substType(t.return, subst) }
+    default:
+      return t
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Monomorphizer
+// ---------------------------------------------------------------------------
+
+/** Context passed through expression/statement rewriting. */
+interface RewriteCtx {
+  /** Type substitution: type param name → concrete type */
+  subst: Map<string, TypeNode>
+  /** Variable scope: variable name → concrete type (for inference) */
+  varTypes: Map<string, TypeNode>
+}
+
+class Monomorphizer {
+  private module: HIRModule
+  /** Map from function name → HIRFunction for generic functions */
+  private genericFns: Map<string, HIRFunction> = new Map()
+  /** Cache: cacheKey → specialized HIRFunction (to avoid duplicate generation) */
+  private specialized: Map<string, HIRFunction> = new Map()
+  /** Worklist for BFS specialization (to handle generic calling generic) */
+  private worklist: Array<{ fn: HIRFunction; typeArgs: TypeNode[] }> = []
+
+  constructor(module: HIRModule) {
+    this.module = module
+  }
+
+  run(): HIRModule {
+    // Collect all generic function definitions
+    for (const fn of this.module.functions) {
+      if (fn.typeParams && fn.typeParams.length > 0) {
+        this.genericFns.set(fn.name, fn)
+      }
+    }
+
+    if (this.genericFns.size === 0) {
+      // Nothing to do — fast path
+      return this.module
+    }
+
+    // Rewrite all non-generic functions, collecting specializations needed
+    const newFunctions: HIRFunction[] = []
+    for (const fn of this.module.functions) {
+      if (fn.typeParams && fn.typeParams.length > 0) {
+        // Skip generic function templates — they'll be replaced by specializations
+        continue
+      }
+      const rewritten = this.rewriteFn(fn)
+      newFunctions.push(rewritten)
+    }
+
+    // Process worklist BFS: generate specializations (which may add more to worklist)
+    while (this.worklist.length > 0) {
+      const { fn: templateFn, typeArgs } = this.worklist.shift()!
+      const key = this.cacheKey(templateFn.name, typeArgs)
+      if (this.specialized.has(key)) continue
+      // Mark as in-progress to prevent cycles
+      this.specialized.set(key, null as unknown as HIRFunction)
+      const specializedFn = this.specialize(templateFn, typeArgs)
+      this.specialized.set(key, specializedFn)
+    }
+
+    // Add all specializations
+    for (const fn of this.specialized.values()) {
+      if (fn) newFunctions.push(fn)
+    }
+
+    return { ...this.module, functions: newFunctions }
+  }
+
+  private cacheKey(fnName: string, typeArgs: TypeNode[]): string {
+    return `${fnName}|${typeArgs.map(typeSuffix).join(',')}`
+  }
+
+  /** Specialize a generic function with concrete type args. */
+  private specialize(templateFn: HIRFunction, typeArgs: TypeNode[]): HIRFunction {
+    const subst = buildSubst(templateFn.typeParams!, typeArgs)
+    const name = mangledName(templateFn.name, typeArgs)
+
+    // Build initial variable scope from parameters
+    const varTypes = new Map<string, TypeNode>()
+    const params: HIRParam[] = templateFn.params.map(p => {
+      const concreteType = substType(p.type, subst)
+      varTypes.set(p.name, concreteType)
+      return {
+        name: p.name,
+        type: concreteType,
+        default: p.default ? this.rewriteExpr(p.default, { subst, varTypes }) : undefined,
+      }
+    })
+
+    const returnType = substType(templateFn.returnType, subst)
+    const body = this.rewriteBlock(templateFn.body, { subst, varTypes })
+
+    return {
+      name,
+      params,
+      returnType,
+      decorators: templateFn.decorators,
+      body,
+      isLibraryFn: templateFn.isLibraryFn,
+      isExported: templateFn.isExported,
+      span: templateFn.span,
+      // No typeParams on the specialized copy
+    }
+  }
+
+  /** Rewrite a non-generic function (substitute calls to generic functions). */
+  private rewriteFn(fn: HIRFunction): HIRFunction {
+    const varTypes = new Map<string, TypeNode>()
+    // Add params to scope with their concrete types
+    for (const p of fn.params) {
+      varTypes.set(p.name, p.type)
+    }
+    return {
+      ...fn,
+      params: fn.params.map(p => ({
+        ...p,
+        default: p.default ? this.rewriteExpr(p.default, { subst: new Map(), varTypes }) : undefined,
+      })),
+      body: this.rewriteBlock(fn.body, { subst: new Map(), varTypes }),
+    }
+  }
+
+  private rewriteBlock(block: HIRBlock, ctx: RewriteCtx): HIRBlock {
+    // Clone varTypes so block-local bindings don't leak
+    const localCtx: RewriteCtx = { subst: ctx.subst, varTypes: new Map(ctx.varTypes) }
+    const result: HIRBlock = []
+    for (const stmt of block) {
+      result.push(this.rewriteStmt(stmt, localCtx))
+    }
+    return result
+  }
+
+  private rewriteStmt(stmt: HIRStmt, ctx: RewriteCtx): HIRStmt {
+    const { subst } = ctx
+    switch (stmt.kind) {
+      case 'let': {
+        const init = this.rewriteExpr(stmt.init, ctx)
+        const type = stmt.type ? substType(stmt.type, subst) : undefined
+        // Track variable type in scope
+        if (type) ctx.varTypes.set(stmt.name, type)
+        else {
+          const inferred = this.inferExprType(init, ctx)
+          if (inferred) ctx.varTypes.set(stmt.name, inferred)
+        }
+        return { ...stmt, type, init }
+      }
+      case 'let_destruct':
+        return { ...stmt, type: stmt.type ? substType(stmt.type, subst) : undefined, init: this.rewriteExpr(stmt.init, ctx) }
+      case 'expr':
+        return { ...stmt, expr: this.rewriteExpr(stmt.expr, ctx) }
+      case 'return':
+        return { ...stmt, value: stmt.value ? this.rewriteExpr(stmt.value, ctx) : undefined }
+      case 'if':
+        return {
+          ...stmt,
+          cond: this.rewriteExpr(stmt.cond, ctx),
+          then: this.rewriteBlock(stmt.then, ctx),
+          else_: stmt.else_ ? this.rewriteBlock(stmt.else_, ctx) : undefined,
+        }
+      case 'while':
+        return {
+          ...stmt,
+          cond: this.rewriteExpr(stmt.cond, ctx),
+          body: this.rewriteBlock(stmt.body, ctx),
+          step: stmt.step ? this.rewriteBlock(stmt.step, ctx) : undefined,
+        }
+      case 'foreach':
+        return { ...stmt, iterable: this.rewriteExpr(stmt.iterable, ctx), body: this.rewriteBlock(stmt.body, ctx) }
+      case 'match':
+        return {
+          ...stmt,
+          expr: this.rewriteExpr(stmt.expr, ctx),
+          arms: stmt.arms.map(arm => ({
+            pattern: arm.pattern ? this.rewriteExpr(arm.pattern, ctx) : null,
+            body: this.rewriteBlock(arm.body, ctx),
+          })),
+        }
+      case 'execute':
+        return { ...stmt, body: this.rewriteBlock(stmt.body, ctx) }
+      case 'if_let_some':
+        return {
+          ...stmt,
+          init: this.rewriteExpr(stmt.init, ctx),
+          then: this.rewriteBlock(stmt.then, ctx),
+          else_: stmt.else_ ? this.rewriteBlock(stmt.else_, ctx) : undefined,
+        }
+      case 'break':
+      case 'continue':
+      case 'raw':
+        return stmt
+    }
+  }
+
+  private rewriteExpr(expr: HIRExpr, ctx: RewriteCtx): HIRExpr {
+    const { subst } = ctx
+    switch (expr.kind) {
+      case 'call': {
+        const args = expr.args.map(a => this.rewriteExpr(a, ctx))
+        // Determine concrete type args for this call
+        const resolvedTypeArgs: TypeNode[] | undefined = expr.typeArgs?.map(t => substType(t, subst))
+        const genericFn = this.genericFns.get(expr.fn)
+        if (genericFn && genericFn.typeParams && genericFn.typeParams.length > 0) {
+          // This call targets a generic function — we need to monomorphize
+          const concreteTypeArgs = resolvedTypeArgs ?? this.inferTypeArgs(genericFn, args, ctx)
+          if (concreteTypeArgs) {
+            const key = this.cacheKey(expr.fn, concreteTypeArgs)
+            if (!this.specialized.has(key)) {
+              // Enqueue for specialization
+              this.worklist.push({ fn: genericFn, typeArgs: concreteTypeArgs })
+            }
+            const name = mangledName(expr.fn, concreteTypeArgs)
+            return { ...expr, fn: name, args, typeArgs: undefined }
+          }
+        }
+        return { ...expr, args, typeArgs: resolvedTypeArgs }
+      }
+      case 'invoke':
+        return { ...expr, callee: this.rewriteExpr(expr.callee, ctx), args: expr.args.map(a => this.rewriteExpr(a, ctx)) }
+      case 'binary':
+        return { ...expr, left: this.rewriteExpr(expr.left, ctx), right: this.rewriteExpr(expr.right, ctx) }
+      case 'unary':
+        return { ...expr, operand: this.rewriteExpr(expr.operand, ctx) }
+      case 'assign':
+        return { ...expr, value: this.rewriteExpr(expr.value, ctx) }
+      case 'member_assign':
+        return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), value: this.rewriteExpr(expr.value, ctx) }
+      case 'member':
+        return { ...expr, obj: this.rewriteExpr(expr.obj, ctx) }
+      case 'index':
+        return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), index: this.rewriteExpr(expr.index, ctx) }
+      case 'array_lit':
+        return { ...expr, elements: expr.elements.map(e => this.rewriteExpr(e, ctx)) }
+      case 'struct_lit':
+        return { ...expr, fields: expr.fields.map(f => ({ name: f.name, value: this.rewriteExpr(f.value, ctx) })) }
+      case 'tuple_lit':
+        return { ...expr, elements: expr.elements.map(e => this.rewriteExpr(e, ctx)) }
+      case 'static_call':
+        return { ...expr, args: expr.args.map(a => this.rewriteExpr(a, ctx)) }
+      case 'lambda':
+        return { ...expr, body: Array.isArray(expr.body) ? this.rewriteBlock(expr.body as HIRBlock, ctx) : this.rewriteExpr(expr.body as HIRExpr, ctx) }
+      case 'is_check':
+        return { ...expr, expr: this.rewriteExpr(expr.expr, ctx) }
+      case 'str_interp':
+        return { ...expr, parts: expr.parts.map(p => typeof p === 'string' ? p : this.rewriteExpr(p, ctx)) }
+      case 'f_string':
+        // FStringPart uses AST Expr (not HIRExpr) — pass through without rewriting
+        return expr
+      case 'some_lit':
+        return { ...expr, value: this.rewriteExpr(expr.value, ctx) }
+      case 'none_lit':
+        return expr
+      // Literals / terminals — pass through unchanged
+      default:
+        return expr
+    }
+  }
+
+  /**
+   * Infer type args from the actual argument expressions.
+   * Works by looking at the types of call arguments and matching them to
+   * the type parameters in the function signature.
+   *
+   * Returns null if inference fails.
+   */
+  private inferTypeArgs(fn: HIRFunction, args: HIRExpr[], ctx: RewriteCtx): TypeNode[] | null {
+    const inferred = new Map<string, TypeNode>()
+    const typeParams = fn.typeParams!
+
+    for (let i = 0; i < fn.params.length && i < args.length; i++) {
+      const paramType = fn.params[i].type
+      const argType = this.inferExprType(args[i], ctx)
+      if (argType) {
+        this.matchTypes(paramType, argType, typeParams, inferred)
+      }
+    }
+
+    // Check all type params were inferred
+    if (typeParams.every(tp => inferred.has(tp))) {
+      return typeParams.map(tp => inferred.get(tp)!)
+    }
+    return null
+  }
+
+  /** Walk a type pattern and a concrete type, binding type param names. */
+  private matchTypes(pattern: TypeNode, concrete: TypeNode, typeParams: string[], inferred: Map<string, TypeNode>): void {
+    if (pattern.kind === 'struct' && typeParams.includes(pattern.name)) {
+      // This position is a type param — bind it
+      if (!inferred.has(pattern.name)) {
+        inferred.set(pattern.name, concrete)
+      }
+      return
+    }
+    if (pattern.kind === 'array' && concrete.kind === 'array') {
+      this.matchTypes(pattern.elem, concrete.elem, typeParams, inferred)
+      return
+    }
+    if (pattern.kind === 'tuple' && concrete.kind === 'tuple') {
+      for (let i = 0; i < pattern.elements.length && i < concrete.elements.length; i++) {
+        this.matchTypes(pattern.elements[i], concrete.elements[i], typeParams, inferred)
+      }
+    }
+  }
+
+  /** Infer the type of a HIR expression (best-effort, for type inference). */
+  private inferExprType(expr: HIRExpr, ctx: RewriteCtx): TypeNode | null {
+    switch (expr.kind) {
+      case 'int_lit':    return { kind: 'named', name: 'int' }
+      case 'float_lit':  return { kind: 'named', name: 'float' }
+      case 'bool_lit':   return { kind: 'named', name: 'bool' }
+      case 'str_lit':    return { kind: 'named', name: 'string' }
+      case 'byte_lit':   return { kind: 'named', name: 'byte' }
+      case 'short_lit':  return { kind: 'named', name: 'short' }
+      case 'long_lit':   return { kind: 'named', name: 'long' }
+      case 'double_lit': return { kind: 'named', name: 'double' }
+      case 'ident':      return ctx.varTypes.get(expr.name) ?? null
+      case 'unary':
+        // unary minus/not preserves the operand's type
+        return this.inferExprType(expr.operand, ctx)
+      case 'binary': {
+        // For arithmetic, use the left operand's type
+        const lt = this.inferExprType(expr.left, ctx)
+        if (lt) return lt
+        return this.inferExprType(expr.right, ctx)
+      }
+      default: return null
+    }
+  }
+}

package/src/hir/types.ts

@@ -0,0 +1,228 @@
+/**
+ * HIR (High-level IR) Types — Stage 2 of the RedScript compiler pipeline.
+ *
+ * HIR is a desugared, structured representation. Compared to the AST:
+ * - `for` loops → `while` loops with explicit init/step
+ * - `a += b` → `a = a + b`
+ * - `a && b` → `if(a) { b } else { false }`
+ * - `a || b` → `if(a) { true } else { b }`
+ * - `cond ? a : b` → if/else expression (not present in RedScript, but pattern applies)
+ * - `as_block`, `at_block`, `as_at` → unified `execute` with subcommands
+ *
+ * All types and names are preserved from the AST.
+ */
+
+import type {
+  Span,
+  TypeNode,
+  EntitySelector,
+  CoordComponent,
+  Decorator,
+  RangeExpr,
+  FStringPart,
+  SelectorFilter,
+  EntityTypeName,
+  LambdaParam,
+} from '../ast/types'
+import type { BinOp, CmpOp } from '../ast/types'
+
+// Re-export types that HIR shares with AST unchanged
+export type {
+  Span,
+  TypeNode,
+  EntitySelector,
+  CoordComponent,
+  Decorator,
+  RangeExpr,
+  FStringPart,
+  SelectorFilter,
+  EntityTypeName,
+  LambdaParam,
+  BinOp,
+  CmpOp,
+}
+
+// ---------------------------------------------------------------------------
+// HIR Expressions
+// ---------------------------------------------------------------------------
+
+export type HIRExpr =
+  // Literals
+  | { kind: 'int_lit'; value: number; span?: Span }
+  | { kind: 'float_lit'; value: number; span?: Span }
+  | { kind: 'byte_lit'; value: number; span?: Span }
+  | { kind: 'short_lit'; value: number; span?: Span }
+  | { kind: 'long_lit'; value: number; span?: Span }
+  | { kind: 'double_lit'; value: number; span?: Span }
+  | { kind: 'bool_lit'; value: boolean; span?: Span }
+  | { kind: 'str_lit'; value: string; span?: Span }
+  | { kind: 'range_lit'; range: RangeExpr; span?: Span }
+  | { kind: 'array_lit'; elements: HIRExpr[]; span?: Span }
+  | { kind: 'struct_lit'; fields: { name: string; value: HIRExpr }[]; span?: Span }
+  // MC-specific literals
+  | { kind: 'rel_coord'; value: string; span?: Span }
+  | { kind: 'local_coord'; value: string; span?: Span }
+  | { kind: 'mc_name'; value: string; span?: Span }
+  | { kind: 'blockpos'; x: CoordComponent; y: CoordComponent; z: CoordComponent; span?: Span }
+  | { kind: 'selector'; raw: string; isSingle: boolean; sel: EntitySelector; span?: Span }
+  // String interpolation
+  | { kind: 'str_interp'; parts: Array<string | HIRExpr>; span?: Span }
+  | { kind: 'f_string'; parts: FStringPart[]; span?: Span }
+  // Identifiers
+  | { kind: 'ident'; name: string; span?: Span }
+  // Operators — && and || preserved (control-flow lowering happens in MIR)
+  | { kind: 'binary'; op: BinOp | CmpOp | '&&' | '||'; left: HIRExpr; right: HIRExpr; span?: Span }
+  | { kind: 'unary'; op: '!' | '-'; operand: HIRExpr; span?: Span }
+  | { kind: 'is_check'; expr: HIRExpr; entityType: EntityTypeName; span?: Span }
+  // Assignment — only plain '=' (compound ops desugared)
+  | { kind: 'assign'; target: string; value: HIRExpr; span?: Span }
+  | { kind: 'member_assign'; obj: HIRExpr; field: string; value: HIRExpr; span?: Span }
+  // Access
+  | { kind: 'member'; obj: HIRExpr; field: string; span?: Span }
+  | { kind: 'index'; obj: HIRExpr; index: HIRExpr; span?: Span }
+  // Calls
+  | { kind: 'call'; fn: string; args: HIRExpr[]; typeArgs?: TypeNode[]; span?: Span }
+  | { kind: 'invoke'; callee: HIRExpr; args: HIRExpr[]; span?: Span }
+  | { kind: 'static_call'; type: string; method: string; args: HIRExpr[]; span?: Span }
+  // Enum variant path
+  | { kind: 'path_expr'; enumName: string; variant: string; span?: Span }
+  // Lambda
+  | { kind: 'lambda'; params: LambdaParam[]; returnType?: TypeNode; body: HIRExpr | HIRBlock; span?: Span }
+  // Tuple literal
+  | { kind: 'tuple_lit'; elements: HIRExpr[]; span?: Span }
+  // Option literals
+  | { kind: 'some_lit'; value: HIRExpr; span?: Span }
+  | { kind: 'none_lit'; span?: Span }
+
+// ---------------------------------------------------------------------------
+// Execute Subcommands (unified — absorbs as_block, at_block, as_at)
+// ---------------------------------------------------------------------------
+
+export type HIRExecuteSubcommand =
+  // Context modifiers
+  | { kind: 'as'; selector: EntitySelector }
+  | { kind: 'at'; selector: EntitySelector }
+  | { kind: 'positioned'; x: string; y: string; z: string }
+  | { kind: 'positioned_as'; selector: EntitySelector }
+  | { kind: 'rotated'; yaw: string; pitch: string }
+  | { kind: 'rotated_as'; selector: EntitySelector }
+  | { kind: 'facing'; x: string; y: string; z: string }
+  | { kind: 'facing_entity'; selector: EntitySelector; anchor: 'eyes' | 'feet' }
+  | { kind: 'anchored'; anchor: 'eyes' | 'feet' }
+  | { kind: 'align'; axes: string }
+  | { kind: 'in'; dimension: string }
+  | { kind: 'on'; relation: string }
+  | { kind: 'summon'; entity: string }
+  // Conditions
+  | { kind: 'if_entity'; selector?: EntitySelector; varName?: string; filters?: SelectorFilter }
+  | { kind: 'unless_entity'; selector?: EntitySelector; varName?: string; filters?: SelectorFilter }
+  | { kind: 'if_block'; pos: [string, string, string]; block: string }
+  | { kind: 'unless_block'; pos: [string, string, string]; block: string }
+  | { kind: 'if_score'; target: string; targetObj: string; op: string; source: string; sourceObj: string }
+  | { kind: 'unless_score'; target: string; targetObj: string; op: string; source: string; sourceObj: string }
+  | { kind: 'if_score_range'; target: string; targetObj: string; range: string }
+  | { kind: 'unless_score_range'; target: string; targetObj: string; range: string }
+  // Store
+  | { kind: 'store_result'; target: string; targetObj: string }
+  | { kind: 'store_success'; target: string; targetObj: string }
+
+// ---------------------------------------------------------------------------
+// HIR Statements
+// ---------------------------------------------------------------------------
+
+export type HIRStmt =
+  | { kind: 'let'; name: string; type?: TypeNode; init: HIRExpr; span?: Span }
+  | { kind: 'let_destruct'; names: string[]; type?: TypeNode; init: HIRExpr; span?: Span }
+  | { kind: 'expr'; expr: HIRExpr; span?: Span }
+  | { kind: 'return'; value?: HIRExpr; span?: Span }
+  | { kind: 'break'; span?: Span }
+  | { kind: 'continue'; span?: Span }
+  | { kind: 'if'; cond: HIRExpr; then: HIRBlock; else_?: HIRBlock; span?: Span }
+  | { kind: 'while'; cond: HIRExpr; body: HIRBlock; step?: HIRBlock; span?: Span }
+  // foreach preserved (entity iteration is MC-specific, not just sugar)
+  | { kind: 'foreach'; binding: string; iterable: HIRExpr; body: HIRBlock; executeContext?: string; span?: Span }
+  // match preserved (not trivially desugarable)
+  | { kind: 'match'; expr: HIRExpr; arms: { pattern: HIRExpr | null; body: HIRBlock }[]; span?: Span }
+  // Unified execute block (absorbs as_block, at_block, as_at, execute)
+  | { kind: 'execute'; subcommands: HIRExecuteSubcommand[]; body: HIRBlock; span?: Span }
+  | { kind: 'raw'; cmd: string; span?: Span }
+  | { kind: 'if_let_some'; binding: string; init: HIRExpr; then: HIRBlock; else_?: HIRBlock; span?: Span }
+
+export type HIRBlock = HIRStmt[]
+
+// ---------------------------------------------------------------------------
+// HIR Function & Module
+// ---------------------------------------------------------------------------
+
+export interface HIRParam {
+  name: string
+  type: TypeNode
+  default?: HIRExpr
+}
+
+export interface HIRFunction {
+  name: string
+  /** Generic type parameter names, e.g. ['T'] for fn foo<T>(...) */
+  typeParams?: string[]
+  params: HIRParam[]
+  returnType: TypeNode
+  decorators: Decorator[]
+  body: HIRBlock
+  isLibraryFn?: boolean
+  isExported?: boolean
+  span?: Span
+}
+
+export interface HIRStructField {
+  name: string
+  type: TypeNode
+}
+
+export interface HIRStruct {
+  name: string
+  fields: HIRStructField[]
+  span?: Span
+}
+
+export interface HIRImplBlock {
+  typeName: string
+  methods: HIRFunction[]
+  span?: Span
+}
+
+export interface HIREnumVariant {
+  name: string
+  value?: number
+}
+
+export interface HIREnum {
+  name: string
+  variants: HIREnumVariant[]
+  span?: Span
+}
+
+export interface HIRConst {
+  name: string
+  type: TypeNode
+  value: HIRExpr
+  span?: Span
+}
+
+export interface HIRGlobal {
+  name: string
+  type: TypeNode
+  init: HIRExpr
+  mutable: boolean
+  span?: Span
+}
+
+export interface HIRModule {
+  namespace: string
+  globals: HIRGlobal[]
+  functions: HIRFunction[]
+  structs: HIRStruct[]
+  implBlocks: HIRImplBlock[]
+  enums: HIREnum[]
+  consts: HIRConst[]
+  isLibrary?: boolean
+}