# Mini Language Spec v1

This is the compact v1 overview. The split specifications in [spec/](./spec) are the detailed references; this file exists to show the whole language shape without duplicating every rule.

## Goals

Muga v1 prioritizes:

- simple local reading
- low syntactic overhead
- static typing with minimal annotations
- fast compiler architecture
- predictable package boundaries

The language is compiler-first. The current VM is a reference execution backend, not a separate semantics engine.

## V1 Completion Boundary

The v1 surface syntax is considered closed around the grammar defined in this overview and the detailed specs. Finishing v1 means implementing and documenting that closed surface, keeping runnable samples and rejection tests aligned with it, and preserving the explicit package artifact workflow.

The v1 grammar includes:

- script files with top-level statements
- package files with `package`, `import`, `pub`, `pkg`, and `as`
- immutable and mutable bindings with optional local type annotations
- `record`, `enum`, `fn`, and anonymous `fn`
- `if`, `while`, final-expression value blocks, and exhaustive `match`
- ordinary calls, chained calls, package-qualified chained calls, field access, record update, list literals, and list indexing
- prefix `try expr` for `Result[T, E]`
- explicit declaration type parameters on records, enums, and functions
- generic type expressions in annotations and signatures

The following are explicitly not v1 completion blockers:

- `class`, inheritance, traits, protocols, typeclasses, overloaded dispatch, or operator overloading
- source-level references such as `ref T`, `mut ref T`, `&value`, `*value`, or pointer syntax
- postfix `?`, `T?`, implicit exceptions, or `throws`
- explicit call-site type arguments such as `id[Int](1)`
- wildcard imports, selective imports, re-export syntax, or package top-level execution
- wildcard match arms, nested patterns, match guards, multi-payload enum variants, or named-field enum variants
- map literals, `Set[T]`, arbitrary `Map` key types, broad collection APIs, `for`, `break`, or `continue`
- concurrency syntax such as `group`, `spawn`, `join`, channels, `async`, or `await`
- `String.len()`, substring/slice indexing, and richer parse error types until their semantics are explicitly chosen

## Core Rules

Bindings are immutable by default:

```muga
x = 1
mut total = 0
total = total + 1
```

`x = e` is one syntactic form. Name resolution decides whether it introduces a new immutable binding or updates an existing mutable binding in the current function scope.

Rules:

- no `let`
- `mut x = e` introduces a new mutable binding
- `x = e` introduces an immutable binding when `x` is not already defined in the current scope
- `x = e` updates `x` when `x` resolves to a mutable binding in the same function
- updating an immutable binding is an error
- shadowing is prohibited
- nested blocks in the same function may update enclosing mutable bindings
- inner functions may read outer bindings but may not update them

## Syntax

Comments use `//`. Statements are separated by newlines.

Core expression and statement forms include:

- integer, boolean, and string literals
- `if` statements and value-producing `if` expressions
- `while` statements
- function declarations and anonymous functions
- record declarations, record literals, field access, and non-destructive record update
- ordinary calls and chained calls
- list literals and list indexing
- exhaustive `match` for compiler-known `Option[T]`, `Result[T, E]`, and user-defined enums
- `try expr` propagation for `Result[T, E]`
- package declarations and imports in package mode

Type annotations use `:`:

```muga
value: Int = 1
mut items: List[Int] = []
fn add(a: Int, b: Int): Int {
  a + b
}
```

Function types use `->`:

```muga
fn apply(value: Int, f: Int -> Int): Int {
  f(value)
}
```

Generic type expressions use square brackets:

```muga
List[Int]
Option[String]
Result[Int, String]
Map[String, Int]
```

The implementation supports generic type expressions for `List`, `Option`, `Result`, and `Map`, plus explicit user-defined generic records and functions.

## Functions And Inference

Type annotations should be omitted when local inference can determine a unique type:

```muga
fn double(x) {
  x * 2
}
```

Annotations remain required when inference is ambiguous, recursive constraints need a stable starting point, or the current implementation has an explicit boundary such as public package signatures.

Function bodies produce their final expression. `return` is not required in v1.

Higher-order functions are supported:

```muga
fn apply(x: Int, f): Int {
  f(x)
}

fn main(): Int {
  apply(10, fn(n) {
    n + 1
  })
}
```

Local bidirectional inference covers selected higher-order cases. When a callback type cannot be inferred uniquely, write the function type.

## Records And Calls

Records are nominal data declarations:

```muga
record User {
  name: String
  age: Int
}
```

Record literals use the record name:

