mt-lang 0.3.28 → 0.3.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20058db447f681f83bcc651d9a9772e79b23bd9f1677e5c33d2053bab536a14f
-  data.tar.gz: 204af7f1018ce7637690eddc2bc9a7f297fc1f10e59c1a573491bd3b7c0b0d1c
+  metadata.gz: d6d13cde9fca875b324ff3e0cb3b892c371e2445ac5e061d138bd0dc8b284b88
+  data.tar.gz: 2a91eedc02120e0d042bc6bafbfc783a4eefb5bbc44c34940e1ee9be6917405e
 SHA512:
-  metadata.gz: ec63256de42954560cedc8e5021370b8f45a64e083ebb839d3057d4ea93816a51d45f950283ece162152ad10be6f1bb6ec4aa54a6ad8ce7b2db107830dd1db6a
-  data.tar.gz: 616bc238b0ee79df60a7a09fc62b895b1ab7717a1116a6b96c50879549578ba0aab91fbb9a74e40aedfc559973c333a8bc2c2cc40d3d16b6913584a744230819
+  metadata.gz: 478dc59b852c703b5cf63ce3cd77a92d6de305424c96cfa7dbeda97ed1882f2d8c52f5770893dc99a3077cb1599cbf0602c6e54b773f219ce859b8b9275c7258
+  data.tar.gz: d221d15fe3c3192ee0b10b61101f5234e8b92830f878051c6e2641aca334b7d165c9668bf410a727b4964f02d45805322044470a9e406b971ab7508650d60a00

data/README.md

@@ -94,7 +94,7 @@ Supported literals:
 - floats: `3.14`, `1.2e-3`, `1.0f` (float suffix), `1.0d` (double suffix)
 - character: `'a'`, `'\n'`, `'\t'`, `'\\'`, `'\''`, `'\0'`, `'\x41'`. Type is `ubyte`. Escape sequences: `\n`, `\r`, `\t`, `\\`, `\'`, `\"`, `\0` (null byte), `\xNN` (hex byte).
 - booleans: `true`, `false`
-- string: `"hello"` -> `str`
+- string: `"hello"` -> `str`. The `+` operator concatenates `str` values: `"hello" + " " + "world"` produces `"hello world"`. For loops or repeated concatenation, prefer `string.String`.
 - cstring: `c"hello"` -> `cstr`
 - heredoc string: `<<-TAG ... TAG`
 - heredoc cstring: `c<<-TAG ... TAG`
@@ -106,7 +106,7 @@ Common punctuation and operators:
 - delimiters: `(` `)` `[` `]`
 - access and separators: `:` `,` `.`
 - type markers: `->` `?`
-- arithmetic: `+ - * / %`
+- arithmetic: `+ - * / %` (additionally, `+` on `str` concatenates)
 - bitwise: `~ & | ^ << >>`
 - comparison: `== != < <= > >=`
 - assignment: `= += -= *= /= %= &= |= ^= <<= >>=`
@@ -937,7 +937,7 @@ See module source for full method surface. Iterator forms:
 
 Text categories:
 
-- `str` -> string view
+- `str` -> string view. The `+` operator concatenates two `str` values, allocating a new heap-backed string. For loops or repeated concatenation, prefer `string.String` for amortized performance.
 - `cstr` -> C ABI string
 - `str_buffer[N]` -> fixed-capacity mutable UTF-8 text buffer
 

data/docs/index.html

