mt-lang 0.3.26 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95066d5ccb69388c431a7b4b963853211c3ef57d8e776de1f8468ecdc983899b
-  data.tar.gz: 83a55caa84c9d54eda5b104727ce0ee4615b4780270d14d0cea4d2001b2fe9fd
+  metadata.gz: 20058db447f681f83bcc651d9a9772e79b23bd9f1677e5c33d2053bab536a14f
+  data.tar.gz: 204af7f1018ce7637690eddc2bc9a7f297fc1f10e59c1a573491bd3b7c0b0d1c
 SHA512:
-  metadata.gz: a6e8f3cf4ed18ec8cd2bdbfbb8ee458f7662546619f31c55bb00123d22bb9150888e405a692cbeea9c67b10bad2e3c82c621efae9992223e1d0c9bd51281f0a2
-  data.tar.gz: 7cb61c0021e8864897a5b23077dadf54586bf11b11a546ec9b19cbb59083dce4c60d7c8bd996c39380d1a80ea266a364008a1a3f2e3fba7f362ad57c2d97c1d0
+  metadata.gz: ec63256de42954560cedc8e5021370b8f45a64e083ebb839d3057d4ea93816a51d45f950283ece162152ad10be6f1bb6ec4aa54a6ad8ce7b2db107830dd1db6a
+  data.tar.gz: 616bc238b0ee79df60a7a09fc62b895b1ab7717a1116a6b96c50879549578ba0aab91fbb9a74e40aedfc559973c333a8bc2c2cc40d3d16b6913584a744230819

data/README.md

@@ -249,6 +249,10 @@ struct Vec2:
     x: float
     y: float
 
+    # Methods may also be defined directly inside the struct body:
+    function length_sq() -> float:
+        return this.x * this.x + this.y * this.y
+
 @[packed]
 struct Header:
     tag: ubyte
@@ -310,6 +314,7 @@ variant Token:
 Rules:
 
 - `struct` and `opaque` may declare nominal interface conformance with `implements`.
+- `struct` bodies may contain `function`, `editable function`, and `static function` declarations directly — they desugar to `extending` blocks targeting the enclosing struct. This is pure syntactic sugar; the compiler emits identical code as a separate `extending` block.
 - `attribute[target, ...]` declares reusable declaration attributes for `struct`, `field`, `callable`, `const`, `event`, `enum`, `flags`, `union`, and `variant` targets.
 - Attributes are applied with one or more leading `@[name(...)]` blocks. Built-in `packed`, `align(bytes)`, and `deprecated(message)` are predefined attributes.
 - `variant` arms may carry named payload fields.
@@ -358,11 +363,31 @@ Method kinds:
 - `editable function` -> editable receiver
 - `static function` -> no receiver
 
+Methods may appear inside a struct body (desugared to an `extending` block) or in a separate
+`extending` declaration:
+
+```mt
+struct Counter:
+    value: int
+
+    function read() -> int:
+        return this.value
+
+    editable function bump() -> void:
+        this.value += 1
+
+    static function zero() -> Counter:
+        return Counter(value = 0)
+```
+
+Both inline and `extending` forms lower to identical C code.
+
 Method notes:
 
 - Async methods are supported.
 - Generic methods are supported.
 - There is no constructor keyword. Names like `init` and `default` are ordinary static methods.
+- Methods may be defined inside struct bodies directly (as syntactic sugar for `extending`) or in separate `extending` blocks. Both forms lower to the same C code; the inline form is preferred when the struct and its core methods appear in the same file.
 
 ## 7. Functions, Externals, And Foreign Functions
 

data/docs/language-manual.md

@@ -300,7 +300,25 @@ Callable and `ref[...]` rules:
 struct Vec2:
     x: float
     y: float
+```
+
+`struct` bodies may also contain `function`, `editable function`, and `static function` declarations directly — they desugar to `extending` blocks targeting the enclosing struct. This is pure syntactic sugar and produces identical C code. See §3.6 for the method kind rules.
+
+```mt
+struct Counter:
+    value: int
+
+    function read() -> int:
+        return this.value
+
+    editable function bump() -> void:
+        this.value += 1
+
+    static function zero() -> Counter:
+        return Counter(value = 0)
+```
 
+```mt
 union Number:
     i: int
     f: float
@@ -417,7 +435,25 @@ Rules:
 
 ### 3.6 Methods
 