```muga
user = User {
  name: "Ada"
  age: 20
}
```

Field access and update:

```muga
name = user.name
older = user.with(age: user.age + 1)
```

Behavior is modeled with functions. Chained calls are surface syntax over function calls:

```muga
fn birthday(user: User): User {
  user.with(age: user.age + 1)
}

older = user.birthday()
```

`self` is only a conventional parameter name. v1 has no classes, inheritance, receiver overloading, or function-valued record fields.

## Collections And Enum-Like Standard Types

Implemented collection/error core:

- `List[T]`
- `Option[T]`
- `Result[T, E]`
- `Map[K, V]` for `Int`, `Bool`, and `String` keys

Examples:

```muga
numbers = [1, 2, 3]
first = numbers.get(0)

match first {
  Option::Some(value) => value
  Option::None => 0
}
```

```muga
result: Result[Int, String] = Result::Ok(1)

match result {
  Result::Ok(value) => value
  Result::Err(message) => 0
}
```

`Option[T]` is the canonical optional spelling. `T?` is reserved as possible future shorthand. `Result[T, E]` is explicit; prefix `try expr` propagates `Result` errors, while postfix `?` is not part of v1.

User-defined enum declarations are implemented with optional unconstrained type parameters, zero-payload and one-payload variants, qualified constructors/patterns, and exhaustive `match`.

## Packages

Script mode is for standalone files. Package mode starts with `package` or is inferred from a nearby `muga.toml`.

```muga
package app::main

import util::numbers

fn main(): Int {
  1.numbers::inc_twice()
}
```

Package-mode visibility:

- unmodified top-level items are module/file-private
- `pkg` items are visible to sibling files in the same package
- `pub` items are importable from other packages

Package interfaces and implementation artifacts are explicit v1 workflow artifacts:

- `.mgi` stores public package interfaces
- `.mgc` stores package check-cache proofs
- `.mgb` stores MIR-lowered bytecode implementation artifacts

`muga check --artifact-root` and `muga run --artifact-root` consume those artifacts without reading dependency implementation bodies. Normal package execution without `--artifact-root` remains source-compatible and may still read dependency source bodies.

## Value Semantics

Ordinary source code uses value semantics. APIs that update ordinary data should return new values, as `List.push`, `List.set`, `Map.insert`, `Map.remove`, and `record.with(...)` do.

The implementation may optimize with internal sharing, copy elision, builders, buffers, resource handles, MIR lowering, or native backend work. These optimizations must not change source-level meaning.

Explicit source-level references such as `ref T`, `mut ref T`, `&value`, `*value`, and raw pointer syntax are not planned for ordinary Muga code.

## Current Implementation Boundary

Implemented:

- parser/resolver/typechecker/HIR/bytecode/VM pipeline
- typed HIR and MIR-lowered bytecode for the reference VM
- records, enums, functions, local inference, closures, higher-order functions, and explicit generic records/functions
- exhaustive `match` for `Option[T]`, `Result[T, E]`, and user-defined enums
- prefix `try expr` propagation for `Result[T, E]`
- packages, module privacy, `pkg`, `pub`, import aliases, package-aware checking, and minimal manifest project mode
- `List`, `Option`, `Result`, `Map`, and the current `String` helper slice
- persisted `.mgi` package interfaces, `.mgc` check-cache artifacts, and `.mgb` implementation artifacts
- artifact-backed `check` and `run` without dependency implementation source fallback

Not implemented:

- public-signature inference for `pub fn`
- dependency declarations, registries, and lockfiles
- project-mode artifact-root configuration and full incremental package artifact reuse
- map literals, `Set[T]`, arbitrary `Map` key types, and broad collection APIs
- control-flow-oriented MIR and native backend
- structured concurrency

## Detailed References

- [spec/001-core-language.md](./spec/001-core-language.md)
- [spec/002-name-resolution.md](./spec/002-name-resolution.md)
- [spec/003-typing.md](./spec/003-typing.md)
- [spec/004-functions.md](./spec/004-functions.md)
- [spec/005-records.md](./spec/005-records.md)
- [spec/006-packages.md](./spec/006-packages.md)
- [spec/008-collections.md](./spec/008-collections.md)
- [spec/009-generics.md](./spec/009-generics.md)
- [spec/010-references-draft.md](./spec/010-references-draft.md)
- [spec/011-value-semantics.md](./spec/011-value-semantics.md)
- [spec/012-protocols-deferred.md](./spec/012-protocols-deferred.md)
- [spec/013-enums-results.md](./spec/013-enums-results.md)