@@ -961,7 +961,7 @@ let total = (
       <tr><td>Delimiters</td><td><code>( ) [ ]</code></td></tr>
       <tr><td>Separators / Access</td><td><code>: , .</code></td></tr>
       <tr><td>Type markers</td><td><code>-&gt;</code> <code>?</code></td></tr>
-      <tr><td>Arithmetic</td><td><code>+ - * / %</code></td></tr>
+      <tr><td>Arithmetic</td><td><code>+ - * / %</code> (the <code>+</code> operator on <code>str</code> concatenates, allocating a new heap-backed string)</td></tr>
       <tr><td>Bitwise</td><td><code>~ &amp; | ^ &lt;&lt; &gt;&gt;</code></td></tr>
       <tr><td>Comparison</td><td><code>== != &lt; &lt;= &gt; &gt;=</code></td></tr>
       <tr><td>Assignment</td><td><code>= += -= *= /= %= &amp;= |= ^= &lt;&lt;= &gt;&gt;=</code></td></tr>
@@ -1243,7 +1243,7 @@ let d: dyn[Drawable] = adapt[Drawable](ref_of(entity))</code></pre>
       <tr><td><code>ptr_int</code> <code>ptr_uint</code></td><td>Pointer-sized integers</td></tr>
       <tr><td><code>float</code> <code>double</code></td><td>Floating-point</td></tr>
       <tr><td><code>void</code></td><td>No value</td></tr>
-      <tr><td><code>str</code></td><td>UTF-8 string view (borrowed)</td></tr>
+      <tr><td><code>str</code></td><td>UTF-8 string view (borrowed). The <code>+</code> operator concatenates two <code>str</code> values, allocating a new heap-backed string.</td></tr>
       <tr><td><code>cstr</code></td><td>NUL-terminated C string</td></tr>
       <tr><td><code>vec2</code> <code>vec3</code> <code>vec4</code></td><td>Float vectors with <code>.x .y .z .w</code></td></tr>
       <tr><td><code>ivec2</code> <code>ivec3</code> <code>ivec4</code></td><td>Integer vectors</td></tr>

data/docs/language-design.md

@@ -38,7 +38,7 @@ If code allocates, takes an address, dereferences a raw pointer, performs an FFI
 
 FFI visibility belongs at the declaration site. Raw `external` files expose exact ABI types. Imported foreign declarations may project those raw types into ordinary Milk Tea types, but the projection rule, temporary-storage rule, and ownership rule must be declared there instead of repeated at every call site.
 
-The same rule applies to text construction. Plain string literals and format string literals are borrowed `str` values. Any surface that builds owned text must say so explicitly, for example `std.fmt.format(f"...")` when ownership must escape.
+The same rule applies to text construction. Plain string literals and format string literals are borrowed `str` values. The `+` operator on `str` allocates a new heap-backed `str` — the one everyday convenience that does allocate. For loops or amortized building, `string.String` and `str_buffer[N]` remain the explicit surfaces with visible cost. Any other surface that builds owned text must say so explicitly, for example `std.fmt.format(f"...")` when ownership must escape.
 
 ### 2. C is the ABI ground truth
 
@@ -755,7 +755,7 @@ Explicit specialization arguments may be type references like `bytes_for[int](4)
 
 Built-in operators should match familiar C behavior where possible:
 
-- arithmetic: `+ - * / %`
+- arithmetic: `+ - * / %` (the `+` operator on `str` concatenates, allocating a new heap-backed string)
 - comparison: `== != < <= > >=`
 - boolean: `and or not`
 - bitwise: `& | ^ ~ << >>`

data/docs/language-manual.md

@@ -124,7 +124,7 @@ Supported literals:
 - integer: `42`, `0xff`, `0b1010`, with `_` separators. Integer type suffixes: `42u` (`uint`), `0xFFub` (`ubyte`), `100z` (`ptr_uint`), `7i` (`int`), `-1l` (`long`), etc.
 - float: `3.14`, `1.2e-3`, `1.1920929E-7`, `1.0f` (float suffix), `1.0d` (double suffix)
 - character: `'a'`, `'\n'`, `'\t'`, `'\\'`, `'\''`, `'\0'`, `'\x41'`. Type is `ubyte`. Escape sequences: `\n`, `\r`, `\t`, `\\`, `\'`, `\"`, `\0` (null), `\xNN` (hex byte).
-- string: `"hello"` (`str`). Supported string escapes are `\n`, `\r`, `\t`, `\0` (null), `\"`, `\'`, and `\\`; any other `\x` sequence is taken literally. Hex byte escapes (`\xNN`) are character-literal only, not string-literal.
+- string: `"hello"` (`str`). Supported string escapes are `\n`, `\r`, `\t`, `\0` (null), `\"`, `\'`, and `\\`; any other `\x` sequence is taken literally. Hex byte escapes (`\xNN`) are character-literal only, not string-literal. The `+` operator concatenates `str` values: `"hello" + " " + "world"` produces `"hello world"`. Each `+` allocates a new heap-backed `str`; for loops or repeated concatenation, prefer `string.String` for amortized performance.
 - cstring: `c"hello"` (`cstr`)
 - heredoc string: `<<-TAG ... TAG` (`str`)
 - heredoc cstring: `c<<-TAG ... TAG` (`cstr`)
@@ -1015,7 +1015,7 @@ Rules:
 8. `==`, `!=`
 9. `<`, `<=`, `>`, `>=`
 10. `<<`, `>>`
-11. `+`, `-`
+11. `+`, `-` (additionally, `+` on `str` concatenates; each `+` allocates a new heap-backed `str`)
 12. `*`, `/`, `%`
 
 ### 5.4 Assignment operators

data/lib/milk_tea/base.rb

@@ -3,7 +3,7 @@
 require "pathname"
 
 module MilkTea
-  VERSION = "0.3.28"
+  VERSION = "0.3.30"
 
   def self.root
     @root ||= Pathname.new(File.expand_path("../..", __dir__))

data/lib/milk_tea/core/c_backend/feature_detection.rb

@@ -289,6 +289,14 @@ module MilkTea
         emitted_functions.any? { |function| function_uses_str_equality?(function) }
       end
 
+      def uses_str_concat_helper?
+        return @uses_str_concat if defined?(@uses_str_concat)
+
+        @uses_str_concat = emitted_functions.any? do |function|
+          function_uses_named_call?(function, %w[mt_str_concat])
+        end
+      end
+
       def uses_variant_equality_helper?
         emitted_functions.any? { |function| function_uses_variant_equality?(function) }
       end

data/lib/milk_tea/core/c_backend/runtime_helpers.rb

@@ -42,6 +42,27 @@ module MilkTea
         ]
       end
 
+      def emit_str_concat_helper
+        [
+          "#define MT_STR_CONCAT_BUF_SIZE 65536",
+          "",
+          "static _Thread_local char mt_str_concat_buf[MT_STR_CONCAT_BUF_SIZE];",
+          "static _Thread_local uintptr_t mt_str_concat_offset = 0;",
+          "",
+          "static mt_str mt_str_concat(mt_str a, mt_str b) {",
+          "#{INDENT}uintptr_t total = a.len + b.len;",
+          "#{INDENT}if (mt_str_concat_offset + total > MT_STR_CONCAT_BUF_SIZE) {",
+          "#{INDENT * 2}mt_str_concat_offset = 0;",
+          "#{INDENT}}",
+          "#{INDENT}char* buf = mt_str_concat_buf + mt_str_concat_offset;",
+          "#{INDENT}if (a.len > 0) memcpy(buf, a.data, a.len);",
+          "#{INDENT}if (b.len > 0) memcpy(buf + a.len, b.data, b.len);",
+          "#{INDENT}mt_str_concat_offset += total;",
+          "#{INDENT}return (mt_str){ .data = buf, .len = total };",
+          "}",
+        ]
+      end
+
       def emit_variant_equality_helpers
         emitted_aggregate_variants.flat_map { |variant_decl| emit_variant_equality_helper(variant_decl) }
       end

data/lib/milk_tea/core/c_backend.rb

@@ -146,6 +146,10 @@ module MilkTea
         lines.concat(emit_str_equality_helper)
         lines << ""
       end
+      if uses_str_concat_helper?
+        lines.concat(emit_str_concat_helper)
+        lines << ""
+      end
       if uses_str_buffer_helpers?
         lines.concat(emit_utf8_validation_helpers)
         lines << ""

data/lib/milk_tea/core/lowering/expressions.rb

@@ -1387,6 +1387,10 @@ module MilkTea
           left = cast_expression(left, operand_type) if operand_type
           right = cast_expression(right, operand_type) if operand_type
 