+Methods may appear directly inside a struct body (desugared to an `extending` block) or in a separate `extending` declaration. Both forms lower to identical C code.
+
+```mt
+# Inline form (sugar)
+struct Counter:
+    value: int
+
+    function read() -> int:
+        return this.value
+
+    editable function bump() -> void:
+        this.value += 1
+
+    static function zero() -> Counter:
+        return Counter(value = 0)
+```
+
 ```mt
+# Equivalent extending form
 extending Counter:
     function read() -> int:
         return this.value

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

@@ -0,0 +1,737 @@
+# 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.

data/lib/milk_tea/base.rb

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

data/lib/milk_tea/core/parser/declarations.rb

@@ -369,7 +369,7 @@ module MilkTea
         AST::AttributeDecl.new(name: name_token.lexeme, targets:, params:, visibility:, line:, column: name_token.column)
       end
 
-      def parse_struct_decl(packed: false, alignment: nil, visibility: :private, attributes: [])
+      def parse_struct_decl(packed: false, alignment: nil, visibility: :private, attributes: [], inline_methods: true)
         line = previous.line
         name_token = consume_name("expected struct name")
         name = name_token.lexeme
@@ -377,13 +377,32 @@ module MilkTea
         implements = parse_implements_clause
         c_name = parse_optional_c_name
         packed, alignment = parse_struct_layout_attributes(attributes) if attributes.any?
-        members = parse_recoverable_block do
-          parse_struct_member
+        receiver_type_param_names = type_params.map(&:name)
+        members = with_type_param_names(receiver_type_param_names) do
+          parse_recoverable_block do
+            parse_struct_member
+          end
         end
         fields = members.filter_map { |kind, member| member if kind == :field }
         events = members.filter_map { |kind, member| member if kind == :event }
         nested_types = members.filter_map { |kind, member| member if kind == :nested_type }
-        AST::StructDecl.new(name:, type_params:, implements:, c_name:, fields:, events:, nested_types:, attributes:, packed:, alignment:, visibility:, lifetime_params:, line:, column: name_token.column)
+        methods = members.filter_map { |kind, member| member if kind == :method }
+        struct_decl = AST::StructDecl.new(name:, type_params:, implements:, c_name:, fields:, events:, nested_types:, attributes:, packed:, alignment:, visibility:, lifetime_params:, line:, column: name_token.column)
+
+        if inline_methods && methods.any?
+          type_ref_args = type_params.map do |tp|
+            AST::TypeArgument.new(
+              value: AST::TypeRef.new(name: AST::QualifiedName.new(parts: [tp.name]), arguments: [], nullable: false, line: tp.line, column: tp.column),
+              line: tp.line,
+              column: tp.column,
+            )
+          end
+          type_ref = AST::TypeRef.new(name: AST::QualifiedName.new(parts: [name]), arguments: type_ref_args, nullable: false, line: name_token.line, column: name_token.column)
+          extending_block = AST::ExtendingBlock.new(type_name: type_ref, methods:, line: name_token.line, column: name_token.column)
+          [struct_decl, extending_block]
+        else
+          struct_decl
+        end
       end
 
       def parse_struct_decl_params
@@ -429,8 +448,24 @@ module MilkTea
         [lifetime_params, type_params]
       end
 
+      def check_method_start?
+        saved = @current
+        match(:public)
+        match(:async)
+        match(:editable) if check(:editable)
+        match(:static) if check(:static)
+        result = check(:function)
+        @current = saved
+        result
+      end
+
       def parse_struct_member
         field_attributes = parse_attribute_applications
+
+        if check_method_start?
+          return [:method, parse_method_def(attributes: field_attributes)]
+        end
+
         visibility, visibility_token = parse_visibility
 
         if match(:event)
@@ -438,7 +473,7 @@ module MilkTea
         end
 
         if match(:struct)
-          return [:nested_type, parse_struct_decl(visibility:, attributes: field_attributes)]
+          return [:nested_type, parse_struct_decl(visibility:, attributes: field_attributes, inline_methods: false)]
         end
 
         raise error(visibility_token, "public is only allowed on struct events") if visibility == :public

data/lib/milk_tea/core/parser.rb

@@ -154,13 +154,23 @@ module MilkTea
       until eof?
         if errors
           begin
-            declarations << parse_declaration
+            result = parse_declaration
+            if result.is_a?(Array)
+              declarations.concat(result)
+            else
+              declarations << result
+            end
           rescue ParseError => e
             errors << e
             synchronize_to_top_level_boundary
           end
         else
-          declarations << parse_declaration
+          result = parse_declaration
+          if result.is_a?(Array)
+            declarations.concat(result)
+          else
+            declarations << result
+          end
         end
         skip_newlines
       end

data/lib/milk_tea/tooling/linter/visitors.rb

@@ -164,7 +164,10 @@ module MilkTea
             end
           end
           check_redundant_type_annotation(statement)
-          flag_redundant_widening_cast(statement.value) if statement.type && statement.value
+          if statement.type && statement.value
+            flag_redundant_widening_cast(statement.value)
+            flag_redundant_literal_cast(statement.value)
+          end
           record_ptr_candidate(statement)
         when AST::Assignment
           visit_expression(statement.value)          # visit RHS first — reads in RHS count against dead-assignment
@@ -173,7 +176,10 @@ module MilkTea
           mark_mutated(statement.target)
           check_self_assignment(statement)
           check_noop_compound_assignment(statement)
-          flag_redundant_widening_cast(statement.value) if statement.operator == "="
+          if statement.operator == "="
+            flag_redundant_widening_cast(statement.value)
+            flag_redundant_literal_cast(statement.value)
+          end
         when AST::IfStmt
           statement.branches.each do |branch|
             visit_expression(branch.condition)
@@ -223,7 +229,10 @@ module MilkTea
           @loop_depth -= 1
         when AST::ReturnStmt
           visit_expression(statement.value) if statement.value
-          flag_redundant_widening_cast(statement.value) if statement.value
+          if statement.value
+            flag_redundant_widening_cast(statement.value)
+            flag_redundant_literal_cast(statement.value)
+          end
         when AST::DeferStmt
           with_scope { visit_statement_list(statement.body) }
         when AST::ExpressionStmt
@@ -278,6 +287,8 @@ module MilkTea
           visit_expression(expression.right)
           check_self_comparison(expression)
           check_redundant_bool_compare(expression)
+          check_redundant_binary_operand_cast(expression)
+          check_redundant_literal_operand_cast(expression)
         when AST::RangeExpr
           visit_expression(expression.start_expr)
           visit_expression(expression.end_expr)
@@ -1141,6 +1152,140 @@ module MilkTea
         emit_redundant_cast(value, target_name, "implicit widening makes this cast redundant")
       end
 
+      INTEGER_TYPE_RANGES = {
+        "byte"   => (-128..127),
+        "short"  => (-32_768..32_767),
+        "int"    => (-(2**31)..2**31 - 1),
+        "long"   => (-(2**63)..2**63 - 1),
+        "ubyte"  => (0..255),
+        "ushort" => (0..65_535),
+        "uint"   => (0..2**32 - 1),
+        "ulong"  => (0..2**64 - 1),
+        "char"   => (0..255),
+      }.freeze
+
+      # Reports an integer-literal cast at a coercion slot as redundant when the
+      # literal would implicitly coerce to the cast target: the compiler accepts
+      # a fitting integer literal for any integer slot (`buf[0] = 1` for a
+      # `ubyte` element), so `ubyte<-1` adds nothing. Out-of-range literals are
+      # left alone because removing the cast would then be a type error.
+      # Widening literal casts are already reported by flag_redundant_widening_cast.
+      def flag_redundant_literal_cast(value)
+        return unless value.is_a?(AST::PrefixCast)
+        return unless @sema_facts
+
+        target_name = type_ref_name(value.target_type)
+        return unless target_name
+        range = INTEGER_TYPE_RANGES[target_name]
+        return unless range
+
+        inner = value.expression
+        return unless inner.is_a?(AST::IntegerLiteral)
+        literal = inner.value
+        return unless literal.is_a?(Integer)
+        return unless range.cover?(literal)
+
+        inner_type = resolve_expr_type(inner)
+        return unless inner_type.is_a?(Types::Primitive)
+        return if inner_type.name == target_name # same-type handled elsewhere
+        return if implicit_cast_allowed?(inner_type, target_name) # widening handled elsewhere
+
+        emit_redundant_cast(value, target_name, "integer literal coercion makes this cast redundant")
+      end
+
+      BINARY_CAST_SAFE_OPS = %w[+ - * / % == != < <= > >=].freeze
+
+      # Reports a widening cast used directly as an operand of an arithmetic or
+      # comparison operator when removing it provably leaves the operation's
+      # result unchanged. An integer->float cast inside a float-family
+      # expression promotes to the sibling's float type either way, so the cast
+      # is redundant. Excluded:
+      #   * shifts (`<<`/`>>`) — the shifted operand's width is load-bearing;
+      #   * `double` in a `float` context — `float_y + double<-i` is `double`
+      #     with the cast but `float` without it;
+      #   * cast-chains such as `float<-x + float<-y` — each removal is only
+      #     safe if the sibling cast stays, so neither is independently
+      #     redundant.
+      def check_redundant_binary_operand_cast(binary)
+        return unless @sema_facts
+        return unless BINARY_CAST_SAFE_OPS.include?(binary.operator)
+
+        check_binary_operand_cast(binary.left, binary.right)
+        check_binary_operand_cast(binary.right, binary.left)
+      end
+
+      def check_binary_operand_cast(operand, sibling)
+        return unless operand.is_a?(AST::PrefixCast)
+        return if sibling.is_a?(AST::PrefixCast)
+
+        target_type = resolve_expr_type(operand)
+        return unless target_type.is_a?(Types::Primitive) && target_type.float?
+
+        inner_type = resolve_expr_type(operand.expression)
+        return unless inner_type.is_a?(Types::Primitive) && inner_type.fixed_width_integer?
+
+        sibling_type = resolve_expr_type(sibling)
+        return unless sibling_type.is_a?(Types::Primitive) && sibling_type.float?
+        return if target_type.name == "double" && sibling_type.name == "float"
+
+        target_name = type_ref_name(operand.target_type)
+        return unless target_name
+
+        emit_redundant_cast(operand, target_name, "implicit float widening makes this cast redundant")
+      end
+
+      COMPARISON_CAST_OPS = %w[== != < <= > >=].freeze
+
+      # Reports an integer-literal cast used directly as a comparison operand
+      # (e.g. `State.idle == ubyte<-0`). The literal coerces to the sibling's
+      # type either way, so `D<-lit` adds nothing when the literal fits `D` and
+      # the sibling is a float-family value, an integer the literal fits in, or
+      # an enum (which compares against any integer literal). Out-of-range
+      # literals are left alone: `ubyte<-300` wraps in `D`, which is not the
+      # same value as the bare literal.
+      def check_redundant_literal_operand_cast(binary)
+        return unless @sema_facts
+        return unless COMPARISON_CAST_OPS.include?(binary.operator)
+
+        check_comparison_literal_operand(binary.left, binary.right)
+        check_comparison_literal_operand(binary.right, binary.left)
+      end
+
+      def check_comparison_literal_operand(operand, sibling)
+        return unless operand.is_a?(AST::PrefixCast)
+
+        target_name = type_ref_name(operand.target_type)
+        return unless target_name
+        target_range = INTEGER_TYPE_RANGES[target_name]
+        return unless target_range
+
+        inner = operand.expression
+        return unless inner.is_a?(AST::IntegerLiteral)
+        literal = inner.value
+        return unless literal.is_a?(Integer)
+        return unless target_range.cover?(literal)
+
+        # Same-type casts are reported by check_redundant_cast.
+        inner_type = resolve_expr_type(inner)
+        return if inner_type.is_a?(Types::Primitive) && inner_type.name == target_name
+
+        sibling_type = resolve_expr_type(sibling)
+        case sibling_type
+        when Types::Primitive
+          return unless sibling_type.float? || sibling_type.integer?
+          if sibling_type.integer?
+            sibling_range = INTEGER_TYPE_RANGES[sibling_type.name]
+            return unless sibling_range && sibling_range.cover?(literal)
+          end
+        when Types::EnumBase
+          nil
+        else
+          return
+        end
+
+        emit_redundant_cast(operand, target_name, "integer literal coercion makes this cast redundant")
+      end
+
       def same_resolved_type?(left, right)
         return true if left.equal?(right)
 
@@ -1177,6 +1322,14 @@ module MilkTea
         target = find_primitive_type(target_name)
         return false unless target
         return false unless target.is_a?(Types::Primitive)
+
+        # Fixed-width integers widen implicitly to float/double (matching the
+        # compiler's promotion, e.g. `float + int` or `return int` from a
+        # `-> float` function). `char`/`bool` are not fixed-width integers and
+        # have no implicit conversion to the float family; float->double is not
+        # implicit either.
+        return true if target.float? && inner_type.fixed_width_integer?
+
         return false unless inner_type.fixed_width_integer? && target.fixed_width_integer?
 
         if inner_type.signed_integer? == target.signed_integer?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mt-lang
 version: !ruby/object:Gem::Version
-  version: 0.3.26
+  version: 0.3.28
 platform: ruby
 authors:
 - Long (Teefan) Tran
@@ -149,6 +149,7 @@ 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
@@ -624,7 +625,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.26 installed!
+  Milk Tea 0.3.28 installed!
 
   System requirements:
     - A C compiler (gcc or clang) must be available on PATH