mt-lang 0.2.0

data/docs/language-design.md

@@ -0,0 +1,1519 @@
+# Milk Tea Language Design
+
+Milk Tea is a statically typed, indentation-based systems language for games.
+It is shaped by a few fixed commitments:
+
+- data layout and ABI boundaries stay explicit
+- public types and control flow stay easy to read
+- everyday code stays low-ceremony without hiding costs
+- unsafe operations stay available, but always spelled directly
+
+The output target is beautiful C. The generated C should be readable enough that a human can debug it, diff it, and ship it without feeling trapped inside a compiler's private IR.
+
+## Primary goals
+
+1. Be obvious to read. The language should look like code, not punctuation.
+2. Stay statically typed. Public APIs must be explicit and unsurprising.
+3. Feel good for game programming. Tight loops, structs, arrays, arenas, handles, and FFI should be first-class.
+4. Interoperate with C as a native citizen. C libraries are not a side feature; they are part of the core story.
+5. Generate C that mirrors the source closely. No hidden runtime, hidden heap traffic, or hidden dispatch.
+
+## Non-goals
+
+- No exceptions
+- No inheritance
+- No hidden virtual dispatch
+- No operator overloading beyond the built-in operators
+- No trait system or typeclass constraint solver beyond explicit nominal interfaces
+- No macro system that rewrites arbitrary ASTs
+- No garbage collector
+- No implicit conversions between unrelated primitive types
+- No user-invisible allocation for strings, collections, closures, or method calls. If a surface allocates owned text or storage, the allocating surface must be spelled in source.
+
+## Design rules
+
+### 1. What you see is what runs
+
+If code allocates, takes an address, dereferences a raw pointer, performs an FFI call, or enters unsafe territory, the source should say so directly.
+
+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.
+
+### 2. C is the ABI ground truth
+
+Milk Tea must represent C structs, unions, enums, flags, pointers, arrays, callbacks, and calling conventions without lossy translation.
+
+### 3. Safe by default, unsafe by choice
+
+The language should help with common mistakes, but it must not hide the machine model. Sharp operations are allowed, but only behind explicit syntax.
+
+### 4. Data-oriented design comes first
+
+Plain structs, arrays, spans, pools, and arenas matter more than elaborate object systems.
+
+### 5. The language surface stays small
+
+If a feature saves five lines but makes lowering, tooling, or debugging much harder, it does not belong in v1.
+
+### 6. One job, one canonical surface
+
+Milk Tea should not accumulate multiple everyday spellings for the same job.
+
+When two surfaces overlap, one must be the normal user-facing form and the other must be either a low-level escape hatch or an implementation detail.
+
+The intended reductions are deliberate:
+
+- borrowed text is `str`
+- raw ABI text is `cstr`
+- fixed-capacity mutable text is `str_buffer[N]`
+- growable owned text is `std.string.String`
+- raw character storage is `array[char, N]` or `span[char]`, not an alternate text object
+- safe single-object aliasing is `ref[T]`
+- raw writable pointers are `ptr[T]`
+- owning heap pointers are `own[T]` — auto-dereferences like `ref` but storable, returnable, and nullable. `heap.must_alloc[T](count)` returns `own[T]`. Compiles to `T*`.
+- raw read-only pointers are `const_ptr[T]`
+- sized many-element borrows are `span[T]`
+- pointer-like absence is `null`, not `zero[ptr[T]]` in typed nullable contexts
+- imported foreign declarations own marshalling policy; raw `std.c.*` declarations stay exact
+
+If a new feature introduces a second ordinary way to express the same concept, the language should delete one of them instead of documenting both.
+
+The compile-time evaluation surface is described in [Compile-Time Evaluation](compile-time.md).
+
+## Overall shape
+
+- Indentation defines blocks.
+- A colon starts a block.
+- Newlines terminate statements.
+- Newlines inside `()` and `[]` do not terminate statements.
+- A physical line that ends with a binary operator also continues onto the next line.
+- Tabs are illegal in source files; indentation is 4 spaces.
+- Trailing commas are allowed in multiline call arguments and aggregate literals. The linter additionally flags a redundant trailing comma in a call-argument list (`trailing-list-comma` hint); aggregate and array literals keep them for diff-friendliness.
+- Comments use `#`.
+- Documentation comments use `##` and are markdown blocks attached to the next declaration when no blank line intervenes.
+- Names are `snake_case` for modules, variables, and functions.
+- Types use `PascalCase`.
+- Generated binding modules preserve C names exactly at the ABI layer.
+- Imported foreign modules use normal Milk Tea naming.
+
+Example:
+
+```mt
+import std.math as math
+import std.raylib as rl
+
+const screen_width: int = 1280
+const screen_height: int = 720
+
+struct Player:
+	position: rl.Vector2
+	velocity: rl.Vector2
+	radius: float
+
+extending Player:
+	editable function update(dt: float):
+		this.position.x += this.velocity.x * dt
+		this.position.y += this.velocity.y * dt
+
+function main() -> int:
+	rl.init_window(screen_width, screen_height, "Milk Tea")
+	defer rl.close_window()
+
+	var player = Player(
+		position = rl.Vector2(x = 400.0, y = 300.0),
+		velocity = rl.Vector2(x = 140.0, y = 100.0),
+		radius = 18.0,
+	)
+
+	while not rl.window_should_close():
+		let dt = rl.get_frame_time()
+		player.update(dt)
+
+		rl.begin_drawing()
+		defer rl.end_drawing()
+
+		rl.clear_background(rl.BLACK)
+		rl.draw_circle_v(player.position, player.radius, rl.GOLD)
+
+	return 0
+```
+
+For long expressions, the preferred style is the Python-like one: wrap inside delimiters so the continuation is structurally obvious. Operator-led continuation is supported, but it should remain the secondary style for cases where it is already clear.
+
+## Syntax and readability rules
+
+Milk Tea should use a deliberately small punctuation set. The only everyday symbolic forms are:
+
+- `:` for blocks
+- `->` for function return types
+- `.` for field and module access
+- `[]` for indexing and generic arguments
+- `?` for nullable types
+
+Everything else should prefer words over symbols.
+
+Address formation and dereference stay as word forms: `ref_of(expr)`, `const_ptr_of(expr)`, `ptr_of(expr)`, `read(ref_value)`, and `read(ptr_value)`.
+
+### Declarations
+
+```mt
+import std.math
+
+const gravity: float = 9.81
+
+type EntityId = uint
+
+struct Body:
+	id: EntityId
+	mass: float
+	velocity: float
+
+enum BodyKind: ubyte
+	dynamic = 1
+	static = 2
+
+flags DrawFlags: uint
+	visible = 1 << 0
+	selected = 1 << 1
+```
+
+### Variables
+
+- `let` creates an immutable local binding.
+- `var` creates a mutable local binding.
+- `const` defines a compile-time constant.
+- A typed local declaration without `= ...` zero-initializes that local. This is the normal local-storage form and is only valid for types that `zero[T]` already supports. Use `zero[T]` or `Type()` only when you need a value expression.
+- Use `zero[T]` when you want raw zero-initialization. Use `default[T]` when you want a semantic default value supplied by an accessible `T.default()` associated function.
+- When a generic API depends on that semantic default, call `default[T]` directly in the generic body and document the requirement in the API prose or naming.
+- `init` is not special syntax. Constructor-like setup remains an ordinary static method naming convention such as `Type.init(...)`.
+- For pointer-like absence, use a nullable type plus `null`. `zero[ptr[T]]` remains available for low-level zero-initialized pointer storage, but the compiler rejects it when the surrounding expected type is already a nullable pointer-like type. In those contexts, write `null`.
+
+```mt
+let width: int = 1280
+var score: int = 0
+var name_input: str_buffer[64]
+const max_players: int = 4
+```
+
+Tuple literal and destructuring:
+
+```mt
+let pair = (42, "hello")         # positional tuple
+let point = (x = 10, y = 20)     # named tuple
+let (a, b) = pair                # destructure positional
+let (x, y) = point               # destructure named
+let Vec2(x, y) = get_position()  # struct destructure
+```
+
+A function can return a tuple type: `function pair() -> (int, str):`.
+
+Local type inference is allowed when the initializer makes the type obvious:
+
+```mt
+let dt = rl.get_frame_time()    # inferred as float
+var player_count = 0            # inferred as int
+```
+
+Guard binding is part of the local declaration surface:
+
+```mt
+let handle = maybe_handle else:
+	return 1
+
+let image = load_image(path) else:
+	return 1
+
+let config = load_config() else as error:
+	return error
+
+let _ = initialize_runtime() else:
+	return 1
+```
+
+The initializer may be `T?`, `Option[T]`, or `Result[T, E]`. For nullable inputs the bound name is the non-null `T`; for `Option[T]` it is the `some.value`; for `Result[T, E]` it is the `success.value`, and `else as error:` optionally binds the `failure.error` value for the failure path. Use `let _ = expr else:` when the success path should be checked but not bound, including `Result[void, E]`. The `else` block must terminate control flow.
+
+Public items should always spell their types out.
+
+### Functions
+
+```mt
+function clamp(value: float, min_value: float, max_value: float) -> float:
+	if value < min_value:
+		return min_value
+	else if value > max_value:
+		return max_value
+	else:
+		return value
+```
+
+There is no overloading. One function name maps to one callable symbol.
+
+### Methods
+
+Methods are syntax sugar over namespaced functions. They do not imply objects, inheritance, or dynamic dispatch.
+
+```mt
+struct Camera:
+	position: Vec2
+	zoom: float
+
+extending Camera:
+	editable function move_by(delta: Vec2):
+		this.position.x += delta.x
+		this.position.y += delta.y
+
+	function world_scale() -> float:
+		return this.zoom
+
+	static function origin() -> Camera:
+		return Camera(position = Vec2(x = 0.0, y = 0.0), zoom = 1.0)
+```
+
+Lowering rule, in emitted C:
+
+- `camera.move_by(delta)` emits `game_Camera_move_by(&camera, delta)`.
+- `camera.world_scale()` emits `game_Camera_world_scale(camera)`.
+- `Camera.origin()` emits `game_Camera_origin()`.
+
+Receiver rule:
+
+- Plain `function` inside `extending T:` means an implicit `this: T` value receiver.
+- `editable function` inside `extending T:` means an implicit writable `this` receiver and requires an addressable receiver.
+- `static function` inside `extending T:` means there is no receiver.
+- There is no hidden dynamic dispatch, vtable lookup, or heap allocation.
+
+Value receivers are deliberate. They keep fluent calls on temporaries honest and let method calls lower directly to plain C value parameters. Writable methods are the only place where the compiler takes an address implicitly.
+
+The rule is fixed and inspectable. There is no method lookup at runtime.
+
+### Interfaces
+
+Interfaces are explicit nominal method-set contracts for static polymorphism.
+They do not introduce inheritance, hidden dispatch, or a second object model.
+
+```mt
+interface Damageable:
+	editable function take_damage(amount: int) -> void
+	function is_alive() -> bool
+
+struct NPC implements Damageable:
+	name: str
+	hp: int
+
+extending NPC:
+	editable function take_damage(amount: int):
+		this.hp -= amount
+
+	function is_alive() -> bool:
+		return this.hp > 0
+```
+
+Conformance belongs on the nominal type declaration, not on an `extending` block.
+That keeps the contract visible at the owning type and avoids import-sensitive structural matching.
+
+Rules for interfaces in v1:
+
+- `interface` bodies contain `function`, `editable function`, or `static function` signatures.
+- Generic interfaces are supported: `interface Mapper[T]: function map(x: T) -> T`.
+- Interface methods may not have bodies, fields, constants, default implementations, associated types, or inheritance.
+- Interface methods may not declare their own type params or be `async`.
+- `struct` and `opaque` declarations may implement zero or more interfaces.
+- Multiple interfaces are allowed: `struct Boss implements Damageable, Drawable:`.
+- A type implements an interface only when its declaration says so explicitly.
+- Conformance matching uses method kind, receiver mutability when applicable, parameter types, return type, and asyncness.
+- An `editable function` requirement must be satisfied by an editable method exactly.
+- If two interfaces require the same method with the same signature, one implementation satisfies both. If the signatures differ, the declaration is rejected.
+- Interface conformance is a compile-time fact, not a storage type.
+
+Generic constraints use the same word form:
+
+```mt
+function deal_area_damage[T implements Damageable](targets: span[T], amount: int):
+	for i in 0..targets.len:
+		if targets[i].is_alive():
+			targets[i].take_damage(amount)
+```
+
+When one type parameter needs multiple interfaces, join them with `and` inside the type-parameter clause:
+
+```mt
+function update_and_draw[T implements Updatable and Drawable](value: ref[T]):
+	value.update()
+	value.draw()
+```
+
+Canonical hash, equality, and ordering hooks remain associated functions `T.hash(value: const_ptr[T]) -> uint`, `T.equal(left: const_ptr[T], right: const_ptr[T]) -> bool`, and `T.order(left: const_ptr[T], right: const_ptr[T]) -> int`. The built-in `hash[T](...)`, `equal[T](...)`, and `order[T](...)` forms lower directly to those associated functions after borrowing safe lvalues or forwarding existing refs and pointers.
+
+The separate `hashes` and `equates` constraint keywords were removed because they were only contract spelling. They were not the thing that made the built-ins work; direct `hash[T](...)`, `equal[T](...)`, and now `order[T](...)` use already force the canonical hooks at specialization time.
+
+Ordered std surfaces should now rely on the canonical tri-state `order[T](...)` hook instead of storing per-instance comparator callbacks when the element type already has a natural ordering. Current ordered surfaces include `std.binary_heap.BinaryHeap[T]`, the thin `std.priority_queue.PriorityQueue[T]` facade over it, `std.ordered_set.OrderedSet[T]` for unique ordered membership, and `std.ordered_map.OrderedMap[K, V]` for ordered associative storage.
+
+`default[T]` requires an explicit `T.default()` provider at each use site. The separate `defaults` constraint was removed because it duplicated that requirement while lengthening generic signatures. If an API depends on semantic defaulting, say so in the API docs and call `default[T]` directly in the generic body.
+
+Constraint checking happens after type inference and specialization, and constrained calls still lower to ordinary static method calls in generated C.
+There is no witness table or vtable for constrained generics.
+
+Bare interface names are not runtime value types in v1.
+That means surfaces such as `var x: Damageable`, `array[Damageable, 10]`, fields of interface type, and returns of bare interface type are invalid.
+Milk Tea supports runtime polymorphic interface values through `dyn[InterfaceName]`. The `dyn` keyword follows the same type constructor pattern as `ptr[T]`, `ref[T]`, and `span[T]`, making the indirection cost explicit in source.
+
+Because fixed arrays copy by value, mutating interface-constrained collection code should usually take `span[T]` or `ref[array[T, N]]` rather than `array[T, N]` by value.
+
+Iteration stays structural in v1 rather than going through a nominal `Iterator[T]` or `Iterable[T]` interface. Arrays, spans, and ranges keep their built-in behavior, and custom iterables participate by exposing the same method shape the compiler already recognizes: a non-editable `iter()` method on the iterable, then either `next() ->` nullable pointer-like item or `next() -> bool` together with `current()` on the iterator.
+
+This is deliberate. Interfaces are compile-time-only nominal contracts and are not generic today, so introducing a central iterator interface hierarchy now would either erase the item type or duplicate type-specific interfaces. The standard library should instead standardize on one iterator convention:
+
+- `collection.iter()` is the canonical traversal surface.
+- Alternate traversals use explicit view methods such as `map.keys()`, `map.values()`, and `map.entries()`.
+- Hash collections keep relying on the canonical `hash[T]` and `equal[T]` associated hooks instead of callback-style comparer objects.
+- Ordered collections can now rely on the canonical `order[T]` hook instead of forcing per-instance comparator storage when the type already has a natural ordering.
+
+### Control flow
+
+```mt
+if ready:
+	start_game()
+else if wants_menu:
+	open_menu()
+else:
+	show_intro()
+
+while running:
+	tick()
+
+for i in 0..count:
+	update_enemy(i)
+
+for body in bodies:
+	simulate(body)
+
+for entity, position in entities, positions:
+	integrate(entity, position)
+
+match event.kind:
+	EventKind.quit:
+		return 0
+	EventKind.resize:
+		resize(event.width, event.height)
+```
+
+Rules:
+
+- Conditions must be `bool`. Integers and pointers do not become truthy implicitly.
+- `match` must be exhaustive for enums.
+- `break` and `continue` use ordinary loop control semantics.
+- Single-form `for` accepts `start..stop`, `array[T, N]`, `span[T]`, and custom structural iterables.
+- A custom structural iterable must expose non-editable `iter()` with no arguments, and its iterator must expose either `next() ->` nullable pointer-like item or `next() -> bool` plus `current()`.
+- Parallel `for` accepts multiple array/span iterables and binds them in lockstep.
+- Parallel `for` does not accept ranges, and iterable lengths must match.
+
+Range-index assignment is also part of the control-flow-and-mutation surface when code wants an explicit fixed-width slice update:
+
+```mt
+buf[0..3] = (1.0, 2.0, 3.0)
+```
+
+The bounds are integer literals, the range is end-exclusive, and the right-hand tuple width must match the slice width exactly.
+
+### Useful structured features
+
+Milk Tea should include a small number of control-flow features that materially improve systems code without hiding behavior.
+
+#### `defer`
+
+`defer` registers cleanup code at scope exit and lowers to obvious cleanup labels in C.
+
+```mt
+
+
+function load_texture(path: str) -> Result[Texture, LoadError]:
+	let texture = rl.load_texture(path)
+
+	if texture.id == 0:
+		return Result[Texture, LoadError].failure(error= LoadError.file_not_found)
+
+	return Result[Texture, LoadError].success(value= texture)
+```
+
+#### `unsafe`
+
+`unsafe` is required for:
+
+- raw pointer dereference and field access through raw pointers
+- raw pointer arithmetic
+- unchecked casts and bit reinterpretation
+- pointer indexing
+- raw ABI work that is not covered by a declared foreign import contract
+
+```mt
+let p = unsafe: pixels + offset
+
+unsafe:
+	let pixel = read(ptr[uint]<-p)
+	pixels = p
+```
+
+The point is not to forbid sharp tools. The point is to mark them.
+Calling a foreign import that already declares borrowed strings, ordinary `str` parameters, string lists, `out` parameters, or typed pointer projections is ordinary code. Crossing into raw `std.c.*` bindings, doing pointer reinterpretation, or manually walking foreign memory remains explicit low-level work.
+
+#### `async` and `await`
+
+Milk Tea has a task surface today, but it is intentionally narrow and explicit.
+
+```mt
+async function child() -> int:
+	return 41
+
+async function parent() -> int:
+	let value = await child()
+	return value + 1
+```
+
+Current implemented shape:
+
+- `async function` lifts its return type to `Task[T]`
+- `await` is only valid inside async functions
+- async entrypoint bootstrapping is compiler-owned, but async helpers stay explicit library surface; import `std.async as aio` when user code needs `sleep`, `work`, `completed`, `result`, `wait`, `run`, or runtime control
+- `aio.wait(...)` and `aio.run(...)` accept direct task expressions as well as zero-arg task roots; the compiler rewrites the direct-task form into the deferred root shape automatically
+- async bodies support ordinary local declarations, including `let ... else:`, assignments, returns, `if`, `while`, single-form and parallel `for`, `match`, `defer`, `unsafe`, and deferred cleanup bodies that `await`
+- await placement is handled by the normalization pass which hoists nested awaits into `let` bindings, so `await` is supported in all expression contexts (call arguments, binary operations, if-expr, match-expr, member access, index access, format strings)
+
+The default async model is a language-integrated entry boundary. `std.async` remains the explicit high-level helper surface for operations such as `sleep`, `work`, `completed`, `result`, `wait`, `wait_on`, and `with_runtime`, while the normal runtime model stays the single integrated libuv-backed runtime.
+
+#### Concurrency: `parallel for` and `parallel:` blocks
+
+Milk Tea has first-class compiler support for multithreading. The threading model is structured: all spawned work completes before the parent scope continues. There is no hidden thread pool, no garbage collector interaction, and no fire-and-forget. Every thread boundary is visible in source.
+
+```mt
+# Data-parallel: each iteration runs on a separate CPU core
+parallel for i in 0..entity_count:
+    positions[i] += velocities[i] * dt
+
+# Structured fork-join: each do block runs on a separate thread
+parallel:
+    textures = load_textures(path)
+    sounds = load_sounds(path)
+```
+
+Design choices:
+
+- **Structured, not fire-and-forget.** All `parallel for` and `parallel:` blocks are synchronous barriers — the calling thread blocks until all work completes. This guarantees that captured local variables remain alive for the duration and eliminates lifetime concerns without ownership annotations.
+- **Compile-time safety.** `ref[T]` captures are rejected because mutable aliases across thread boundaries create data races. The `parallel:` block enforces single-writer-or-multiple-readers: if one statement writes a variable, no other block may read or write it.
+- **Value capture, pointer-based arrays.** Scalars and spans are captured by value (the span's data pointer still references the original storage). Arrays are captured as pointers to their first element, so writes in the worker affect the original array.
+- **`do` is a keyword.** It is recognized inside `parallel:` blocks to introduce each concurrent unit of work.
+- **Real OS threads via libuv.** Thread dispatch uses `uv_thread_create` / `uv_thread_join`, consistent with `std.thread` and `std.sync`. CPU count is detected at runtime via `uv_cpu_info`. The first chunk runs on the calling thread to avoid unnecessary dispatch when the workload is small.
+- **No forced dependency.** The build system automatically detects `parallel for` and `parallel:` usage via a sema-level flag and links libuv only when needed.
+
+#### Atomics: `atomic[T]`
+
+`atomic[T]` is a built-in type constructor for lock-free concurrent access to integer values. It lowers to C11 `_Atomic T` with `__atomic_*` builtins (GCC/Clang). All operations use sequential consistency.
+
+```mt
+var counter: atomic[int]
+counter.store(0)
+let prev = counter.add(1)
+let value = counter.load()
+```
+
+`atomic[T]` is deliberately narrow: it supports only primitive integer types and `bool`. This avoids the complexity of atomic struct operations and keeps the C lowering simple and efficient. For more complex synchronization patterns, use `std.sync.Mutex`, `std.sync.Condition`, and `std.sync.Semaphore`.
+
+## Type system
+
+The type system must stay simple, explicit, and close to C.
+
+### Primitive types
+
+- `bool`
+- `byte`
+- `char`
+- `byte`, `short`, `int`, `long`
+- `ubyte`, `ushort`, `uint`, `ulong`
+- `ptr_int`, `ptr_uint`
+- `float`, `double`
+- `void`
+- `str`
+- `cstr`
+- `vec2`, `vec3`, `vec4` — float vectors
+- `ivec2`, `ivec3`, `ivec4` — integer vectors
+- `mat3`, `mat4` — column-major matrices
+- `quat` — quaternion (memory-compatible with `vec4`)
+
+Notes:
+
+- Native vector, matrix, and quaternion types support aggregate construction: `vec3(x = 1.0, y = 2.0, z = 3.0)`, `quat(x = 0.0, y = 0.0, z = 0.0, w = 1.0)`, and column-wise `mat4(col0 = ..., col1 = ..., ...)`. Omitted fields default to zero.
+- `str` is a UTF-8 string view, not a NUL-terminated C string.
+- Every `str` value must contain valid UTF-8 bytes for its full length.
+- `cstr` is the raw ABI-facing NUL-terminated C string type. It belongs primarily in raw `external` files and low-level interop code.
+- `char` is the ABI-facing single-byte character type for C text and raw buffers. It is not a general arithmetic integer type.
+- String literals produce `str`.
+- Safe code does not fabricate `str` values from raw parts. Source code ordinarily obtains `str` values from literals, `str_buffer.as_str()`, slicing an existing `str`, imported foreign boundaries that declare borrowed text, or other compiler/runtime surfaces that preserve the UTF-8 invariant.
+- Low-level code may construct `str(data = ..., len = ...)` only inside `unsafe`, and the caller is then responsible for pointer validity, lifetime, and the UTF-8 invariant.
+- A string literal may satisfy an expected `cstr` directly when the compiler has contextual type information, such as a typed local, an `array[cstr, N]` element, or a borrowed C-string argument position, because static storage is known.
+- `c"hello"` produces `cstr` with static storage for raw ABI work and low-level interop.
+- `<<-TAG ... TAG` produces `str` and `c<<-TAG ... TAG` produces `cstr` for multiline block text. The content is dedented by the shared leading spaces of nonblank lines, and the newline before the terminator is preserved.
+- Whitespace-adjacent `"..."` / `c"..."` literal segments concatenate exactly with no implicit separator, so long text can wrap (or be split on one line) without introducing another literal form.
+- The VS Code extension may attach embedded grammars to specific heredoc tags such as `GLSL`, `VERT`, `FRAG`, `COMP`, `JSON`, `JSONC`, `SQL`, `HTML`, and `MT`, but that is editor-only highlighting. The `MT` tag recursively applies Milk Tea syntax highlighting to the heredoc content. It does not change runtime semantics, and SQL values should still use bound parameters rather than text interpolation.
+- There is no first-party runtime JSONC normalization layer; editor JSONC highlighting remains separate from runtime parsing.
+
+### Composite types
+
+```mt
+array[T, N]      # fixed-size array
+SoA[T, N]        # Structure-of-Arrays: flatten struct fields into separate arrays
+str_buffer[N]   # fixed-capacity mutable UTF-8 text buffer
+ptr[T]           # raw pointer
+span[T]          # pointer + length view
+fn(A, B) -> R    # function pointer type
+(T, U)           # tuple type (positional or named fields)
+```
+
+Examples:
+
+```mt
+let pixels: span[ubyte]
+let name_input: str_buffer[64]
+let labels: array[str, 8]
+let texture_ptr: ptr[Texture]
+let normal_table: array[float, 256]
+let callback: fn(ptr[void], int) -> void
+```
+
+Notes:
+
+- Fixed-array indexing is bounds-checked and safe by default.
+- Safe array indexing requires an addressable array value; bind temporaries before indexing them.
+- Safe indexing (`arr[i]`) aborts on out-of-bounds via `fatal`. Use `get(arr, i)` for recoverable bounds-checked access that returns `ptr[T]?`.
+- When a `span[T]` boundary is expected, addressable `array[T, N]` values coerce directly. Arrays also expose `.as_span()` for explicit conversion when the target type is not a call boundary.
+- `array[char, N]` and `span[char]` are the ordinary source-level forms for raw writable character storage and byte-oriented foreign buffers. They are not alternate text objects and should not grow a parallel everyday text API.
+- `str_buffer[N]` is the one source-level mutable UTF-8 text type. It owns `N` writable text bytes plus an implementation-managed trailing NUL slot, tracks current text length, and refreshes that length when a writable buffer alias mutates the underlying storage.
+- If low-level code needs to validate raw `array[char, N]` storage as text, that conversion belongs in an explicit helper or imported boundary, not as a built-in method family on raw arrays.
+- Addressable `str_buffer[N]` values also coerce to `span[char]`, so writable foreign text APIs can still accept builders directly when they do not want a second application-facing text abstraction.
+- `str_buffer[N]` is not an ABI type. Raw bindings still spell writable text as `ptr[char]` or `span[char]`; `str_buffer[N]` is the caller-side text object.
+- `str_buffer[N]` has a built-in text surface: `.clear()`, `.assign(str)`, `.append(str)`, `.len()`, `.capacity()`, `.as_str()`, and `.as_cstr()`.
+- `.assign(...)` replaces the current contents and traps at runtime if the new text exceeds capacity.
+- `.append(...)` extends the current contents and traps at runtime if the appended text would exceed capacity.
+- `.len()` returns the tracked text length, revalidating UTF-8 and rescanning for the trailing NUL if the builder was passed through a writable `span[char]` or `ptr[char]` alias.
+- `.capacity()` reports the maximum writable text bytes, not counting the reserved trailing NUL slot.
+- `.as_str()` and `.as_cstr()` borrow from the same builder storage and revalidate through that same dirty-refresh path before returning.
+- `str.slice(start, len)` uses byte offsets and byte lengths, but both the start and end position must be UTF-8 code-unit boundaries or the slice traps at runtime.
+- Ordinary string lists stay `array[str, N]` or `span[str]` in source. If an imported foreign declaration chooses that public surface for a raw `char **`, `span[cstr]`, or pointer-plus-length text-list API, the boundary owns the temporary marshalling.
+- Imported foreign declarations may map `str_buffer[N] as ptr[char]` directly when the public surface wants writable UTF-8 text with fixed caller capacity.
+- If the raw call also needs the caller buffer size, a `str_buffer[N]` public signature should pass `text_public.capacity() + 1` in the foreign mapping so the raw side sees the full writable byte count including the trailing NUL slot.
+- `span[char] as ptr[char]` remains the right public surface when the writable storage is not semantically UTF-8 text or when the caller capacity is intentionally runtime-sized instead of part of the type.
+- In an explicit foreign mapping, a parameter declared with `as` keeps the boundary value under its original name and exposes the public value as `<name>_public`.
+- Pointer indexing follows the raw pointer model and requires `unsafe`.
+
+### Nullability
+
+Milk Tea keeps nullability explicit. `T?` is valid for any type.
+
+```mt
+let window: ptr[Window]? = null
+let name: cstr? = null
+let port: int? = null
+```
+
+For pointer-like bases (`ptr[T]`, `const_ptr[T]`, `cstr`, `fn(...)`, `proc(...)`, opaque), `T?` is a nullable pointer and `null` reuses the null pointer as the absent value. For non-pointer value bases (`int`, `bool`, `float`, structs), `T?` is stored inline by value as a tagged optional — a presence flag plus the value. It copies by value with no hidden heap allocation, boxing, or pointer aliasing, which keeps value-type optionals consistent with the rest of the value-semantics model.
+`null` expresses absence in any nullable context. When contextual typing already determines the nullable pointer-like type, prefer bare `null` over a typed form such as `null[ptr[Window]]`; use a typed `null[...]` (whose target must be pointer-like) only when the surrounding context does not provide the target type.
+Do not use `zero[ptr[T]]` as a replacement for `null`; `null` expresses absence, while `zero[T]` is the generic value-initialization surface. When the expected type is already a nullable pointer-like type, the compiler rejects `zero[ptr[T]]` and requires `null`.
+At an FFI boundary, only pointer-like `T?` is allowed: `external` and `foreign function` parameters and returns reject a non-pointer value nullable such as `int?` so the C ABI stays unambiguous — use `ptr[T]?` or an explicit struct instead.
+
+### User-defined types
+
+#### Structs
+
+Structs are plain data. Field order is preserved.
+
+```mt
+struct Vec2:
+	x: float
+	y: float
+```
+
+Structs may contain nested struct declarations, which become independently named types scoped inside the parent:
+
+```mt
+struct Rectangle:
+	x: float
+	y: float
+
+	struct Edge:
+		start: float
+		end: float
+
+	top_edge: Edge
+	left_edge: Edge
+```
+
+Nested structs are full types, not inline anonymous members. Their qualified name is `Parent.Nested`
+(e.g., `Rectangle.Edge`). Inside the parent struct, bare names resolve to nested types. Outside,
+use the qualified name. Nested structs may themselves contain nested structs. The generated C name
+joins the path with underscores (e.g., `module_Rectangle_Edge`).
+
+#### Enums
+
+Enums always have an explicit backing type.
+
+```mt
+enum WeaponKind: ubyte
+	sword = 1
+	bow = 2
+	wand = 3
+```
+
+#### Flags
+
+Flags are named bitmasks with a fixed integer backing type.
+
+```mt
+flags WindowFlags: uint
+	fullscreen = 1 << 0
+	vsync = 1 << 1
+	borderless = 1 << 2
+```
+
+#### Unions
+
+Unions are allowed for FFI and low-level storage.
+
+```mt
+union Value:
+	i: int
+	f: float
+	raw: ptr[void]
+```
+
+Unions are untagged storage. The current implementation does not track an active field, so switching views is a low-level operation by design rather than a checked safe surface.
+
+#### Variants
+
+Variants are tagged unions. Each arm optionally carries named payload fields.
+
+```mt
+variant Token:
+	ident(text: str)
+	number(value: int)
+	eof
+```
+
+Arm constructors follow the same field-assignment form as struct literals. No-payload arms are bare member expressions. Match on a variant uses `as name` to bind a payload arm's fields. Generic variants are supported through specializations like `Box[int].some(value = 1)`.
+
+#### Opaque types
+
+Opaque types are essential for C handles.
+
+```mt
+opaque SDL_Window
+opaque ma_engine
+```
+
+#### Type aliases
+
+```mt
+type Seconds = float
+type FileHandle = ptr[libc.FILE]
+```
+
+### Generics
+
+Generics are useful, but they must stay boring. The compile-time surface is documented in [Compile-Time Evaluation](compile-time.md); generic bodies participate in that surface by using `when`, `inline for`, `inline while`, `inline match`, `inline if`, `type`-returning functions, `const function`, and block-bodied `const` initializers (`const X -> T: ...`) at the lexical positions where the compile-time rules allow them.
+
+Allowed in v1:
+
+- generic structs
+- generic variants
+- generic functions
+- generic functions with explicit `implements` interface constraints
+- explicit specialization calls
+- monomorphized code generation
+
+Not allowed in v1:
+
+- structural or inferred generic constraints (use `implements` for nominal constraints; use reflection and `inline for` for ad-hoc structural checks)
+
+Example:
+
+```mt
+struct Slice[T]:
+	data: ptr[T]
+	len: ptr_uint
+
+function first[T](items: Slice[T]) -> ptr[T]?:
+	if items.len == 0:
+		return null
+	return items.data
+
+function capacity_of[N](buffer: str_buffer[N]) -> ptr_uint:
+	return buffer.capacity()
+
+function explicit_capacity(buffer: str_buffer[32]) -> ptr_uint:
+	return capacity_of[32](buffer)
+```
+
+Explicit specialization arguments may be type references like `bytes_for[int](4)` or numeric literals like `capacity_of[32](buffer)` when the generic parameter is used in a literal slot such as `str_buffer[N]` or `array[T, N]`.
+
+## Expressions and conversions
+
+### Operators
+
+Built-in operators should match familiar C behavior where possible:
+
+- arithmetic: `+ - * / %`
+- comparison: `== != < <= > >=`
+- boolean: `and or not`
+- bitwise: `& | ^ ~ << >>`
+
+No user-defined operator overloading.
+
+Built-in vector, matrix, and quaternion types support component-wise arithmetic with the standard operators:
+
+- Vectors (`vecN`/`ivecN`): `+`, `-`, `*` (component-wise same-type); `*`, `/` (scalar); unary `-`
+- Matrices (`matN`): `+`, `-` (component-wise same-type); `*`, `/` (scalar); unary `-`
+- Quaternions (`quat`): `+`, `-`, `*` (component-wise same-type); unary `-`
+
+### Casts
+
+Conversions are explicit. Use `T<-expr` for ordinary conversions.
+
+```mt
+let count64 = ulong<-count32
+let value = float<-raw
+let newline = char<-10
+```
+
+For bit reinterpretation, use a separate form inside `unsafe`:
+
+```mt
+unsafe:
+	let bits = reinterpret[uint](value)
+```
+
+Binary arithmetic and numeric comparison operators may promote primitive operands to a common type locally.
+This is limited to `+ - * / % == != < <= > >=` and does not change assignment, return, or aggregate-field typing rules.
+Non-external call boundaries remain strict, but external calls may pass enum or flags values to same-width fixed-width integer parameters without an explicit cast for C ABI interop.
+Mixed signed and unsigned integers still require an explicit cast.
+
+`char` stays outside the general numeric-promotion rules. If code wants arithmetic on a character value, cast it to an integer type first. If code wants to write bytes back into a `char` buffer, either use `char<-...` explicitly or rely on the expected `char` boundary where a known `char` target is being initialized or assigned.
+
+Example:
+
+```mt
+let newline = char<-10
+
+unsafe:
+	buffer[0] = 65
+	buffer[1] = newline
+	let code = int<-buffer[0]
+```
+
+### Literals
+
+```mt
+42
+0xff
+0b1010
+3.14159
+"hello"
+c"hello"
+```
+
+Integer literals are untyped until context resolves them, defaulting to `int`.
+Float literals default to `float` when unconstrained.
+
+Typed contexts may adopt the expected numeric type for a literal directly. This is limited to literal typing, not general implicit conversion.
+
+Exact compile-time numeric constants may also fit an explicit numeric target without a manual cast when the value is representable exactly in that target type. This applies to literals, named `const`s, and immutable locals whose initializer is itself a compile-time numeric constant. If the value would lose range or precision, the compiler rejects it; this is a type error, not a linter warning.
+
+There is one additional narrow boundary rule for float-heavy code: a primitive integer expression may flow into an expected float type for an explicitly typed local declaration, an assignment to a float-typed lvalue (`=` and arithmetic compound assignment operators), a return expression from a float-returning function, an ordinary function argument with a float parameter type, or an aggregate/variant field initializer with a float field type.
+
+This is still a boundary cast, not a general usual-arithmetic-conversions model. It does not widen public constant initialization or arbitrary expression typing. Integer arithmetic stays integer arithmetic until that final boundary cast, so `let ratio: float = hits / total` still performs integer division before the result is converted.
+
+Foreign/external numeric boundaries are stricter: runtime implicit conversion is limited to provably lossless widening within the same numeric family. Truncating conversions and runtime implicit integer-to-float or float-to-integer conversions at foreign boundaries require an explicit cast. Exact compile-time numeric constants are still allowed when the target type can represent them exactly.
+
+Examples of typed contexts:
+
+- a declaration with an explicit type
+- a function argument with a known parameter type
+- a struct field initializer with a known field type
+- a return expression with a known return type
+
+This keeps `float`-heavy game code readable while preserving the rule that ordinary expressions do not silently convert between numeric types.
+
+### Composite literals
+
+There are no constructors with hidden logic in v1. Aggregate construction uses field and element literals directly.
+Multiline aggregate-style calls may use trailing commas so data-heavy code stays easy to diff.
+Omitted fields in plain aggregate literals and omitted tail elements in fixed-array literals default to zero.
+That means `Type()`, `Type(field = value)`, `array[T, N]()`, and `array[T, N](a, b)` are all just zero-default data literals, not constructor calls.
+There are still no default field expressions, hidden initializer functions, or other non-local effects during construction.
+Typed locals without `= ...` remain the declaration form for zero-initialized storage; these aggregate literals are the expression forms when code needs a value.
+
+```mt
+let player = Player(
+	position = Vec2(x = 10.0, y = 20.0),
+	velocity = Vec2(x = 0.0, y = 0.0),
+)
+
+let origin = Player()
+
+let palette = array[uint, 4](0xff0000ff, 0x00ff00ff, 0x0000ffff, 0xffffffff)
+let grayscale = array[uint, 4](0x111111ff, 0x555555ff)
+```
+
+This keeps data construction obvious and maps cleanly to C initializers.
+
+## Memory model
+
+The memory model must feel like C with better defaults and cleaner surfaces.
+
+### Value semantics by default
+
+- Scalars copy by value.
+- Structs copy by value.
+- Fixed arrays copy by value.
+- Returning a struct is allowed and lowers to normal C return or out-parameter lowering as needed.
+
+There is no hidden reference counting and no hidden heap boxing.
+
+### Explicit allocation
+
+Heap allocation is always explicit and allocator-driven.
+
+```mt
+import std.mem.heap as heap
+
+function spawn_enemy(start: Vec2) -> own[Enemy]:
+	let enemy = heap.must_alloc[Enemy](1)
+	enemy.position = start
+	enemy.health = 100
+	return enemy
+```
+
+The default heap allocation functions return nullable pointers because C allocation can fail: `alloc_bytes`, `alloc_zeroed_bytes`, `resize_bytes`, `alloc[T]`, `alloc_zeroed[T]`, and `resize[T]` all return `...?`. Code that wants explicit error handling checks for `null`. Code that wants simple fail-fast behavior uses `must_alloc*` or `must_resize*`, which fatal on allocation failure.
+
+Allocator surfaces are semantic, not stylistic. Heap, arena, pool, and stack model different ownership and lifetime stories; the language should not add alias APIs that make them feel interchangeable.
+
+Recommended standard memory surfaces:
+
+- `std.mem.heap` for general allocation and the raw `*_bytes` boundary
+- `std.mem.arena` for frame, level, and scratch lifetimes
+- `std.mem.pool` for fixed-size object pools
+- `std.mem.stack` for explicit temporary allocators
+
+Typed allocation helpers live on the module surface where generic methods are not available yet. For example, `heap.must_alloc[Enemy](1)`, `arena.alloc[Enemy](ref_of(scratch), 4)`, `pool.alloc[Enemy](ref_of(objects))`, and `stack.alloc[Enemy](ref_of(temp), 2)` all stay explicit about allocator choice, while raw byte APIs remain available for lower-level storage work.
+
+### Pointers and references
+
+Pointers are still first-class because game code needs raw memory and FFI. The source model is explicit and uniform.
+
+```mt
+let position_ref = ref_of(player.position)
+let position_ptr = ptr_of(position_ref)
+
+position_ref.x += 1
+
+unsafe:
+	position_ptr.x += 1
+```
+
+Rules for safe references:
+
+- `ref[T]` is a non-null writable safe alias to one live object.
+- `ref_of(expr)` requires a mutable addressable lvalue source and produces `ref[T]`.
+- calling a function that expects `ref[T]` may pass a mutable addressable `T` directly; the compiler borrows it as if `ref_of(expr)` had been written explicitly.
+- `const_ptr_of(expr)` requires an addressable lvalue source and produces `const_ptr[T]` for read-only raw interop.
+- `read(ref_value)` is safe and yields the referenced lvalue/value.
+- `ptr_of(expr)` forms a writable raw pointer from a mutable safe lvalue.
+- `ptr_of(ref_value)` converts an existing safe reference to `ptr[T]` explicitly.
+- member access and method calls auto-project through refs, so `handle.field` and `handle.edit_method()` are the preferred forms.
+- there is no implicit ref-to-value call conversion: if a function expects `T`, pass `read(handle)`.
+- references do not support arithmetic, pointer indexing, or nullable semantics.
+- writable references are non-escaping in the current implementation: they may be used in locals and non-external function parameters, and imported foreign parameters may expose `out` or `inout` boundary forms that lower to raw pointers, but refs themselves still cannot be stored, nested inside other types, returned, or used directly in raw `external` files.
+
+Rules for raw pointers:
+
+- `ptr[T]`, `ptr[T]?`, `const_ptr[T]`, and `const_ptr[T]?` are raw pointer values.
+- there is no source `&expr`, `*ptr`, or `ptr->field`.
+- spell writable address formation as `ref_of(expr)`, read-only raw address formation as `const_ptr_of(expr)`, and writable raw pointer formation as `ptr_of(expr)` when you truly need a raw pointer.
+- `read(ptr)` dereferences a raw pointer and requires `unsafe`.
+- `const_ptr[T]` is the read-only raw-pointer surface and lowers to C `const T*`. `const_ptr[void]` is valid and represents C `const void *`.
+- `ptr.field` and `ptr.method()` access pointee fields and methods through a raw pointer and require `unsafe`.
+- pointer arithmetic and pointer indexing remain `unsafe`.
+- raw pointer offsets and indices may use ordinary integer expressions directly; code does not need a pre-emptive cast to `ptr_uint` just to write `ptr[i]` or `ptr + offset`.
+- pointer comparison is explicit and never treated as boolean truthiness.
+- `ptr[char]` is the ordinary representation for mutable C text and byte-oriented FFI buffers; writing control bytes such as NUL or newline uses `char` values, typically spelled with `char<-0` and `char<-10`.
+- imported foreign declarations may project ABI-identical pointer forms at the boundary. A raw `ptr[void]` parameter may surface as `ptr[T]?` or an opaque handle type when the imported declaration says so. Reinterpretation inside user code still requires an explicit `T<-value` cast and, when dereferenced, `unsafe`.
+
+References are separate from methods:
+
+- plain methods still receive values.
+- `editable methods` use the writable implicit receiver and require an addressable call target.
+- `static function` methods receive nothing.
+- `ref[T]` is for explicit aliasing in APIs, not hidden receiver lowering.
+
+This gives the language clear aliasing tools instead of one overloaded surface:
+
+- `ref[T]` for safe aliasing of one mutable object
+- `own[T]` for owning heap pointers with auto-deref (storable, returnable, nullable)
+- `ptr[T]` / `ptr[T]?` for writable raw memory and FFI
+- `const_ptr[T]` / `const_ptr[T]?` for read-only raw memory and FFI
+- `span[T]` for sized borrowed views over raw pointer data
+
+### Spans
+
+Raw pointers are necessary. Spans are the readable everyday view.
+
+```mt
+span[T] is conceptually:
+	data: ptr[T]
+	len: ptr_uint
+```
+
+`span[T]` should be built into the language surface as a standard view type because it is the right default for arrays, buffers, decoded file content, vertex streams, and audio samples.
+
+`span[T]` is the many-element view. `ref[T]` is the safe writable single-object alias, while `const_ptr[T]` is the raw read-only single-object pointer form.
+
+For frequent pointer-plus-length construction in game code, construct spans directly with `span[T](data = ..., len = ...)`. If a project wants a shorter spelling, it should define a project-local helper instead of assuming a standard helper module.
+
+### Standard library foundation
+
+The standard library follows the same rule as the language: no hidden allocation, no implicit ownership transfer, and no runtime machinery the source did not ask for.
+
+Implemented core modules:
+
+- `Option[T]` and `Result[T, E]` are standard library generic variant types (auto-imported via prelude) for APIs where explicit optional or fallible values are clearer than nullable pointers.
+- `std.string.String` is the normal growable owned UTF-8 text surface. Its public API should mirror the mutable-text shape of `str_buffer[N]`: method-style `len`, `capacity`, `append`, `assign`, `clear`, `as_str`, `to_cstr`, and explicit constructors, not a parallel module-function vocabulary. Byte-level appends exist as low-level escape hatches, but `as_str` and `to_cstr` still enforce valid UTF-8 at the borrowed-text boundary.
+- `std.str` provides borrowed string helpers: UTF-8 validation, byte lookup, prefix/suffix/equality, ASCII trimming, and byte search.
+- `std.fmt` is the explicit formatting subsystem. It should be the single normal formatting engine for owned and fixed-capacity text rather than one option among many formatting styles. `f"..."` produces borrowed `str`; `fmt.format(f"...")` is the explicit owned-text allocation path when you need a `std.string.String`. Low-level append helpers remain implementation building blocks.
+- `std.async` provides the first-party async runtime surface.
+
+### Lifetime story
+
+Milk Tea should make lifetime choices explicit at the API level.
+
+The model:
+
+- stack values for local temporaries
+- arenas for frame and level data
+- pools for stable object storage
+- explicit heap allocation when needed
+- `unsafe` for manual aliasing and lifetime tricks
+
+This is enough to write fast engine and game code without dragging the user through ownership proofs.
+
+## Events
+
+Milk Tea has a built-in typed publisher/subscriber surface with fixed-capacity listener storage. The design follows the same rule as the rest of the language: no hidden allocation, no hidden heap traffic, and the cost of dispatch is visible in the source.
+
+### Why fixed capacity
+
+Event declarations spell their capacity at the declaration site:
+
+```mt
+public event closed[4]
+public event resized[8](ResizeEvent)
+```
+
+This is deliberate. When `emit()` fires, the runtime snapshots all active listener slots into a **stack-allocated array** (`snapshots[capacity]`). That means:
+
+- **Zero heap allocations** during dispatch — critical for real-time, audio, and embedded contexts
+- **Predictable latency** — dispatch time is bounded by capacity, not by an unbounded growable list
+- **No malloc/free churn** when subscribers join or leave frequently
+
+If capacity were dynamic, every `subscribe()` would potentially need `realloc`, and `emit()` would snapshot a heap-allocated list. That is a hidden cost incompatible with the language's rule that allocation must be spelled in source.
+
+The tradeoff is that `subscribe()` can fail with `EventError.full`. This is the same tradeoff as `array[T, N]` (fixed, stack-suitable) versus `Vec[T]` (growable, heap-managed). The right choice depends on the use case:
+
+- **Single-observer UIs** (button click, window close): use a plain function-pointer field on the struct, not an event
+- **Small fixed fan-out** (game state changed, level loaded): capacity 8–32 is typically generous; the stack cost is negligible
+- **Unbounded observers** (logging hooks, inspector tooling): subscribe one dispatcher handler to the event, and maintain a dynamic observer list inside it
+
+### Why emit is module-private
+
+`emit()` is only callable from within the module that declares the event. This is not about visibility — it is about **predictable side effects**. If any module could trigger emission, every subscriber anywhere in the program would become a potential side effect of that emit call. Restricting emission to the declaring module makes the control flow explicit: you can see who fires the event by looking at one file.
+
+Subscribing and unsubscribing from a public event from another module is always allowed. Observing is safe; triggering is the privileged operation.
+
+### Slot lifetime model
+
+The runtime stores listeners in a fixed array of slots, each with:
+
+- an `active` flag
+- a `once` flag (for one-shot subscribers)
+- a `generation` counter (incremented on each new subscription into that slot)
+- a `listener` pointer
+- an optional `state` pointer (for stateful subscribers)
+- an optional `wait_frame` pointer (for async wait)
+
+When `subscribe()` finds a free slot, it increments that slot's generation counter and returns a `Subscription` handle containing both the slot index and the generation. `unsubscribe(sub)` validates both the index and generation before deactivating the slot. This prevents use-after-free: if a slot is reused after an unsubscribe, old subscription handles become stale because their generation no longer matches.
+
+`subscribe_once()` sets the `once` flag; the slot is automatically deactivated after the next emission fires.
+
+### Why no auto-grow
+
+Growth is allocation. Allocation in the hot path (during `subscribe()` or `emit()`) is exactly what the language was designed to avoid. If you need an unbounded listener list, the idiomatic pattern is to build it yourself on top of the primitives — just as you would use `Vec[T]` when `array[T, N]` is too rigid. The event system is the `array[T, N]` of pub/sub: bounded, predictable, allocation-free.
+
+## Error handling
+
+Exceptions do not belong here.
+
+Preferred strategy:
+
+- `Result[T, E]` for recoverable failures
+- `get(arr, i)` for recoverable bounds-checked array/span indexing that returns `ptr[T]?` (null on OOB)
+- `fatal("message")` for programmer errors and impossible states
+- explicit status codes for imported foreign APIs when that matches the C API better
+
+Example:
+
+```mt
+
+
+enum LoadError: ubyte
+	file_not_found = 1
+	invalid_format = 2
+
+function load_level(path: str, arena: ptr[Arena]) -> Result[Level, LoadError]:
+	let json = read_text_file(path, arena)
+	if json == null:
+		return Result[Level, LoadError].failure(error= LoadError.file_not_found)
+
+	return parse_level(json)
+```
+
+No implicit exception paths. Every failure path is visible in the type or the code.
+
+## Modules and packaging
+
+Source files should map directly to modules.
+
+```mt
+import std.raylib as rl
+import game.assets
+```
+
+Rules:
+
+- one module identity per file, derived from its path
+- explicit imports only
+- no wildcard imports in v1
+- no cyclic imports
+- package naming stays filesystem-friendly
+
+Recommended layout:
+
+- `std.*` for core library modules and imported foreign modules
+- `std.c.*` for raw bindgen-generated C modules
+- project modules under their own root namespace
+
+Handwritten wrappers may still exist for real policy or domain logic, but they are not the primary answer to FFI noise. The primary interop story should be raw `std.c.*` modules plus compiler-recognized imported foreign declarations.
+
+## FFI design
+
+FFI is a core feature, not a bolt-on.
+
+Milk Tea needs two interop surfaces, not one:
+
+1. a raw ABI surface for exact bindings
+2. an imported foreign surface for ordinary Milk Tea code
+
+The declaration site carries the boundary contract. Raw pointers, reinterpretation, and manual memory walking remain explicit.
+
+### Raw C bindings
+
+Milk Tea needs a dedicated `external` file form for ABI-exact bindings.
+
+Direct `external function` declarations are also allowed in ordinary modules for small manual ABI bridges, but generated and standard-library bindings should prefer full `external` files so the raw surface stays grouped, auditable, and easy to regenerate.
+
+That dedicated file form is intentional. Raw binding modules carry module-level `include`, `link`, and `compiler_flag` directives and act as the exact ABI layer, while ordinary headerless files remain the normal policy-oriented module form. The distinction is there to keep raw ABI and build-surface concerns grouped instead of smearing them across ordinary modules.
+
+```mt
+external
+
+link "raylib"
+include "raylib.h"
+
+struct Vector2:
+	x: float
+	y: float
+
+struct Color:
+	r: ubyte
+	g: ubyte
+	b: ubyte
+	a: ubyte
+
+external function InitWindow(width: int, height: int, title: cstr) -> void
+external function WindowShouldClose() -> bool
+external function BeginDrawing() -> void
+external function EndDrawing() -> void
+external function DrawCircleV(center: Vector2, radius: float, color: Color) -> void
+```
+
+Capabilities required by the FFI surface:
+
+- exact integer and float widths
+- exact struct field order
+- packed structs and explicit alignment
+- unions
+- opaque handles
+- function pointers and callbacks
+- `cdecl` and future calling convention markers
+- C varargs for APIs like `printf`
+- constant and macro import where clang can resolve the value
+
+### Bindgen
+
+Bindings for libc, libm, raylib, SDL3, Box2D, stb, miniaudio, json-c, and similar libraries should be generated with clang.
+
+Bindgen output rules:
+
+1. Preserve ABI-visible names exactly in raw `std.c.*` modules.
+2. Emit the thinnest possible surface. No runtime marshaling.
+3. Emit opaque types instead of guessing private layouts.
+4. Emit comments or metadata that make the original C header traceable.
+5. Prefer enums, flags, structs, unions, constants, and function declarations over clever wrappers.
+6. When headers are clear enough, emit metadata that can drive generated imported foreign declarations for borrowed strings, transient strings, out parameters, spans, opaque handles, and release functions. If the header is not clear enough, stay raw instead of guessing.
+
+The imported layer may also be generated, but only from an explicit checked-in policy file. clang bindgen is responsible for ABI facts; the policy file is responsible for semantic facts the header does not encode, such as `str as cstr`, `out`, `inout`, `consuming`, span fan-out, selected renames, and which raw declarations should remain exposed only through `std.c.*`.
+
+The raw layer should be inspectable and boring. Handwritten wrappers are optional, but they are not the language's primary ergonomics mechanism.
+
+### Imported foreign declarations
+
+Foreign call ergonomics are implemented directly through `foreign function` declarations with boundary projections (`as`), parameter modes (`in`, `out`, `inout`, `consuming`), and mapping expressions — no separate follow-on proposal document is needed.
+
+Most application code should call imported foreign declarations, not raw `std.c.*` bindings.
+
+Imported foreign modules are ordinary headerless files. They import a raw `std.c.*` module and re-export compiler-recognized `foreign function` declarations.
+
+```mt
+import std.c.raylib as c
+
+public type Vector2 = c.Vector2
+public type Texture = c.Texture
+public type Color = c.Color
+
+public const BLACK: Color = c.BLACK
+public const GOLD: Color = c.GOLD
+
+public foreign function init_window(width: int, height: int, title: str as cstr) -> void = c.InitWindow
+public foreign function close_window() -> void = c.CloseWindow
+public foreign function window_should_close() -> bool = c.WindowShouldClose
+public foreign function get_frame_time() -> float = c.GetFrameTime
+
+public foreign function load_texture(path: str as cstr) -> Texture = c.LoadTexture
+public foreign function load_file_data(file_name: str as cstr, out data_size: int) -> ptr[ubyte]? = c.LoadFileData
+public foreign function save_file_data(file_name: str as cstr, data: span[ubyte]) -> bool = c.SaveFileData(file_name, data.data, int<-data.len)
+public foreign function set_shader_value[T](shader: Shader, loc_index: int, in value: T as const_ptr[void], uniform_type: int) -> void = c.SetShaderValue
+
+public foreign function mem_alloc[T](count: ptr_uint) -> ptr[T]? = c.MemAlloc(count * uint<-size_of(T))
+public foreign function mem_realloc[T](memory: ptr[T]?, count: ptr_uint) -> ptr[T]? = c.MemRealloc(memory, count * uint<-size_of(T))
+public foreign function mem_free[T](memory: ptr[T]?) -> void = c.MemFree(memory)
+```
+
+Types, enums, flags, and constants that need no boundary conversion should usually be re-exported with ordinary `public type`, `public const`, `enum`, or `flags` declarations. `foreign function` is for call boundaries, not for everything else in the module.
+
+These declarations are not handwritten wrappers:
+
+- one imported declaration maps directly to one foreign symbol
+- there is no extra function body, hidden dispatch, or policy object
+- lowering stays inspectable in generated C
+- boundary conversions are declared once on the import instead of repeated at every call site
+
+Chosen v1 form:
+
+- `foreign function` is a new declaration kind allowed in ordinary modules
+- the left side is the public Milk Tea signature
+- the right side is either a raw symbol name or a declarative raw call expression
+- `= c.Symbol` is shorthand for positional lowering when surface parameters map directly to the raw ABI after boundary conversion
+- `= c.Symbol(...)` is required when one surface parameter fans out into multiple raw arguments, when argument order changes, or when the raw API needs size arithmetic such as `count * size_of(T)`
+
+The right side is deliberately not a normal function body. It is a restricted lowering clause. It may use:
+
+- the referenced raw foreign symbol
+- imported parameters
+- field access such as `data.data` and `data.len`
+- `T<-expr`, `size_of`, `align_of`, literals, `null`, and simple arithmetic
+
+It may not use:
+
+- control flow
+- local declarations
+- arbitrary function calls
+- heap allocation
+- `unsafe` blocks
+
+An imported foreign declaration must be able to express at least:
+
+- a `str` parameter that lowers to `cstr` at the foreign boundary
+- ordinary `span[str]` or `array[str, N]` inputs for foreign string-list APIs
+- automatic transient boundary marshalling for dynamic text when the imported declaration chooses that public surface
+- `in`, `out`, and `inout` parameters that lower to raw pointers
+- release-style functions that consume a handle and null the caller binding afterward
+- pointer-plus-length views that lower from `span[T]`
+- identity ABI projections such as `ptr[T]?` to `ptr[void]` or `cstr?` to `ptr[char]?`
+
+Parameter and boundary rules:
+
+- `name: str as cstr` means the public Milk Tea type is `str`, while the raw foreign target expects `cstr` or `ptr[char]`
+- imported foreign declarations do not spell this surface as `str as ptr[char]`; the public text boundary stays `str as cstr` even when the raw callee argument type is `ptr[char]`
+- a string literal or existing `cstr` value may satisfy `str as cstr` without temporary storage
+- a dynamic `str` argument for `str as cstr` is materialized automatically at the foreign boundary for the duration of the call
+- imported foreign declarations may accept `span[str]` or `array[str, N]` for string-list APIs even when the raw callee wants `span[cstr]`, `span[ptr[char]]`, or pointer-plus-length forms; that marshalling belongs to the declaration, not to the call site
+- `in name: T` means the raw foreign target takes a read-only pointer; call sites pass an ordinary expression and the boundary lowers by taking a const address, materializing a temporary first when the expression is not directly addressable
+- `out name: T` means the raw foreign target takes a writable pointer; call sites pass an ordinary mutable addressable lvalue
+- `inout name: T` means the raw foreign target reads and writes through a pointer; call sites pass an ordinary mutable addressable lvalue
+- `consuming name: Handle` means the public Milk Tea parameter is a non-null opaque handle or `ptr[T]`, and v1 uses it only for release-style foreign calls that consume an existing nullable binding
+- plain parameters and return values require exact compatibility or an explicitly permitted identity ABI projection
+
+#### Sema rules for foreign defs
+
+The checker should treat `foreign function` as its own declaration kind with dedicated rules.
+
+Declaration rules:
+
+- `foreign function` is allowed only in ordinary modules, not inside `external`, `extending` blocks, or function bodies
+- the right-hand side must resolve to an imported raw external symbol from a `std.c.*` module
+- `= c.Symbol` is shorthand symbol mapping; `c.Symbol` must resolve to an imported `external function`
+- `= c.Symbol(...)` is declarative RHS mapping; the callee must resolve to an imported `external function`
+- the right-hand side may reference only declaration parameters and imported raw symbols from the module scope
+- a `consuming` parameter may not use `as`, must have a non-null `opaque Handle` or `ptr[T]` type, and any `foreign function` that has a `consuming` parameter must return `void`
+
+Shorthand symbol mapping rules:
+
+- the public parameter count must match the raw parameter count, excluding raw varargs
+- parameters map positionally in source order
+- each mapped pair must satisfy one of: exact type match, declared boundary mapping such as `str as cstr`, directional pointer mapping through `out` or `inout`, or an allowed identity ABI projection
+- an `in` parameter may use `as const_ptr[...]`, including `as const_ptr[void]`, to express read-only foreign borrows such as Raylib shader uniform values
+- aliasing a public imported-binding type to a different raw module type does not create a new identity ABI projection. Two raw structs from different `std.c.*` modules remain distinct unless the language grows an explicit foreign type-projection rule for that pair.
+- the public return type must either exactly match the raw return type or be reachable through an allowed identity ABI projection
+- shorthand mapping is rejected if any surface parameter must fan out into multiple raw arguments, if any raw argument needs arithmetic over more than one parameter, or if raw argument order differs from public argument order
+
+Declarative RHS mapping rules:
+
+- the RHS must be a raw call expression whose callee is an imported raw external function
+- raw call arity must match the raw target signature, respecting raw varargs rules
+- the checker analyzes each raw argument expression in an environment containing the public parameters
+- allowed RHS expression forms are: parameter identifiers, member access, index access, literals, `null`, `size_of`, `align_of`, `offset_of`, explicit `T<-expr` casts, and simple arithmetic or comparisons built from those forms
+- disallowed RHS forms are: control flow, local declarations, assignment, `unsafe`, `defer`, heap allocation, and arbitrary non-builtin function calls
+- every public parameter must be consumed by the RHS according to its mode
+
+Parameter consumption rules:
+
+- a plain parameter may be referenced one or more times in the RHS
+- a `span[T]` parameter may be split into `.data` and `.len`
+- an `out` parameter must appear exactly once as a bare parameter reference in the raw argument position that receives the writable pointer
+- an `in` parameter must appear exactly once as a bare parameter reference in the raw argument position that receives the read-only pointer
+- an `inout` parameter must appear exactly once as a bare parameter reference in the raw argument position that receives the mutable pointer
+- a `consuming` parameter lowers through the same identity value as a plain handle parameter; v1 ownership affects call-site validation and post-call flow, not the RHS mapping expression shape
+- a `str as cstr` parameter may appear only in raw argument positions whose target type is `cstr` or `ptr[char]`
+
+Call-site checking rules:
+
+- a call to a `foreign function` with `out` parameters requires an ordinary mutable addressable lvalue at the corresponding argument position
+- a call to a `foreign function` with `in` parameters accepts an ordinary expression at the corresponding argument position
+- a call to a `foreign function` with `inout` parameters requires an ordinary mutable addressable lvalue at the corresponding argument position
+- a call to a `foreign function` with `consuming` parameters requires a bare identifier naming a nullable local or parameter binding
+- the current flow type of that binding must already be the non-null handle type required by the `consuming` parameter
+- in v1, a foreign call with any `consuming` parameter must be a top-level expression statement; `defer`, local initializers, assignments, returns, and larger expressions are rejected
+- after a `consuming` foreign call, continuation flow refines each consumed binding to `null`
+- legacy call-site markers such as `in expr`, `out lvalue`, and `inout lvalue` are rejected semantically; boundary directionality lives on the imported declaration
+- `in` parameters accept ordinary expressions; if an expression is not addressable, lowering creates a short-lived temporary before taking its const address
+- `out` parameters require a mutable addressable lvalue and do not read the old value before the call
+- `inout` parameters require a mutable addressable lvalue and expose both the old and new value to the callee
+- automatic foreign text marshalling is part of imported-boundary checking, not an extra source clause
+- string literals and existing `cstr` values lower directly where possible, so the compiler only materializes temporary storage when the public argument actually needs it
+
+Allowed identity ABI projections in v1 are deliberately narrow:
+
+- `ptr[T]` or `ptr[T]?` to `ptr[void]` or `ptr[void]?`
+- `ptr[T]` or `ptr[T]?` to `const_ptr[void]` or `const_ptr[void]?` for read-only foreign pointer projections
+- `ptr[void]` or `ptr[void]?` to `opaque Handle` or `opaque Handle?` when the imported declaration chooses that handle surface
+- `ptr[char]` or `ptr[char]?` to `cstr` or `ptr[char]?` when mutability rules permit the raw direction
+- raw opaque pointer returns to typed pointer-like public returns when the representation is unchanged
+
+Anything outside those cases requires the raw layer or an explicit later language feature. `foreign function` is not a general coercion system.
+
+#### Lowering rules for foreign calls
+
+`foreign function` lowers directly to the referenced raw call boundary. It does not lower as a normal Milk Tea function body.
+
+Shorthand symbol mapping lowering:
+
+- the call target is the referenced raw symbol
+- arguments are lowered left-to-right in public parameter order
+- each public argument lowers through its declared boundary rule and then into the matching raw parameter slot
+- if the return type needs an allowed identity ABI projection, the backend emits the minimal explicit C cast required by the target types
+
+Declarative RHS mapping lowering:
+
+- the lowering clause is expanded by substituting lowered public arguments into the restricted RHS expression tree
+- the expanded raw call becomes the emitted call target and raw argument list
+- field access such as `data.data` and `data.len` lowers exactly as the corresponding member access on the public argument value
+- builtin forms such as `T<-expr`, `size_of`, `align_of`, and `offset_of` lower exactly as they do elsewhere in the language
+
+Automatic text marshalling lowering:
+
+- if a public foreign boundary uses `str`, `span[str]`, or `array[str, N]` and the raw callee needs C-compatible text storage, the compiler materializes that storage automatically for the duration of the call
+- materialization happens in left-to-right argument order so evaluation stays inspectable
+- literal-backed and already-compatible arguments lower directly with no temporary storage
+- dynamic `str` values lower to temporary NUL-terminated C strings when needed
+- string lists lower to temporary C-string arrays or pointer-plus-length views when needed
+- the temporary storage is released immediately after the raw call completes
+- if code needs exact storage control or wants to avoid boundary marshalling entirely, it may call the raw `std.c.*` layer or pass already-compatible `cstr` / `span[char]` values directly
+
+Directional pointer lowering:
+
+- an `out` parameter lowers its call-site lvalue by taking its address at the raw call boundary without exposing `ptr_of(...)` in user source
+- an `in` parameter lowers its call-site argument by taking a const address at the raw call boundary without exposing `const_ptr_of(...)` or casts in user source; non-addressable operands lower through a visible temporary in statement-shaped foreign calls
+- an `inout` parameter lowers the same way as `out`, but sema preserves the read-write contract instead of pure output
+- if the raw target expects `ptr[void]` or another identity-projection pointer type, lowering inserts only the minimal cast required by the raw C signature
+
+Release-function ownership lowering:
+
+- a `consuming` argument lowers through the same raw boundary value as the corresponding plain handle argument
+- immediately after the raw foreign call completes, lowering emits `binding = null` for each consumed binding
+- the same statement updates continuation flow so later code sees that binding as `null`
+- v1 does not add a general move checker; this null-after-call rule is limited to bare nullable local or parameter bindings in top-level expression statements
+
+Generated C quality rule:
+
+- lowering may introduce short-lived temporaries for foreign text marshalling, result spilling, or identity casts
+- lowering should not emit an extra helper function for each `foreign function` in the ordinary case
+- the preferred output is one visible raw call site whose surrounding temporaries make the boundary work obvious in C
+
+Call sites should read like this:
+
+```mt
+rl.init_window(screen_width, screen_height, "Milk Tea")
+let texture = rl.load_texture(path)
+let file_data = rl.load_file_data("storage.data", data_size)
+let success = rl.save_file_data("storage.data", bytes)
+let ints = rl.mem_alloc[int](16)
+```
+
+`str as cstr` and `span[str]` foreign boundaries use ordinary imported-call syntax. When the boundary needs synthesized temporary C-compatible storage or other statement-shaped setup, lowering hoists that work into visible temporary locals and branch-local control flow as needed, so nested call arguments, arithmetic, `if ...: ... else: ...` expressions, and short-circuit boolean expressions still read like ordinary Milk Tea while generated C stays explicit about the temporary storage.
+
+`in`, `out`, and `inout` are declaration-side foreign-boundary forms, not imported-call expressions. They control how ordinary call-site arguments lower at the boundary without exposing `const_ptr_of(...)`, `ptr_of(...)`, or ABI casts in ordinary code.
+
+This boundary rule is deliberate: declarations say how the boundary works, while raw pointer code remains explicitly low-level.
+
+### Strings and buffers at the FFI boundary
+
+String and buffer rules must stay explicit, but the explicitness belongs in imported declarations, not in every call site:
+
+- raw `external` files stay exact and continue to use `cstr`, `ptr[T]`, and `ptr[void]`
+- a string literal may satisfy a contextual `cstr` position directly; ordinary UI code should not need `c"..."` just to populate `cstr` locals, `array[cstr, N]`, or borrowed C-string arguments
+- converting a dynamic `str` or `span[str]` to foreign C-compatible text is automatic when an imported declaration chooses that public surface
+- `cstr` remains available for raw ABI work, returned native strings, and low-level code
+- pointer-plus-length APIs should import as `span[T]` when the native contract is a view rather than untyped memory
+- single-object output parameters should import as `out T` or `inout T` instead of naked pointer syntax
+- `ptr[void]` should stay in the raw layer, but imported declarations may project it to typed pointers or opaque handles when the ABI conversion is identity-only
+
+This keeps the important distinction intact:
+
+- source code thinks in `str`, `array[str, N]`, `span[str]`, and one mutable text buffer type
+- raw memory work still requires raw syntax
+- call sites stop spelling C representation details that the import declaration already knows
+
+### Callbacks
+
+Callbacks must map directly to C function pointers.
+
+```mt
+type LogCallback = fn(level: int, message: cstr, user_data: ptr[void]) -> void
+```
+
+Capturing closures should not be lowered to hidden heap objects. If user state is needed, pass it explicitly as `user_data` at ABI boundaries or allocate explicit local storage such as `std.cell.alloc[T](...)` in ordinary Milk Tea code.
+
+## Data layout and ABI controls
+
+The language must expose a small set of layout controls for interop and SIMD-friendly code.
+
+```mt
+@[packed]
+struct FileHeader:
+	magic: array[ubyte, 4]
+	version: ushort
+
+@[align(16)]
+struct Mat4:
+	m: array[float, 16]
+```
+
+Required controls:
+
+- `@[packed]`
+- `@[align(n)]`
+- `attribute[target, ...]`
+- `size_of(T)`
+- `align_of(T)`
+- `offset_of(T, field)`
+- `static_assert(condition, message)`
+
+These are not niche. They are mandatory for FFI and engine code.
+
+## Generated C quality bar
+
+Milk Tea only succeeds if the generated C is respectable.
+
+### Generated C requirements
+
+1. Keep one obvious symbol mapping from source to C.
+2. Preserve source names as much as the C target allows.
+3. Emit straightforward local variables and control flow.
+4. Lower methods to plain functions.
+5. Lower `match` to `switch` where possible.
+6. Lower `defer` to readable cleanup labels or scoped cleanup blocks.
+7. Avoid a mandatory runtime beyond what is needed for startup, fatal hooks, and core helper intrinsics.
+
+Example lowering:
+
+Milk Tea:
+
+```mt
+struct Player:
+	position: Vec2
+	velocity: Vec2
+
+extending Player:
+	editable function update(dt: float):
+		this.position.x += this.velocity.x * dt
+		this.position.y += this.velocity.y * dt
+```
+
+Target C:
+
+```c
+typedef struct game_Vec2 {
+	float x;
+	float y;
+} game_Vec2;
+
+typedef struct game_Player {
+	game_Vec2 position;
+	game_Vec2 velocity;
+} game_Player;
+
+static void game_Player_update(game_Player* this, float dt) {
+	this->position.x += this->velocity.x * dt;
+	this->position.y += this->velocity.y * dt;
+}
+```
+
+This is the standard to protect. If the generated C becomes harder to read than hand-written C, the language has drifted.
+
+## Summary
+
+Milk Tea should be a language where:
+
+- the syntax is calm and readable
+- the type system is explicit but not academic
+- the memory model is fast and honest
+- pointers are available without shame
+- C libraries fit naturally
+- the generated C remains clean enough to trust
+
+That combination is the point. The language should feel like a direct place to write systems and game code without being pushed into a second abstraction model just to stay productive.