+          if expression.operator == "+" && left_type == @ctx.types.fetch("str") && right_type == @ctx.types.fetch("str")
+            return IR::Call.new(callee: "mt_str_concat", arguments: [left, right], type:)
+          end
+
           expanded = lower_vector_binary_operation(expression.operator, left, left_type, right, right_type, type)
           return expanded if expanded
 

data/lib/milk_tea/core/semantic_analyzer/expressions.rb

@@ -612,8 +612,8 @@ module MilkTea
 
           left_type
         when "+", "-", "*", "/"
-          if expression.operator == "+" && (string_like_type?(left_type) || string_like_type?(right_type))
-            raise_sema_error("operator + does not support str/cstr concatenation; use continued string literals for static text or string.String/str_buffer for dynamic text")
+          if expression.operator == "+" && left_type == @ctx.types.fetch("str") && right_type == @ctx.types.fetch("str")
+            return left_type
           end
 
           pointer_result = pointer_arithmetic_result(expression.operator, left_type, right_type)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mt-lang
 version: !ruby/object:Gem::Version
-  version: 0.3.28
+  version: 0.3.30
 platform: ruby
 authors:
 - Long (Teefan) Tran
@@ -149,7 +149,6 @@ files:
 - docs/index.html
 - docs/language-design.md
 - docs/language-manual.md
-- docs/self-hosted-compiler-plan.md
 - lib/milk_tea.rb
 - lib/milk_tea/base.rb
 - lib/milk_tea/bindings.rb
@@ -625,7 +624,7 @@ metadata:
   homepage_uri: https://teefan.github.io/mt-lang/
   source_code_uri: https://github.com/teefan/mt-lang
 post_install_message: |
-  Milk Tea 0.3.28 installed!
+  Milk Tea 0.3.30 installed!
 
   System requirements:
     - A C compiler (gcc or clang) must be available on PATH

data/docs/self-hosted-compiler-plan.md

@@ -1,737 +0,0 @@
-# Self-Hosted Milk Tea Compiler — Architecture Plan
-
-## `projects/mtc`
-
-This document describes the architecture and implementation plan for a self-hosted
-Milk Tea compiler, written in Milk Tea, that compiles Milk Tea source to C.
-
----
-
-## 0. Core Design Principles
-
-Three principles separate a modern self-hosted compiler from the Ruby prototype:
-
-1. **IR-stage separation**. The Ruby compiler's `Lowering` does too much in one pass — CPS
-   transform, monomorphization, desugaring, and C-biased lowering are all intertwined.
-   `mtc` uses two distinct IRs between the surface AST and the C backend: **HIR** (typed,
-   monomorphized, name-resolved) and **LIR** (flat, C-shaped). Generics are
-   monomorphized during the AST → HIR transition rather than deferred to lowering.
-
-2. **Modular passes**. Each pass is a standalone module with a single `run(ctx) ->
-   Result[ctx, Error]` signature. Passes compose via a pipeline struct. No global
-   mutable state.
-
-3. **Diagnostics-first**. Every pass accumulates `Diagnostic` values into a shared
-   `DiagnosticEngine`. Errors never abort the pipeline; they are collected, sorted by
-   location, and emitted as a batch.
-
----
-
-## 1. Project Layout
-
-```
-projects/mtc/
-├── package.toml                    # kind=application, source_root=src
-├── src/
-│   ├── main.mt                     # Entry: parse CLI, dispatch compile/run/check/test
-│   ├── mtc/
-│   │   ├── diagnostics.mt          # Diagnostic, DiagnosticKind, DiagnosticEngine, SourceSpan
-│   │   ├── token.mt                # TokenKind enum, Token struct
-│   │   ├── lexer/
-│   │   │   ├── lexer.mt            # Lexer.lex(source, path) -> Result[Vec[Token], Error]
-│   │   │   ├── trivia.mt           # Whitespace/comment handling (CST reconstruction)
-│   │   │   └── char_tables.mt      # Static lookup tables (is_alpha, is_digit, etc.)
-│   │   ├── parser/
-│   │   │   ├── parser.mt           # Recursive-descent parser entry
-│   │   │   ├── expressions.mt      # Pratt parser for operator expressions
-│   │   │   ├── declarations.mt     # Top-level declarations
-│   │   │   ├── statements.mt       # Statement parsing (if, for, match, while, etc.)
-│   │   │   └── recovery.mt         # Error recovery synchronizer sets
-│   │   ├── ast.mt                  # AST node definitions and arena
-│   │   ├── hir.mt                  # HIR types (typed, monomorphized, name-resolved)
-│   │   ├── lir.mt                  # LIR types (flat, C-shaped)
-│   │   ├── symbol_table.mt         # Scoped symbol table (stacked maps)
-│   │   ├── type_system/
-│   │   │   ├── types.mt            # Type variant and registry
-│   │   │   └── layout.mt           # size_of / align_of / offset_of (const functions)
-│   │   ├── semantic/
-│   │   │   ├── checker.mt          # Phase: AST → HIR (name resolution, type checking)
-│   │   │   ├── infer.mt            # Bidirectional type inference
-│   │   │   ├── conform.mt          # Interface conformance checking
-│   │   │   ├── monomorphize.mt     # Generic instantiation (HIR construction time)
-│   │   │   └── const_eval.mt       # Compile-time expression evaluator
-│   │   ├── lowering/
-│   │   │   ├── lower.mt            # Phase: HIR → LIR (desugaring, flattening)
-│   │   │   ├── desugar.mt          # async→CPS, for→while, match→switch, ?→if-return
-│   │   │   └── cps.mt              # Continuation-passing-style transform for async
-│   │   ├── module_loader.mt        # Load and resolve transitive imports
-│   │   ├── module_path_resolver.mt # Resolve import paths to filesystem paths
-│   │   ├── module_binder.mt        # Public/private visibility split per module
-│   │   ├── backend/
-│   │   │   ├── c_backend.mt        # Phase: LIR → C source text
-│   │   │   ├── llvm.mt             # Future: LIR → LLVM IR (via external function bindings)
-│   │   │   └── runtime.mt          # C runtime helper emission (fatal, format, refcount, etc.)
-│   │   └── pipeline.mt             # CompilerPipeline orchestrator struct
-│   └── tests/                      # In-language tests using @[test] and std.testing
-│       ├── lexer_test.mt
-│       ├── parser_test.mt
-│       ├── semantic_test.mt
-│       ├── type_test.mt
-│       └── roundtrip_test.mt
-└── tests/                          # Canary .mt programs as test corpus (run via mtc test)
-    ├── lex/
-    ├── parse/
-    ├── type/
-    ├── lower/
-    └── roundtrip/                  # Self-compilation verification
-```
-
-Note: LSP support (`lsp/server.mt`, `hover.mt`, `completion.mt`, `goto_def.mt`) is
-deferred to v2. The v1 compiler is CLI-only. The `DiagnosticEngine` is designed to
-accommodate LSP consumers in the future via byte-offset source spans.
-
----
-
-## 2. Pipeline Architecture
-
-```
-┌─────────┐    ┌─────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐
-│  Source │───▶│  Lexer  │───▶│  Parser   │───▶│ Semantic │───▶│ Lowerer │
-│   Text  │    │         │    │           │    │ (AST→HIR)│    │(HIR→LIR)│
-└─────────┘    └─────────┘    └───────────┘    └──────────┘    └─────────┘
-                   │               │               │                │
-                   ▼               ▼               ▼                ▼
-              ┌─────────────────────────────────────────────────────────┐
-              │                     DiagnosticEngine                    │
-              └─────────────────────────────────────────────────────────┘
-                                                                     │
-                                                                     ▼
-                                                              ┌──────────┐
-                                                              │ CBackend │──▶ C source
-                                                              └──────────┘
-```
-
-`CompilerPipeline` is the orchestrator:
-
-```mt
-struct CompilerPipeline:
-    options: CompileOptions
-    diagnostics: DiagnosticEngine
-
-    function run(source: str, path: str) -> Result[vec.Vec[ubyte], Diagnostic]:
-        let tokens = this.lex(source, path)?
-        let ast = this.parse(tokens, path)?
-        let hir = this.semantic(ast, path)?
-        let lir = this.lower(hir)?
-        return this.backend(lir)?
-```
-
-Each pass returns `Result[Output, Diagnostic]`. Critical errors short-circuit via `?`.
-Non-critical diagnostics accumulate in the engine for batch emission.
-
----
-
-## 3. Memory Model: Arena + Handle Pattern
-
-Milk Tea prohibits storing `ref[T]` inside generic containers such as `Vec`.
-Tree-shaped data (AST, HIR, LIR) must therefore avoid `Vec[ref[Expr]]` and similar
-patterns. The standard solution, used by industrial compilers including `rustc`, is
-arena-allocated value storage with opaque index handles.
-
-### The pattern
-
-Every IR node type has a corresponding `Id` — a plain `ptr_uint` index into a
-`Vec[Node]` owned by an arena struct:
-
-```mt
-type ExprId = ptr_uint
-type StmtId = ptr_uint
-type DeclId = ptr_uint
-type TypeId = ptr_uint
-
-struct AstArena:
-    exprs: Vec[Expr]
-    stmts: Vec[Stmt]
-    decls: Vec[Decl]
-
-    editable function alloc_expr(node: Expr) -> ExprId:
-        let index: ptr_uint = this.exprs.len()
-        this.exprs.push(node)
-        return index
-
-    editable function alloc_stmt(node: Stmt) -> StmtId:
-        let index: ptr_uint = this.stmts.len()
-        this.stmts.push(node)
-        return index
-
-    editable function alloc_decl(node: Decl) -> DeclId:
-        let index: ptr_uint = this.decls.len()
-        this.decls.push(node)
-        return index
-```
-
-All child references in AST/HIR/LIR nodes use `Id` types, never `ref[T]`. Ids are
-plain integers — legal in any container, trivially copyable, and zero-cost to
-resolve through the arena. Bulk deallocation happens when the arena itself is released.
-
-The same pattern applies to the type system: types live in a `TypeRegistry` arena
-and are referenced by `TypeId`:
-
-```mt
-struct TypeRegistry:
-    types: Vec[Type]
-
-    edible function intern(typ: Type) -> TypeId:
-        let index: ptr_uint = this.types.len()
-        this.types.push(typ)
-        return index
-
-    function resolve(id: TypeId) -> ptr[Type]?
-```
-```
-
-### Why not `own[T]` or `ref[T]`
-
-`ref[T]` is rejected in every relevant tree-storage position:
-
-- `Vec[ref[T]]` — rejected at compile time: *"ref types cannot be nested inside Vec"*
-- `ref[T]` as a variant arm payload field — rejected: *"cannot store ref types; declare
-  a lifetime on the struct"*
-- `ref[T]` in a struct field auto-generates an implicit lifetime, making the struct
-  non-owning and rejected from `Vec`, returns, and module storage
-
-`own[T]` (owning heap pointers) is storable in containers and variant fields, but
-using it for every tree child produces millions of separate heap allocations for a
-50K-LOC compiler. The arena pattern stores all nodes contiguously in a single
-allocation per IR stage, yielding far better cache locality and eliminating per-node
-allocation overhead.
-
-### Arena implementation
-
-The arena pattern above is built on plain `Vec` storage: each arena field (`exprs`,
-`stmts`, `decls`) is a `Vec[Node]`, and `alloc_*` methods simply push the node and
-return `this.vec.len()` as the index. No unsafe code, no pointer arithmetic — just
-contiguous expandable storage with O(1) append and O(1) index resolution via `Vec.get`.
-For release, the arena's `release()` iterates and calls `release()` on each contained
-`Vec` and `Map`, then bulk-deallocates.
-
-For lower-level bump-pointer allocation (e.g., in the C backend's output buffer),
-`std.mem.arena` is available but not needed for IR tree storage.
-
----
-
-## 4. Key Data Structures
-
-*Import preamble: `Vec`, `Map`, `Set` are not prelude types (only `Option` and `Result`
-are). Real source files use `import std.vec as vec`, `import std.map as m`, etc.
-and reference them as `vec.Vec[T]`, `m.Map[K,V]`. Code examples below use bare
-`Vec[T]`, `Map[K,V]` for readability.*
-
-### AST Nodes (the surface tree)
-
-```mt
-variant Expr:
-    literal(value: Literal)
-    identifier(name: str)
-    binary(left: ExprId, op: BinOp, right: ExprId)
-    unary(op: UnaryOp, operand: ExprId)
-    call(callee: ExprId, args: Vec[ExprId])
-    member(obj: ExprId, field: str)
-    index(obj: ExprId, idx: ExprId)
-    if_expr(cond: ExprId, then_branch: ExprId, else_branch: Option[ExprId])
-    match_expr(scrutinee: ExprId, arms: Vec[MatchArm])
-    proc_expr(params: Vec[Param], body: StmtId)
-    tuple_expr(elements: Vec[ExprId])
-
-variant Stmt:
-    expr(expr: ExprId)
-    let_decl(name: str, typ: Option[TypeId], init: Option[ExprId], guard: Option[Guard])
-    assign(target: ExprId, op: AssignOp, value: ExprId)
-    if_stmt(cond: ExprId, then_block: Vec[StmtId], else_ifs: Vec[ElseIf],
-            else_block: Option[Vec[StmtId]])
-    while_stmt(cond: ExprId, body: Vec[StmtId])
-    for_stmt(bindings: Vec[ForBinding], iterable: ExprId, body: Vec[StmtId])
-    match_stmt(scrutinee: ExprId, arms: Vec[MatchArm])
-    return_stmt(value: Option[ExprId])
-    defer_stmt(body: Vec[StmtId])
-
-variant Decl:
-    function_def(name: str, params: Vec[Param], return_type: Option[TypeId],
-                 body: Option[Vec[StmtId]], visibility: Visibility, is_async: bool)
-    struct_def(name: str, fields: Vec[Field], type_params: Vec[TypeParam],
-               implements: Vec[QualName], visibility: Visibility)
-    variant_def(name: str, arms: Vec[VariantArm], type_params: Vec[TypeParam],
-                visibility: Visibility)
-    const_decl(name: str, typ: TypeId, init: ExprId, visibility: Visibility)
-    import_decl(module_path: Vec[str], alias: Option[str])
-```
-
-Note: variant arm fields of types like `Vec[ExprId]`, `Option[ExprId]`, and direct
-`ExprId` values are all storable because `ExprId = ptr_uint` is a plain integer.
-
-### HIR (typed, monomorphized, name-resolved)
-
-HIR is the typed intermediate representation. Generic types are fully monomorphized,
-names are resolved to bindings, and types are attached to every expression node.
-
-```mt
-struct HirProgram:
-    modules: Vec[HirModule]
-
-struct HirModule:
-    name: str
-    path: str
-    declarations: Vec[HirDecl]
-    type_registry: TypeRegistry
-    symbol_table: SymbolTable
-
-variant HirExpr:
-    literal(value: Literal, typ: TypeId)
-    var_ref(binding: BindingId, typ: TypeId)
-    call(callee: HirCallable, args: Vec[HirExprId], typ: TypeId)
-    member(obj: HirExprId, field: str, typ: TypeId)
-    intrinsic(kind: IntrinsicKind, args: Vec[HirExprId], typ: TypeId)
-
-type HirExprId = ptr_uint
-```
-
-### LIR (flat, C-shaped)
-
-LIR matches the Ruby compiler's `IR::Program` in spirit — flat statement lists, no
-type parameters, C-compatible expression forms:
-
-```mt
-struct LirProgram:
-    modules: Vec[LirModule]
-
-struct LirFunction:
-    name: str
-    linkage_name: str
-    params: Vec[LirParam]
-    return_type: TypeId
-    body: Vec[LirStmt]
-    locals: Vec[LirLocal]
-
-variant LirExpr:
-    name(id: LocalId)
-    integer(value: int, width: IntWidth)
-    call(target: str, args: Vec[LirExpr])
-    member(obj: LirExpr, field: str)
-    binop(left: LirExpr, op: BinOp, right: LirExpr)
-    address_of(expr: LirExpr)
-    load(expr: LirExpr)
-```
-
----
-
-## 5. Type System Design
-
-The type representation is the compiler's internal model — distinct from the language's
-user-facing types:
-
-```mt
-# (All arm names use _type suffix uniformly.  Of the 24 reserved primitive type
-#  names, only 6 appear here — bool/int/uint/float/char/void — and they require
-#  the suffix.  Every other name works bare, but we suffix all for consistency.)
-
-variant Type:
-    # Primitives
-    bool_type
-    int_type(width: IntWidth)
-    uint_type(width: UintWidth)
-    float_type(width: FloatWidth)
-    char_type
-    void_type
-
-    # Constructors
-    ptr_type(inner: TypeId)
-    const_ptr_type(inner: TypeId)
-    own_type(inner: TypeId)
-    ref_type(inner: TypeId)
-    span_type(inner: TypeId)
-    array_type(inner: TypeId, len: ptr_uint)
-    tuple_type(elements: Vec[TypeId])
-    func_type(params: Vec[TypeId], ret: TypeId)
-    proc_type(params: Vec[TypeId], ret: TypeId)
-
-    # User-defined
-    struct_type(name: QualName, args: Vec[TypeId])
-    variant_type(name: QualName, args: Vec[TypeId])
-    enum_type(name: QualName)
-    dyn_type(interface: QualName, args: Vec[TypeId])
-
-    # Special
-    type_var_type(index: int)   # For generic resolution (replaced during monomorphization)
-    error_type                  # Sentinel for recovery
-```
-
-Types live in the `TypeRegistry` arena and are referenced by `TypeId` everywhere.
-The `type_var` variant represents unresolved generic type parameters during inference;
-it is never present in HIR or LIR — monomorphization replaces every `type_var` with a
-concrete type.
-
----
-
-## 6. Symbol Table
-
-Stacked scopes with a pre-populated global scope for builtins:
-
-```mt
-struct SymbolTable:
-    scopes: Vec[Scope]
-
-# Each scope is anonymous. Resolution walks the Vec from the innermost scope
-# outward (the index position encodes nesting depth). No parent pointer needed.
-struct Scope:
-    types: Map[str, TypeBinding]
-    values: Map[str, ValueBinding]
-    functions: Map[str, FuncBinding]
-
-struct TypeBinding:
-    kind: TypeBindingKind
-    type_id: TypeId        # Index into TypeRegistry
-    visibility: Visibility
-    definition_span: SourceSpan
-
-struct ValueBinding:
-    type_id: TypeId        # Index into TypeRegistry
-    kind: ValueKind
-    is_mutable: bool
-    definition_span: SourceSpan
-```
-
-Module-level scope construction follows this order (same as the Ruby checker's phase
-pipeline):
-
-1. Install builtin types (bool, int, str, etc.)
-2. Install imports (populate from imported module bindings)
-3. Declare named types (register struct/variant/enum names — enables forward references)
-4. Resolve type aliases and aggregate fields
-5. Declare functions (register signatures — enables forward calls)
-6. Type-check function bodies
-
----
-
-## 7. Module Loading and Visibility
-
-The Ruby compiler's module infrastructure (`module_loader.rb`, `module_binder.rb`,
-`module_path_resolver.rb`, `module_roots.rb`) maps to three mtc modules:
-
-**`module_path_resolver.mt`** — Given `import std.hash`, resolves to the filesystem
-path `std/hash.mt`. Handles platform-specific variants (`name.linux.mt`),
-`package.source_root` resolution, and in-memory source overrides.
-
-**`module_loader.mt`** — Loads and analyzes a module and its transitive imports.
-Returns a `ModuleGraph` containing all parsed and analyzed modules. Handles circular
-imports via forward-declaration bindings, matching the Ruby compiler's two-pass
-strategy.
-
-**`module_binder.mt`** — Given a module's `SymbolTable` and `Visibility` annotations,
-produces a public-only view that downstream modules can import. Partitions types,
-values, functions, methods, and interface implementations into public/private sets.
-
----
-
-## 8. Milk Tea Feature Mapping
-
-| Milk Tea Feature | Compiler Use |
-|---|---|
-| **`variant`** | AST nodes, HIR nodes, LIR expressions, Type representation, DiagnosticKind |
-| **`enum`** | TokenKind, BinOp, UnaryOp, AssignOp, Visibility, PlatformTarget, IntWidth, FloatWidth |
-| **`flags`** | Token modifier flags (is_keyword, is_literal, is_assignment_start) |
-| **`struct`** | Arena, SymbolTable, Scope, Binding, SourceSpan, CompileOptions, Pipeline, Module |
-| **`Result[T, E]` + `?`** | Every pass return type; error propagation through the pipeline |
-| **`Option[T]`** | Optional AST children (else branch, initializer, type annotation, import alias) |
-| **`Vec[T]`** | Token stream, AST child vectors, declaration lists, statement blocks, diagnostic list |
-| **`Map[K,V]`** | Symbol table scopes, type registry index, monomorphization cache, import table |
-| **`Set[T]`** | Used-name tracking, reachability analysis, live-variable sets |
-| **`interface` + `dyn[I]`** | Pass trait (`interface Pass: function run(ctx) -> Result[...]`), AST visitor dispatch |
-| **`const function`** | `size_of(T)`, `align_of(T)`, `offset_of(T, field)` — type layout at compile time |
-| **`when` / `inline if`** | Platform-conditional codegen (linux vs windows vs wasm target dispatch) |
-| **`inline for` + `fields_of`** | Reflective struct field iteration for comparison, hash, format code generation |
-| **`match`** | AST traversal, token dispatch in lexer, operator dispatch, pattern matching on IR nodes |
-| **`array[T,N]`** | Fixed-size lookup tables (operator precedence, keyword trie, char classification) |
-| **`span[T]`** | Zero-copy views over source text, token slices for diagnostics |
-| **`str` / `cstr`** | Source text, identifiers, file paths; C ABI strings for external function calls |
-| **`proc(...)`** | Per-pass callbacks (e.g., `ResolveIdentifier` in the const evaluator) |
-| **`fn(...)`** | Function pointers for static dispatch tables (no-capture callbacks, vtable entries) |
-| **`defer`** | Resource cleanup (file handles, arena deallocation, temp file removal) |
-| **`own[T]`** | Owning heap pointers for module-level data (file contents, cached artifacts) |
-| **`str_buffer[N]`** | C source assembly (building output line by line, no heap allocation per fragment) |
-| **`static_assert`** | Compile-time invariants (type sizes, alignment, field offsets, struct layout) |
-| **`@[test]` + `std.testing`** | Unit tests for lexer, parser, type checker, lowering passes |
-| **`emit`** | Compile-time helpers generated from `const function` (codegen support) |
-| **`SpatialGrid[T]`** | Future: incremental recompilation tracking (dirty region queries) |
-
-The following features are valid Milk Tea but are **not used in v1** of mtc — they
-target performance and parallelism, which are v2 concerns:
-
-| Deferred Feature | Future Use |
-|---|---|
-| **`parallel for`** | Type-checking independent functions concurrently (no data dependencies) |
-| **`parallel:`** | Concurrent lexing/parsing of independent imported modules |
-| **`async function` + `await`** | LSP request handling (non-blocking I/O), parallel compilation orchestration |
-| **`atomic[T]`** | Shared diagnostic counters across parallel passes |
-| **`SoA[T, N]`** | Hot-path data layouts (cache-friendly token streams in lexer) |
-| **`RingBuffer[T]`** | Work-stealing queues for parallel compilation |
-
----
-
-## 9. C Runtime Helpers
-
-The C backend must emit runtime support code that the generated C depends on. Rather
-than linking a pre-compiled library, the self-hosted compiler emits helpers inline
-into the generated C file (matching the Ruby compiler's approach):
-
-| Helper | Purpose |
-|---|---|
-| `mt_fatal(message, expr, file, line)` | Abort with formatted error (used by bounds checks, `unimplemented`, `fatal()`) |
-| `mt_format_*` (int, float, str, bool, hex, bin, oct) | Format primitives to `string.String` sinks (format string lowering) |
-| `mt_async_frame_*` | Task frame allocation and state management (async CPS lowering) |
-| `mt_proc_retain` / `mt_proc_release` | Ref-counted proc capture lifecycle |
-| `mt_event_*` | Fixed-capacity listener arrays, emit dispatch, subscription management |
-| `mt_loop_N` counters | Per-function loop guard injection (50M iteration cap, catches hangs) |
-
-The `backend/runtime.mt` module is a collection of `const` string literals — one
-per helper — selected for emission based on feature detection during the LIR walk.
-
----
-
-## 10. Testing Strategy
-
-Milk Tea has a built-in testing framework (`std.testing`, `@[test]` attribute, `mtc
-test` runner). The self-hosted compiler's test suite uses this framework:
-
-```mt
-import std.testing as t
-
-@[test]
-function test_lex_keywords() -> t.Check:
-    let result = Lexer.lex("function if else return", "test.mt")
-    let tokens = result?
-    t.expect_equal[ptr_uint](tokens.len(), 4)?
-    return t.ok()
-```
-
-Test categories:
-
-| Directory | Tests |
-|---|---|
-| `src/tests/lexer_test.mt` | Keyword recognition, char literals, string escapes, number formats, heredocs |
-| `src/tests/parser_test.mt` | AST structure verification for each declaration and statement form |
-| `src/tests/semantic_test.mt` | Type checking, name resolution, interface conformance, generic instantiation |
-| `src/tests/type_test.mt` | Type equality, subtype checks, layout computation, type registiry operations |
-| `src/tests/roundtrip_test.mt` | Compile .mt → C → compile C → run → assert exit code 0 |
-
-The `tests/` directory (at the project root, outside `src/`) holds canary `.mt`
-programs that exercise full language features. These are compiled by `mtc test` and
-their exit codes verified against expected values. They also serve as the corpus for
-self-compilation verification (Stage 5 bootstrap).
-
----
-
-## 11. Bootstrapping Strategy
-
-### Stage 1: Lex + Parse Only (Subset)
-
-Write a lexer and parser in Milk Tea that can parse Milk Tea source and produce an AST.
-Test by compiling with the Ruby `mtc` and running against the existing test corpus.
-No semantic analysis yet.
-
-- **Verification**: AST pretty-print round-trips on `examples/language_baseline.mt`
-- **Files**: `token.mt`, `lexer/*.mt`, `ast.mt`, `parser/*.mt`, `diagnostics.mt`
-
-### Stage 2: Semantic Analysis
-
-Add name resolution, type checking, and monomorphization. Generics are resolved to
-concrete instantiations during HIR construction. The output HIR need not lower to C
-yet, just pass checking.
-
-- **Verification**: All `examples/*.mt` files type-check without errors against `std/`
-- **Files**: `hir.mt`, `symbol_table.mt`, `type_system/*.mt`, `semantic/*.mt`,
-  `module_loader.mt`, `module_path_resolver.mt`, `module_binder.mt`
-
-### Stage 3: Lowering + C Backend
-
-Add desugaring, CPS transform, and C code emission including runtime helpers.
-
-- **Verification**: `examples/language_baseline.mt` produces a C file that compiles
-  with gcc/clang and produces identical runtime behavior to the Ruby `mtc` compiled
-  version
-- **Files**: `lir.mt`, `lowering/*.mt`, `backend/c_backend.mt`, `backend/runtime.mt`
-
-### Stage 4: Full Language
-
-Implement every remaining feature (async CPS, `parallel for`, events, `emit`, `dyn[T]`,
-struct patterns, format strings, etc.) until `mtc` passes the full test corpus. This is
-the long tail — roughly 70% of the effort targets the last 30% of features.
-
-- **Verification**: All `examples/*.mt` and `std/` modules compile and run correctly
-- **Files**: `lowering/cps.mt`, `lowering/desugar.mt` (full)
-
-### Stage 5: Self-Compile
-
-At this point, `mtc` compiled by the Ruby `mtc` can compile `mtc`'s own source:
-
-```sh
-# First bootstrap: Ruby mtc compiles mtc
-ruby-mtc build projects/mtc  →  ./build/mtc
-
-# Second bootstrap: mtc compiles itself
-./build/mtc build projects/mtc  →  ./build/mtc2
-
-# Verify: the two binaries produce identical C for the full compiler
-diff <(./build/mtc compile projects/mtc --no-cache) \
-     <(./build/mtc2 compile projects/mtc --no-cache)
-```
-
-Once identical output is achieved, the Ruby compiler is retired from the mtc build
-chain. The self-hosted compiler can evolve independently.
-
-### Stage 6: Secondary Backend (Future)
-
-Once `mtc` is self-hosting, target a secondary backend — LLVM via the C API using
-`external function` bindings, or directly emit machine code. This unlocks native
-compilation speed, debug info (DWARF), and incremental compilation.
-
----
-
-## 12. Implementation Risks and Mitigations
-
-| Risk | Mitigation |
-|---|---|
-| **Bootstrapping gap**: Milk Tea lacks features that `mtc` needs | Use the Ruby `mtc` as a "supercompiler" — if `mtc` hits a compiler bug in the Ruby compiler during bootstrap, fix the Ruby compiler first. |
-| **Performance of self-compiled code**: The C backend generates naive C; self-compiled `mtc` may be 5-10x slower | Optimize the generated C in the C backend first (fewer temporaries, better loop structure). LLVM backend eliminates this entirely. |
-| **Parser complexity**: The Ruby parser is ~4200 lines of hand-written recursive descent | Start with a clean implementation targeting only the Milk Tea grammar subset needed for `mtc` itself. Avoid parsing external files initially. |
-| **Debugging the self-hosted compiler**: Debugging a compiler compiled by itself is a hall-of-mirrors | Embed verbose tracing behind a `--debug-passes` flag. Use `static_assert` liberally for internal invariants. |
-| **45K LOC of Ruby**: The Ruby compiler is large and deeply integrated | `mtc` is a clean-room rewrite. It does not need to match every feature from day one — only the subset needed to bootstrap itself. |
-| **Standard library dependency**: `mtc` will import `std.*` heavily | The Ruby `mtc` already compiles `std/`. This is the least risky dependency — treat it as a given and focus on the compiler logic. |
-| **Arena exhaustion**: Arena-backed `Vec`s can grow unboundedly during IR construction | Each IR stage gets a fresh arena per compilation unit. Large files may trigger `Vec` resizes but cannot silently corrupt — `Vec` handles its own growable storage. |
-
----
-
-## 13. First Files to Write (Ordered)
-
-1. **`src/mtc/diagnostics.mt`** — `Diagnostic`, `DiagnosticEngine`, `SourceSpan`. Every
-   other module depends on these types for error reporting.
-
-2. **`src/mtc/token.mt`** — `TokenKind` enum, `Token` struct. No dependencies.
-   Verifiable by printing a hardcoded token list.
-
-3. **`src/mtc/ast.mt`** — All AST variant and arena types. Depends on `token.mt` and
-   `diagnostics.mt`. Defines the data model for the entire compiler.
-
-4. **`src/mtc/lexer/lexer.mt`** + **`char_tables.mt`** — Lexer. Outputs `Vec[Token]`.
-   Verifiable by dumping tokens for any `.mt` file.
-
-5. **`src/mtc/parser/*.mt`** — Parser. Outputs `AstArena` (containing all AST nodes).
-   Verifiable by pretty-printing the AST.
-
-6. **`src/mtc/type_system/types.mt`** — `Type` variant and `TypeRegistry`.
-
-7. **`src/mtc/symbol_table.mt`** — `SymbolTable`, `Scope`, and binding structs.
-
-8. **`src/mtc/module_path_resolver.mt`** — Import path resolution.
-
-9. **`src/mtc/hir.mt`** — HIR type definitions.
-
-10. **`src/mtc/semantic/*.mt`** — Semantic checker (AST → HIR), including
-    `monomorphize.mt`.
-
-11. **`src/mtc/module_loader.mt`** + **`module_binder.mt`** — Module loading and
-    visibility.
-
-12. **`src/mtc/lir.mt`** — LIR type definitions.
-
-13. **`src/mtc/lowering/*.mt`** — Lowering passes (HIR → LIR).
-
-14. **`src/mtc/backend/c_backend.mt`** + **`runtime.mt`** — C code and runtime emission.
-
-15. **`src/main.mt`** + **`pipeline.mt`** — CLI entry point and pipeline orchestration.
-
-Each file is independently testable as soon as its upstream dependencies are complete.
-
----
-
-## 14. Key Architecture Decisions
-
-### Arena + Handle over `ref[T]` in containers
-
-Milk Tea's `ref[T]` restriction on containers forces the arena pattern. This is not a
-workaround — it is the correct design. Arena-allocated AST/HIR nodes with index handles
-yield better cache locality than pointer-chasing graphs, enable bulk deallocation, and
-trivially support serialization (copy the `Vec[Node]` — done). The same pattern is used
-by `rustc`, `swiftc`, and `clang`.
-
-### Monomorphization during HIR construction, not during lowering
-
-Generics are resolved to concrete types during the semantic pass (AST → HIR). This is
-simpler than the Ruby compiler's inline-lowering approach and sufficient for a
-single-compilation-unit compiler. The HIR is fully resolved — every type variable is
-replaced, every generic call has concrete type arguments. This makes the lowering pass a
-pure transformation with no type-level work.
-
-If separate compilation of generics becomes necessary later, a dedicated
-monomorphization pass can be inserted between HIR construction and lowering. The IR
-separation already accommodates this.
-
-### (Sugar) Inline methods in struct bodies
-
-`mtc`'s Ruby compiler supports defining methods directly inside struct bodies —
-no separate `extending` block required. The parser desugars inline `function` /
-`editable function` / `static function` declarations into synthetic `ExtendingBlock`
-nodes targeting the enclosing struct. This is pure syntactic sugar with zero
-semantic or code-generation impact.
-
-```mt
-# These are equivalent:
-struct Counter:
-    value: int
-
-    function read() -> int:
-        return this.value
-
-# same as:
-struct Counter:
-    value: int
-
-extending Counter:
-    function read() -> int:
-        return this.value
-```
-
-Type parameters declared on the struct are in scope for all inline methods,
-enabling generic methods without re-declaring type params.
-
-```mt
-struct Box[T]:
-    inner: T
-
-    function unwrap() -> T:
-        return this.inner
-```
-
-The self-hosted plan uses this sugar throughout for cleaner code layout — struct
-definitions keep their core methods visually adjacent.
-
-### C backend as primary target
-
-The C backend is the pragmatic first target: it reuses the Ruby compiler's C runtime
-conventions, is portable to any platform with a C compiler, and lets the self-hosted
-compiler bootstrap on any architecture. LLVM is the strategic second target for native
-compilation speed.
-
-### Diagnostics-first design (LSP-ready, not LSP-included)
-
-The `DiagnosticEngine` uses byte-offset `SourceSpan` values (not line:column pairs with
-string interpolation), suitable for both CLI output and LSP protocol position encoding.
-Error recovery in the parser produces a best-effort AST even with syntax errors. The
-LSP server itself is deferred to v2, but the data model is designed to accommodate it
-without refactoring.
-
-### Symmetric module structure with the Ruby compiler
-
-`module_loader.mt`, `module_path_resolver.mt`, and `module_binder.mt` mirror the Ruby
-compiler's module infrastructure. This is intentional — the Ruby compiler's module
-system has been hardened through real-world use and its design is sound. The self-hosted
-compiler reimplements the same semantics in Milk Tea, not a new design.