Dawn Language Specification

Status: normative. Applies to version: 0.90.0 (the VERSION in selfhost/src/version.dawn). When the implementation conflicts with this document, this document wins and the implementation is a bug — unless some clause here is explicitly marked "superseded by X".

The title read "v0.1 draft" for a long time; by the day that was changed the toolchain had already reached 0.11. A document that calls itself a draft cannot act as a judge, and this is the only document in the repository qualified to judge disputes about semantics. The version number follows VERSION; it is no longer numbered separately.

This document is the authoritative definition of the syntax and semantics. For design motivation see design.en.md. The repository keeps no separate formal grammar file: when the grammar is in dispute, this document and selfhost/src/front/parser.dawn win; the executable expectations live in scripts/grammar-corpus/.

Wording of this specification: must (violating it is a compile error), guaranteed (behaviour the implementation promises), undefined (not promised by this specification; do not rely on it).

1.Source files and lexical structure

1.1Source files

1.2Comments

# Line comment, to end of line
## Doc comment, attached to the declaration that immediately follows (extracted by the toolchain)

There are no block comments. The only comment is the one that starts with # and runs to the end of the line; to comment out a stretch of code, put # on each line. /* is a lexical error (Dawn has no block comments; use `#` on each line), reported at the /*; the text after it up to */ (or to the end of the file if there is none) is skipped as a whole, so it raises nothing further. Rationale: Dawn's line structure carries meaning (§1.7: a newline separates statements, and the line's last token decides whether it continues), and interpolation is single-line (§1.6). Without block comments every line can be tokenized on its own, "what is the last token of this line" never depends on earlier text, and dawn fmt needs no indentation rule for comments that span lines. Gleam and Zig likewise have only line comments.

Doc comments. A whole-line comment that starts with ## is a doc comment (so is ###; the third # belongs to the text); a comment that starts with a single # means nothing to the toolchain.

Rationale: a doc comment is still a comment. Whether a comment is a doc depends only on its own line (does it start with ##, is there code before it), so, as above, every line can be tokenized on its own and dawn fmt needs no rule of its own for it; attachment is decided by the single line rule "contiguous, right above", with no extra node in the syntax tree. If a trailing ## counted too, the next line's declaration would claim it, though it speaks about the code on its own line. Rust's, Zig's and Gleam's /// all have this same shape. The link notation is Rust's and KDoc's [`name`]: in CommonMark it is an undefined reference and renders literally, so a renderer that does not know it still reads it. Names in backticks are not all taken as links: most of what this repository writes in backticks is code, and which of it counted as a link would be impossible to predict. Resolution lives in the tooling, not the compiler: comments carry no meaning, and dawn run should neither refuse to compile over a typo in a comment nor pay for reading one.

1.3Identifiers and naming conventions

The enforced part — the first character decides the syntactic category, and the parser uses it to disambiguate (in pattern matching x is a binding and X is a constructor; TYPEIDENT is a separate token):

Style conventions — not enforced by the toolchain, but followed throughout the repository: values use lower_snake_case ([a-z][a-z0-9_]*), types use UpperCamelCase ([A-Z][A-Za-z0-9]*).

On non-ASCII: "uppercase / lowercase" is decided by Java's Character.isUpperCase, and subsequent characters by Character.isLetterOrDigit or _. So fn 中文() and fn _hidden() both compile — a Han character is neither uppercase nor lowercase, so it takes the "not uppercase" branch, i.e. it is a value identifier.

This is implementation-defined, not designed: Unicode's XID_Start/XID_Continue, normalization (whether the two spellings of é count as the same name), and homoglyphs are all undefined by this specification, and code that depends on them is not portable. Scripts without case (Han, Arabic, kana) can therefore only be value names; there is no natural way to write them as type names. Converging on a well-defined Unicode identifier syntax is open work (SYN-01 in docs/codebase-audit.md).

1.4Keywords

fn let var type alias const use pub
match if else for while
return break continue
comptime
trait impl effect
true false not

Keywords cannot be used as identifiers. panic and todo are built-in functions, not keywords. There are twelve further contextual keywords. Each has a special meaning in exactly one syntactic position and remains an ordinary identifier everywhere else (let in = 1 and a field named test are both legal):

WordIts one syntactic position
javause java "a.B": after use, followed by a class-name string (§9.1)
testat the head of a top-level declaration: test "name" { … } (§3.4)
assertat the start of a statement, followed by an expression (§3.4); in assert = 1 and assert.x it is a name
withat the start of a statement, followed by a name or <- (§4.10)
inin a for header, after the pattern (§4.7)
deriveat the tail of a type declaration (§3.5)
asin the renaming position of use (§10.2)
handleafter with, when the next token is not <- (§6.5)
opaquedirectly before type, introducing an opaque type (§2.7)
ctldirectly before effect, declaring a suspendable effect (§6.5)
resumeafter a handler arm's parameter list: op(a) resume k => … (§6.5)
pkgonly after pub(: pub(pkg) (§10.4)

The statement-start tests are "what a plain name could never legally be followed by": a name directly followed by an expression or by another name is never a legal program, so giving those sequences to the keyword takes no legal spelling away. The one cost is that a function named assert cannot be called as assert(x) at the start of a statement (that is an assertion).

Both lists are reconciled by machine: the hard keywords are the keyword table in selfhost/src/front/token.dawn, and the contextual keywords are the is_word(…, "<word>") sites in selfhost/src/front/parser.dawn. scripts/doc-check.py and the editor grammar's contract test (editors/vscode/test/scope-contract.js) both read those two places, so a word missing from this section or from the grammar file is red.

Symbol tokens take the longest match (as with >>>/>=/->/|>). The binding arrow <- of the with statement (§4.10) follows the same rule: a<-b reads as a <- b, not a < (-b). The spaced a < -b is unaffected, and dawn fmt puts a space on both sides of every binary operator (§1.8), so formatted source never reaches the second reading.

1.5Literals

FormTypeNotes
42, 1_000_000, 0xFF, 0b1010Int when nothing is expected64-bit signed; underscores may be used as separators; typed by its expectation (below)
3.14, 1.0e-9Float when nothing is expectedIEEE 754 double; typed by its expectation (below)
true / falseBool
"hello"Stringsee §1.6
()Unitthe only value
[1, 2, 3]List[Int]trailing comma allowed; separators and element forms in §4.11
(1, "a")(Int, String)tuple, 2 to 8 elements
'a', '\n', '世', '\u{1F600}'Charcharacter literal (see below)

The non-negative magnitude of an integer token must normally be in 0..9223372036854775807. The sole exception is exactly 2^63, and only when it is the direct operand of unary -: decimal -9223372036854775808, hexadecimal -0x8000000000000000, and the corresponding 64-bit binary spelling all denote the minimum Int. Expressions and literal patterns use the same rule. Parentheses around the whole negative value remain valid ((-9223372036854775808)), but parentheses separating the magnitude from the minus do not (-(9223372036854775808)), nor does bare 2^63. A magnitude greater than 2^63 is a range error; a digit forbidden by its radix (such as 0b2) is an invalid literal rather than a range error.

A numeric literal has no type of its own; its expected type types it (since 2026-10-06, literal-system-design.md). A literal atom is an integer literal, a float literal, or either one directly after a unary -. When it is checked with an expected type T:

When the impl is pure, the compiler computes the literal's value at compile time (the same interpreter as comptime, §7), and a panic in the impl is a compile error pointing at the literal: the range of U8 is written in its FromInt impl, which is why let b: U8 = 300 does not compile although the compiler does not know 255. When the impl has an effect, the literal is a call at run time and the effect is charged to the enclosing signature (§6); such a literal cannot appear in a const or a comptime block. Typing a literal never feeds back into the type of anything else: there are no inference variables and no defaulting rules. How the expectation reaches a literal: for a binary operator see §4.3 (the literal yields to the typed side); among the arguments of a generic call, a literal whose parameter still names an unsettled type parameter is checked after the other arguments have typed themselves and before those that need an expectation, a float literal before an integer literal on the same type parameter (g(1, 2.5) has T = Float, and in g(s, 1) the 1 takes the type of s). Literals in patterns are not part of this and follow §5.1 as before.

A character is its own type, Char: one Unicode scalar value (0..0x10FFFF, excluding the surrogate range D800..DFFF). It is an opaque type (§2.7) over Int whose owner is std/char — the representation is the code point, so it is zero-cost, and ==, <, hashing and literal patterns in match all reuse the Int ones. The rendering comes in two layers (§4.3), and std/char writes one for each: impl Display[Char] is the top level, so to_string(c) and "${c}" give the character, while impl Show[Char] is the nested one, so a Char inside a structure ([c], a record field, a tuple) renders as the source literal 'a', escaped with the set above, the way a nested String renders as "a". str.from_char(c) asks for that top-level one-character string by name, without depending on an impl. But it is not an Int: 'a' + 1 does not hold, and converting between the two goes through std/char — char.code(c) -> Int takes the code point, char.of(n) -> Option[Char] builds a character from a code point (None if it is not a scalar value). Inside single quotes is a single code point: the escapes are the same as in strings (\n \t \r \\ \u{...}) plus \'; an empty literal, more than one code point, or a \u{...} that is not a scalar value → lexical error. For the functions that handle strings by code point see §11 (code_points -> List[Char]/from_code_points/len/str.slice/str.at). Note: the runtime storage is java.lang.String (indexed by UTF-16 code units), so "random access by code point index" needs an O(n) conversion — for the measurements and the design trade-off see the appendix of `seq6-research.md`. For character-by-character traversal use the cursor of §11 (std/cursor), whose cost per step is constant; the indexed version is for one-off calls.

cursor.char is the exception: it returns Int, not Char. At the end it answers -1 (a named exception in §4.8), and a sentinel that is not a code point cannot live in a type where every value is a code point. The Char surface is str.at, str.chars and code_points; cursor.char is the primitive underneath them.

History: up to and including v0.56.0, 'a' was an Int (Go's rune route). The type name Char landed in v0.54.0 and the std/char module in v0.56.0, each one release early and as a transparent spelling of Int, purely to satisfy the seed discipline (docs/bootstrap.md): the compiler that compiles the release doing the flip must already know that name and that module. The flip was done in one go in v0.57.0. For the phasing, the measurements and the several routes that were rejected see `audit/nominal-types-design.md` §7.

1.6Strings and interpolation

Double-quoted strings, with the escapes \n \t \r \\ \" \$ and Unicode \u{1F600}. Braces { } are ordinary characters and need no escaping — convenient for writing JSON, CSS and code generation.

Interpolation has one spelling: ${expr} inserts an arbitrary expression (a name is written ${name} too). The interpolated type must have a Show witness — the built-in scalars, user types that write impl Show or derive Show, and containers and tuples whose elements are renderable (see §4.3):

let n = 3
println("got ${n} items, first = ${list.get(0)}")

A $ directly followed by a character that can start a name (a letter or _) is a lexical error; the diagnostic names both repairs, ${name} to interpolate or \$name for the literal. A $ followed by anything else (a digit, a space, punctuation, the end of the string) is still a literal dollar sign ("$5" needs no escaping); to write a literal $ before { use \$. (Before v0.78.0 there was a short form $name that took the longest identifier, so "$obj_x" and "$obj.name" silently read a value the author did not write. It was removed rather than re-read as a literal because re-reading it would make every program written the old way silently print other text; an error makes every occurrence visible. dawn fmt from v0.78.0 through v0.79.0 rewrote $name to ${name}; from v0.80.0 it only reports the error, see `syntax-window-design.md` §2.) The effects of the expressions inside an interpolation are unioned into the effects of the whole string expression.

A ${...} must fit on one line (spanning lines reports interpolation cannot span lines), and that holds inside a triple-quoted string too: what may span lines is the string, not one ${...} within it. Otherwise an interpolation takes anything: the } that ends it is the one reached after skipping whole literals, so a } inside a string, a triple-quoted string, a raw string or a character literal ("${'}'}", "${`}`}") does not count.

Multi-line strings use triple quotes """; the leading and trailing newline and the common indentation are stripped. The interpolation rules are the same.

Raw strings use backticks: everything between `...` is literal — no escapes, no interpolation, may span lines, indentation not stripped, what you see is the value. The one restriction is that the content cannot contain a backtick itself (and there is no escape hatch; to write a backtick, use an ordinary string). The blind spots of the three forms complement each other: contains a backtick → "..."; a template that needs interpolation → """; verbatim text containing quotes and $ (regexes, code samples, HTML) → backticks.

1.7Newlines and semicolons

Statements are separated by newlines; there are no semicolons — writing a ; gets a dedicated diagnostic (telling you to delete it) and is then recovered as a newline, so it does not take everything after it down with it. A line that ends in a binary operator, |>, a comma or an opening bracket continues automatically; in addition, |>, . and binary operators are all allowed at the start of the next line (vertical pipelines / vertical method chains / vertical boolean or arithmetic, the idiomatic spelling — a Java builder chain x\n .uri(u)!\n .build()! can be broken across lines, and so can a long condition a\n && b\n && c). The sole exception is + and -: a leading - is ambiguous with unary negation (is x\n - y the expression x - y, or a new statement -y? there is no way to tell), so that pair of arithmetic operators does not continue a line from the start of one. By convention, one statement per line; dawn fmt makes it uniform. A line ending in =, ->/<-/=>, ., not or : continues as well (let a: with the type on the next line is one statement); the set is written once, in the lexer (continues_line), and dawn fmt derives its continuation indent from it, so the two cannot disagree.

A newline doubles as a separator in two places: between match arms (§5) and between the elements of a list literal (§4.11). Both parse the expression by the rules above first, and the newline left standing afterwards is the separator, so continuation wins and separation follows.

1.8dawn fmt

dawn fmt <file>... formats in place; dawn fmt --check <file>... only reports files that are not formatted (exit code 1 if there are any, for CI). The implementation is a reprinter over the token stream: it reprints token by token as-is (strings and interpolations are kept exactly as their source ranges, not a character changed) and adjusts the whitespace between tokens — intra-line spacing, 2-space indentation, collapsing consecutive blank lines (the author's physical line breaks are kept). The sole token normalization omits the optional first | of a single-line sum type declaration (§2.3); all other tokens and comments are preserved. Formatting is idempotent, and it only needs the lexer to succeed (not the parser), so a file with syntax errors can still be formatted.

A successful lex is a precondition, and failing it is a refusal: a character the lexer rejects produces no token, and tokens are all that get reprinted, so formatting such a file deletes it. So dawn fmt does not write back a file that does not lex — it renders the diagnostics, exits 1, and leaves the file untouched (--check likewise); the files in the same batch that do lex are formatted as usual. A directly named non-.dawn file is refused the same way (exit 2): directory mode already filters by extension and a named path did not, so one path typo was enough to feed Markdown to the Dawn formatter and overwrite it.

The rules: indent 2 spaces; 1 space on each side of a binary operator / -> / => / = / |>; 1 space after ,/: and none before; nothing inside (/[; ./? tight; .. tight on both sides (a..b; where it is a prefix instead — the record spread { ..base }, the list/constructor/record rest [x, ..rest] — the space to its left belongs to the opening bracket's or the comma's rule); over-long lines are not wrapped (lines the author broke are kept).

2.Types

2.1Basic types

The non-generic, compiler-owned basic types users may name directly are Int (64-bit), Char (a Unicode scalar value), Loc (a call site, §8.4), Float (double), Bool, String, Bytes (an immutable byte sequence), and Unit. These eight names, together with the three public generic names in the next section, are the complete public builtin type surface.

Unit is a first-class value (its only value is ()) and may appear anywhere a value can appear: parameters, local variables, closure captures, tuple elements, return values, and as an instantiated type parameter (Result[Unit, E], List[Unit], catch_fault(() => <void call>)). At runtime it has a real representation — a singleton object (dawn/rt/Unit, the same representation as None and as constructors without fields), occupying one reference slot; the C backend gives it one byte.

There is only one exception, and it is not a restriction of the representation:

Like the other scalars, Unit has the four impls Eq/Hash/Ord/Show (§3.5), and every answer is a constant: () == (), cmp((), ()) == 0, hash(()) == 1 (the seed of the synthesized hash: there are no parts), and it renders as (). The constant itself is useless; the use is in composition: Result[Unit, E] can therefore be compared, printed and used as a key. (Before 2026-09-24 these impls were withheld on purpose, for exactly the reason "the answer would be a constant"; builtin-privileges-design.md §2 records why that accounting was wrong.)

There is no null. A value of any type is necessarily valid; possible absence is expressed with Option[T]. There are no implicit conversions. Int → Float must be written explicitly as to_float(n). A numeric literal is not a value of Int or Float; it is typed by §1.5, so let f: Float = 1 is legal and let f: Float = n is not.

2.2Composite types and naming layers

The generic, compiler-owned types users may name directly are exactly List[T], Map[K, V], and Set[T]:

The remaining composite types do not belong to that builtin-name inventory:

In type position, (T) is grouping only: after parsing it is still T, with no extra type node. A tuple still has at least two elements: (A, B) is a tuple, (T,) is not a one-element tuple, and empty () is not a type either (the unit type is written Unit).

Function-type arrows remain right-associative, and a suffix effect belongs to the function layer it immediately follows. When the return type is itself a function, parentheses separate an outer effect from that returned function:

fn() -> fn() -> Int !io          # pure outer function, !io returned function
fn() -> (fn() -> Int) !io        # !io outer function, pure returned function
fn() -> (fn() -> Int !io) !io    # both layers are !io

Option and Result are ordinary prelude ADTs, with no special status (the ? operator has syntactic support for them, see §8.1).

Map[K, V] / Set[T] are built-in persistent containers on a par with List. They have no literal syntax and are operated on entirely through built-in functions (the list is in §11). The semantics that matter:

2.3Sum types (ADT)

The first | is optional; the formatting convention omits it on a single-line declaration and puts a bar before each constructor line in a multi-line declaration.

type Shape =
  | Circle(r: Float)
  | Rect(w: Float, h: Float)
  | Point                       # constructor with no payload

2.4Records

type Point = { x: Float, y: Float }

let p = Point { x: 1.0, y: 2.0 }
let q = Point { ..p, x: 3.0 }     # functional update
let d = p.x                        # field access

A record is sugar for a single-constructor product type, and supports pattern matching just the same. Fields are immutable — "modification" is functional update.

A record can only be built with braces, and only matched with them. Point(1.0, 2.0), Point(x: 1.0, y: 2.0) and Point() are all errors ("record Point must be built with braces"), whether the parentheses were written directly or produced by a pipeline (§4.4); Point(x: a) in a pattern is an error too ("record Point is matched with braces", since v0.78.0). The reason is that spelling and meaning correspond one to one: fields in the brace form must be named, and filling a record positionally would turn field order into an ABI; a record's bare name is not a constructor function either (§2.3, last bullet). x |> Point { ... } is not "filling in fields" — it calls a record value, and is reported as not callable.

A field of fn type can be called directly: r.f(x) calls the function value stored in the field, equivalent to let g = r.f followed by g(x); the field's effects are unioned into the caller as usual. When a function named f also exists in scope, the method spelling r.f(x) is a compile error (ambiguity) — a silent precedence would let a new function of the same name, added somewhere far away, quietly change the meaning of an existing call (§10.3 already rejected the same kind of ambiguity for module aliases of the same name; the rule here is the same). Disambiguation: to take the field, write (r.f)(x) (or bind it first with let g = r.f); to call the function, name it directly as f(r, x).

The ambiguity belongs to the one spelling r.f(x): it is the syntactic form of a method call (§4.3). The other spellings that apply r.f as a value — parentheses (r.f)(x), the pipe x |> r.f (§4.4: when the right side is not a call, it is applied to the left value as a whole), and with v <- r.f — have a field read as their callee, so when the record has a fn-typed field f they always take the field, whether or not a function of that name is in scope; a new function of the same name cannot change their meaning, so the reason above does not apply. (When the record has no field f, these spellings still call the function f by UFCS today; whether to tighten that is a separate question.)

2.5Generics

2.6Type aliases

alias Meters = Float                                  # built-in scalar
alias Pair = (Int, String)                            # tuple
alias Names = List[String]                            # generic application
alias Handler = fn(Request) -> Result[Response, HttpError] !io   # function type
alias Lookup[T] = fn(String) -> Option[T]             # may carry type parameters
alias Paint = Color                                   # user types (ADT/record) can be aliased too

Aliases have their own keyword, alias; type declares only nominal types (an ADT or a record). An alias is transparent (not a newtype): it is expanded during resolution and is fully interchangeable with the type it names.

alias Meters = Float provides no unit safety whatsoever. It is fully interchangeable with Float: Meters and Seconds can be added together, and passing a bare Float where a function takes Meters goes through fine. The first line above is only a syntax example of "an alias can name a built-in scalar" — do not read it as a recommended practice for domain modelling; unit types are the most misleading use of alias. The real value of aliases is in the lines below it: giving a long type a short name (Handler, Lookup[T]).

For unit safety, what you want is the opaque type of the next section: pub opaque type Meters = Float is interchangeable outside its module with neither Float nor Seconds, and getting in and out is two one-line functions (§2.7). This sentence used to read "Dawn does not have this yet" — that was written before §2.7 landed and nobody came back to change it (the root of LANG-05 is exactly examples and signposts drifting out of sync, and this sentence committed the same sin itself).

Historical note: the two once shared type, told apart by a "shape of the right-hand side" heuristic — same form, different meaning, and user types could not be aliased (a bare capitalised name was always read as a constructor). Now type X = <fn type/tuple/Name[...]/built-in scalar> is a compile error whose hint points at alias; type Color = Red keeps its ADT meaning unchanged.

Restrictions: an alias cannot be recursive (a cycle is an error); an effect variable must be bound by the parameter list (alias Mapper[T, U, !e] = fn(T) -> U !e), and writing an unbound one is an error, while a named label and !io are simply written (§6.3); with pub it can be imported across modules (use m.{Handler}).

2.7Opaque types

pub opaque type UserId = Int                # only this module knows it is an Int
pub opaque type Env = Map[String, Int]
pub opaque type Pair[T] = (T, T)            # may carry type parameters

opaque type N[..] = T has the same syntax as alias, with exactly one difference: who is allowed to see through it. Inside the module that declares it, N and T convert to each other; outside that module they are different types.

# inside module ids
pub fn wrap(n: Int) -> UserId = n           # ✅ convertible inside this module
pub fn unwrap(u: UserId) -> Int = u         # ✅

# in another module
let bad: Int = wrap(7)                      # ❌ annotated type is Int but the
                                            #    initializer is UserId

Conversion happens at assignment, argument and return positions (that is, wherever type assignability is decided), not inside an expression: u + 1 is still wrong inside the module; write let n: Int = u and then compute, and the result converts back automatically when it reaches a UserId position. This is the discipline of a newtype, and it also keeps "opaque" to a single decision in the implementation rather than special cases scattered everywhere.

Opacity blocks the view, it does not change the semantics: at runtime an opaque type is its target type — the same representation, the same equality, hashing and ordering (Eq/Hash/Ord, the target's unless the type writes its own), on both backends, at zero cost. opaque is a soft keyword; only opaque type means anything.

What it inherits is the relations, a closed allowlist. An opaque type with no impl of its own falls back to its target for Eq, Hash and Ord only. Every other trait (Show/Display, arithmetic, FromInt/FromFloat, format-identity traits such as HasDtype, and any trait a user or library declares) asks only the type's own impls, and a missing one is a compile error: no impl of … / … has no such impl. There is one criterion: a relation only answers true/false or a sign, exposes no representation and mints no value; every other trait describes the type's identity, format or behaviour, and borrowing the target's answer would hand the target's identity to a type that declared "I am not it". (Since 2026-10-07; before that the rule was "fall back by default, with a blacklist of Show, arithmetic, FromInt/FromFloat", every new trait meant one more special case, and HasDtype[U16] silently resolved to Int's "i64", the opposite of the "should be a type error" std/dtype declares. Haskell newtypes, Rust newtypes, Scala 3 opaque types and Kotlin value classes all inherit nothing by default; GHC's GeneralizedNewtypeDeriving reuses the representation's dictionary, again except for Show/Read. To inherit, write a two-line forwarding impl in the declaring module.)

The next two paragraphs are what this rule means for rendering and arithmetic.

Rendering. An opaque type does not inherit its target's Show (and so not its Display either). A relation only answers true/false or a sign and exposes nothing; a rendering prints the representation as it is, which is exactly what the type hides. To print one, write impl Show[N] in the declaring module (and impl Display[N] when needed); without it, to_string, ${…}, a field under derive Show and a [T: Show] bound are all compile errors for it. (Since 2026-09-24; before that it was inherited, and fourteen handle types in std and packages would print a handle number or internal state. GHC's GeneralizedNewtypeDeriving draws the same line: it reuses the representation's dictionary, except for Show/Read, which do not look through. The audit and the verdict per type are in builtin-privileges-design.md §4.)

Nor does an opaque type inherit its target's arithmetic (Add/Sub/Mul/Div/Rem/Neg, §3.5, §4.3): arithmetic makes a new value of the type, and only the declaring module knows how that value keeps the type's invariant (summing handle numbers, or skipping the re-rounding of a narrow float, would be silently wrong). To have +, write impl Add[N] in the declaring module; without it, u + u and a [T: Add] bound are compile errors for it, Char included (convert with char.code first). (Since 2026-10-06; before that, arithmetic on an opaque type was an error too, only because arithmetic accepted nothing but Int/Float. GHC draws the same line: Num does not come with a newtype for free, it takes an explicit deriving newtype. See arith-operator-traits-design.md D4.)

A generic opaque type's instance identity is its declaration identity together with its instantiated arguments; the target answers only questions about runtime representation. Even when a type parameter does not appear in the target at all, Phantom[Int] and Phantom[String] are two types; substitution, equality, unification, display and export-surface validation all carry those arguments along. "The representation is not public" does not imply "the type parameters are hidden".

The criterion for implementers (the alias-substitution test): replace opaque type N = T in place with alias N = T; if some function's answer changes, it is either one of the six things below, or it is a bug. Only six things are allowed to see TyOpaque: the assignability and unification decision (who can convert), impl selection (head_of/impl_at), symbol naming (ty_key/dict_key/impl method names), the type name in diagnostics, export-surface visibility (§3.3: it checks the identity and the explicit arguments, not the representation), and witness resolution outside the allowlist (only Eq/Hash/Ord fall back to the target). Every other function that eats a Ty — width, descriptor, slot, boxing, which instruction, whether it can be a constant, whether some trait has an answer — takes the target's answer. The order is fixed too: ask about identity before representation. impl Eq[UserId] must come before "compare as Int", or declaring it would be pointless. The mechanised form is in scripts/opaque-twin/: every corpus program is run twice, once as written and once with alias substituted, and the outputs must agree (a compile error counts as output). Doing this by hand once on 2026-07-27 caught 12 places. Traits outside the allowlist (rendering, arithmetic and the rest) are outside that property because of the rule above; the corpus renders and computes through the target explicitly, and "the alias side compiles, the opaque side is refused" is pinned separately by the twin-refused-alias-ok verdict.

An opaque type can be given its own impls (impl Show[UserId], impl Display[UserId]), which take precedence over the target type's; the orphan rule counts an opaque type as a local type of the module that declares it. Char wrote both (impl Display[Char] and impl Show[Char], §1.5), so it can be rendered, and neither of its renderings is the Int's while ==, < and hashing still are. scripts/opaque-twin/char.dawn pins all four, claim by claim, each rendering in both directions: equal to the string its impl is defined to produce, and not equal to the Int's.

Why it is needed: before this, every time a representation had to be hidden a mechanism was hand-rolled on the spot — Cursor was an opaque scalar minted by the compiler, and the HAMT nodes from making the collections pure Dawn would have been the next one. This puts the mechanism up before there is a third time.

Cursor has already been migrated (§11): the compiler's version was deleted outright and std/cursor stands it back up using the mechanism of this section, the first real user of the feature.

Array is not the same kind of thing — this used to say it would "migrate along with making the collections pure Dawn", and measurement showed that was wrong: this mechanism needs a target type, and Array has no target, it is the representation; the two also point in opposite directions, in that this mechanism publishes the name and hides the representation, while Array's is_std_module gate hides the name and exposes the representation to std. That gate stays; the reason is in `trait-v2-design.md` §8.3.

3.Declarations

Only these are allowed at module top level: use, type (including opaque type), alias, const, fn, test, trait, impl, effect. There is no top-level mutable state.

3.1Functions

fn add(a: Int, b: Int) -> Int = a + b

fn greet(name: String) -> Unit !io = {
  println("hi, ${name}")
}

Default parameter values (2026-08-08, #207): a parameter may be written name: Type = expr; a call that omits the argument evaluates the expression once per call (not Python's evaluate-once-and-share):

fn column(kids: List[Int], align: Int = 0, gap: Int = 0) -> Int = align + gap * len(kids)

column(kids)
column(kids, gap: 12)
column(kids, align: 1, gap: 12)

Local named functions: a block may contain a fn name(params) -> T [!Row] = body statement — essentially "a lambda whose name is visible inside its own body", so it can recurse (a self tail call compiles to a loop, §12.4), can capture enclosing bindings (by value, same rule as lambdas), and can be passed as a value. Parameter types and the return type must be written out in full; the effect row follows the rule of a written function type (§6.2, rule 8): !io, named effects, and the effect variables and associated-effect projections the enclosing signature binds may be written, but no new effect variable can be introduced; type parameters cannot be declared (the enclosing function's type parameters are naturally in scope).

fn sum(xs: List[Int]) -> Int = {
  fn go(i: Int, acc: Int) -> Int =
    if i == len(xs) { acc } else { go(i + 1, acc + xs[i]) }
  go(0, 0)
}

3.2Constants

const MAX_DEPTH: Int = 64
const SIN_TABLE: List[Float] = comptime {
  range(0, 360) |> map(d => sin(to_radians(d)))
}

The right-hand side of a top-level const is implicitly in a comptime context (§7); it must be pure and reducible to a constant.

3.3Visibility

All declarations are module-private by default; pub exports. pub can be used on fn, type, alias, const, trait, effect. pub type exports its constructors and fields as well.

The complete resolved export surface of a pub declaration must be nameable outside its module. Marking only the outermost declaration pub does not export the private nominal identities it refers to:

An ordinary pub fn may declare a public named effect (§6.5): callers can import it, propagate it, or install a handler. It is a private effect in a public surface that is an error.

3.4Test blocks

test "precedence" {
  assert eval("2+3*4") == Ok(14)
}

test eval {
  assert eval("1") == Ok(1)
}

Tests named by a declaration. Instead of a string, test may be followed by the name of a top-level declaration of this module, and the test is that declaration's example:

Rationale: an example should be code, not text inside a comment. Written as a test, dawn fmt, the editor and diagnostics all work on it as usual, renaming or deleting the declaration it names is immediately a compile error, and a published example therefore always compiles and passes. The shape is Zig's decltest rather than Rust's code blocks in /// that a tool extracts and runs: those need a language of block attributes of their own (ignore, no_run, should_panic), mapping diagnostics from the comment's text back to source positions, and a tool that rebuilds code across lines, against §1.2's "every comment line tokenizes on its own". The name may only refer to this module: a test block already belongs to its module, so naming a declaration elsewhere means the example is in the wrong place, and if imported names counted, the same example would change owners as use lines come and go. A constructor is T.Ctor rather than a bare Ctor so that "a bare name is a top-level declaration" has no exceptions.

3.5trait and impl

A single-parameter, nominal typeclass, implemented by dictionary passing (the full design and the decision rules are in trait.md):

trait Ord2[T] {
  fn cmp2(a: T, b: T) -> Int
  fn max_of(a: T, b: T) -> T = if cmp2(a, b) >= 0 { a } else { b }  # default body
}

impl Ord2[Point] {
  fn cmp2(a: Point, b: Point) -> Int = a.x - b.x
}

fn sort2[T: Ord2](xs: List[T]) -> List[T] = ...   # bound: [T: Trait (+ Trait)*]
trait Head[C] {
  type Item
  fn first(c: C) -> Option[C.Item]
}

impl[T] Head[List[T]] {
  type Item = T
  fn first(c: List[T]) -> Option[T] = get(c, 0)
}

fn head_or[C: Head](c: C, d: C.Item) -> C.Item =   # the projection reduces at instantiation
  match first(c) { Some(x) -> x, None -> d }        # head_or([1], 9) is Int

Heterogeneous collections

There is no dyn; the idiom for a heterogeneous collection is first-class functions plus an opaque type: while the type is still concrete, wrap the method call in a closure, put the closure in a record, declare the record as an opaque type, and give that opaque type an impl.

type ShownRepr = { render: fn() -> String }

pub opaque type Shown = ShownRepr

pub fn shown[T: Show](x: T) -> Shown = {
  let r: ShownRepr = ShownRepr { render: () => show(x) }
  r
}

impl Show[Shown] {
  fn show(s: Shown) -> String = {
    let r: ShownRepr = s
    r.render()
  }
}

pub fn main() -> Unit !io = {
  let xs: List[Shown] = [shown(1), shown("two"), shown(true)]
  for x in xs { println("${x}") }
}
1
"two"
true

Each of the four steps rests on a rule stated in this document:

Where it applies:

4.Expressions

Dawn is expression-oriented: if, match and blocks all produce values.

4.1Bindings

let x = 42              # immutable binding, type inferred
let y: Float = 1.0      # optional annotation
var acc = 0             # mutable local variable
acc = acc + 1           # assignment, legal only for var

4.2Blocks

let area = {
  let w = 3.0
  let h = 4.0
  w * h                  # the last expression is the block's value
}

A block introduces a new scope; the last expression is the block's value, and every other statement must have type Unit (this stops a Result from being quietly discarded — discarding a non-Unit value must be written out as let _ = ...).

4.3Operators and precedence

From lowest to highest:

PrecedenceOperatorAssociativityNotes
1|>leftpipeline, see §4.4
2||leftlogical or, short-circuiting
3&&leftlogical and, short-circuiting
4== != < <= > >=non-associativecomparison; chained comparison is a syntax error
5|leftbitwise or; Int only
6^leftbitwise xor; Int only
7&leftbitwise and; Int only
8<< >> >>>leftshifts; Int only. >> is arithmetic (sign-filling), >>> logical (zero-filling)
9++rightString/List concatenation
10+ -leftboth sides the same type; native on Int/Float, through Add/Sub on other types (§3.5)
11* / %leftboth sides the same type; native on Int/Float, through Mul/Div/Rem otherwise; Int division by zero panics
12not, unary -, ~prefixunary - goes through Neg past Int/Float; ~ is bitwise complement, Int only
13? . () [] callpostfix? see §8.1; () has been a general postfix since 2026-07-30 (see below)

Numeric edge semantics (all of them guaranteed — after selfhosting the two implementations are cross-checked against this, "happens to agree" is not allowed):

Dot calls (UFCS)

x.f(a, b) is another spelling of f(x, a, b): the receiver x fills the first parameter of f, and the arguments in the parentheses fill the rest in order. This is pure sugar and introduces no new node. It is the same call as the pipe x |> f(a, b) (§4.4); the three spellings (f(x, a, b), x.f(a, b), x |> f(a, b)) have the same types, effects, evaluation order and diagnostics. The dot is a postfix (row 13 of the §4.3 table) and binds tighter than unary operators and |>: a + b |> f is f(a + b), while (a + b).f() applies f to the sum.

What recv is decides which kind of call recv.name(args) is, tried in this order:

  1. Module alias: recv is the alias of a whole-module import, so this is the qualified call alias.name(args) (§10.3). An alias sharing its name with any binding of this module is a compile error, so this step never competes with the ones below.
  2. Java static: recv is a class name brought in by use java (Math.floor(x), StringBuilder.new()).
  3. Java instance: recv is a value whose type is a Java class with an instance method named name.
  4. fn-typed record field: recv is a record value with a fn-typed field named name, so the function value stored in the field is called (§2.4). If a function named name is also in scope, this spelling is a compile error (ambiguity); disambiguate with (r.name)(a) or the direct call name(r, a).
  5. UFCS: otherwise name is looked up as a bare name in the current scope as a function, and recv becomes its first argument. What it finds can be a function of this module, a selectively imported name (use std/str.{split}), a prelude builtin, or a trait method (trait methods enter the module function namespace).

Step 5 only sees names that are in scope unqualified. A whole-module use std/str binds only the alias str and does not bring split into scope, so s.split(",") does not hold and the compiler reports:

error: undefined function: split
  = hint: `split` is not in scope unqualified, but an import exports it: write
    `str.split(...)`, or add `use std/str.{split}` to keep the dot call

Either write the qualified call str.split(s, ",") (or the pipe s |> str.split(","), which needs no import of the bare name), or import selectively and keep the dot.

Named arguments work as usual; the receiver already took the first slot by position, so x.f(self: y) reports "parameter self is given twice" (the named-argument item of §4.3). A tail block also lands on a dot call: xs.each { x => e } is each(xs, x => e).

4.4Pipelines

x |> f(a, b) is equivalent to f(x, a, b) — it puts the left-hand side into the first parameter. x |> f is equivalent to f(x). Standard library APIs are all designed around "the main datum is the first parameter" so that they work with pipelines.

|> is argument insertion into an ordinary call, and nothing else. The right-hand side is parsed as one expression by the postfix rules of §4.3; if its outermost form already is a call (f(a), m.f(a), r.m(a), make()(a)), the left-hand side goes in front of that call's written arguments; otherwise the whole right-hand side is applied to the left-hand side.

x |> f(a)          # f(x, a)
x |> f             # f(x)
x |> m.f(a)        # m.f(x, a)        a module alias is not a receiver
x |> r.m(a)        # r.m(x, a)        the receiver stays put, it is not re-inserted
x |> make()(a)     # make()(x, a)     not make()(a)(x)
x |> One(a)        # One(x, a)        a constructor is just another thing being called

The pipeline introduces no node of its own, and so:

4.5Lambda

A function value takes at most 8 explicit parameters. Function types, lambdas, and named functions or constructors used as values are rejected during checking when they exceed this limit. Direct named calls and direct record construction are not subject to this function-value limit. Ordinary effect operations take at most 8 parameters; ctl effect operations take at most 7 because their handlers also receive a continuation. Operations are checked at their declarations. These limits are the same on the JVM and native backends.

let double = (x: Int) => x * 2
let add = (a, b) => a + b         # parameter types may be omitted when inferable
let now = () => 0                 # zero parameters
xs |> map(x => x * x)             # parentheses optional for a single parameter

4.6if

let sign = if x > 0 { 1 } else if x < 0 { -1 } else { 0 }

4.7Loops

for x in [1, 2, 3] { println("${x}") }
for (key, value) in entries { println("${key}=${value}") }
while queue.non_empty() { ... }

Idiomatic style prefers map/filter/fold; loops are there for performance-sensitive spots and for taste.

4.8Indexing

let x = xs[i]        # List[T] -> T; out of range panics (negatives included)
let v = m["key"]     # Map[K, V] -> V; a missing key panics (the message carries the key)
let c = rows[1][0]   # chainable, composes with ?/./()

An impl for a user type:

type Grid = { w: Int, cells: List[Int] }

impl Index[Grid] {
  type Idx = (Int, Int)
  type Item = Int
  fn index(g: Grid, p: (Int, Int)) -> Int = {
    let (x, y) = p
    g.cells[y * g.w + x]
  }
}

let g = Grid { w: 3, cells: [1, 2, 3, 4, 5, 6] }
let v = g[(2, 1)]                                 # 6

fn first[C: Index](c: C, i: C.Idx) -> C.Item = c[i]   # a generic consumer

The three out-of-range criteria. The language promises three out-of-range policies only, and every operation taking an index/range parameter (the [] of this section and the library functions of §11) belongs to exactly one of them, classified by what the parameter means rather than settled function by function:

  1. Assertion — the parameter is a position, the caller claims it is valid, and out of range is a bug: xs[i], m[k], bytes.at, str.at, pvec.index/nth, an invalid range for cursor.slice → panic (negative indices included).
  2. Enquiry — out of range / a missing key is a normal branch the caller wants to tell apart: the get family (list.get, map.get, absence in set.has, a miss in the index_of family (str/bytes/list), a non-match in str.strip_prefix/ strip_suffix, malformed input to bytes.from_hex/from_base64 and to fspath.extension (package)) → Option (or Bool).
  3. Clamping — the parameter is a range, saying "whatever part of this stretch is there", and does not assert that the endpoints exist: list.take/drop/slice, bytes.slice, str.slice/take/drop, cursor.next/prev/back/seek → each end is clamped into [0, len] (a negative becomes 0, an over-long one len), from > to gives the empty sequence, and it never panics.

The one named exception: cursor.char(s, c) returns the sentinel -1 at the end rather than an Option (§11, "std/cursor"). It is the primitive that advances character by character — wrapping every step in an Option is one allocation per step; the same sentinel is wrapped by std into a panic over at bytes.at (criterion 1), while here at cursor.char it is part of the public contract (the lexer of packages/json depends on it). Apart from this, no library function may express out of range with a sentinel value.

4.9return

fn classify(n: Int) -> String = {
  if n < 0 { return "negative" }   # guard clause
  if n == 0 { return "zero" }
  "positive"
}

4.10The with statement

fn write_all(path: String, bytes: Bytes) -> Unit !io = {
  with f <- bracket(FileOutputStream.new(path), s => s.close())
  f.write(bytes)!
  f.flush()!
}

with x <- f(a, b) is parser-level sugar: all the statements after it in the block are packed into x => { ... } and attached as f's last argument, and the whole call becomes the block's value at that point. The snippet above is equivalent to

bracket(FileOutputStream.new(path), s => s.close(), f => {
  f.write(bytes)!
  f.flush()!
})

Why bracket and not defer: the protected interval is always exactly one closure call, return/break cannot get out of it at the language level, and so the compiler owes no escape-rewriting pass. The criteria are in docs/core-move2-design.md §2.6 and §6.

4.11List literals and their element forms

list_lit  = "[" [ list_elem { list_sep list_elem } [ list_sep ] ] "]"
list_sep  = "," | NL                   (* a newline is the same separator as a comma;
                                          adjacent, the two count as one *)
list_elem = expr                       (* an ordinary element: contributes one *)
          | ".." expr                  (* a spread: contributes 0..n *)
          | if_no_else                 (* a conditional element: contributes 0 or 1 *)
if_no_else = "if" expr block { "else" "if" expr block }   (* no final else *)
column([
  header,
  ..body,                            # body: List[Widget[Msg]], spliced in whole
  if m.note != "" { text(m.note) },  # a line only when there is something to say
  help,
])

Separators: a newline is a comma. Inside a multi-line list literal the commas between elements may be dropped, and one newline is one separator:

column([
  header
  ..list.map(m.todos, t => item_row(t))
  if m.note != "" { text(m.note) }
  dim(text("commands"))
])

The two separators may be mixed within one literal, a trailing comma or newline is still allowed, and both [] and a [\n] spanning lines are still zero elements. This is a pure syntactic addition: [1, 2, 3], a multi-line literal with commas, and a trailing comma all parse to exactly what they parsed to before. dawn fmt does not rewrite either spelling into the other either; the author's choice of separator is kept, since for lists the formatter only adjusts spacing within a line and indentation, never the line breaks the author wrote.

What is dropped is only the comma at a line break. Two elements on one line still need one: [a b] is a syntax error, and the diagnostic is the same "expected ], found b" at the same position.

Which newline is a separator is decided by §1.7, not by this rule. An element is parsed by the ordinary expression rules first, an operator that may lead a continuation line (|>, ., a binary operator) is still swallowed by the element above it, and the newline left standing is the separator:

[
  xs
    |> f        # one element: `|>` leads a continuation line, which has nothing to do with lists
  a
  -1            # two elements: `+`/`-` never lead a continuation (§1.7), so `-1` is a prefix
                # minus opening a new element
]

+ has no prefix meaning, so a + at the start of a line lands at an element position and is refused there, with "expected an expression, found +". That is what the +/- exception does at an element position, not an extra rule of the list literal's own.

A line-leading .. always reads as a spread, never as a range continuing the line above. .. is not an expression operator (all four of its meanings are positions, see below) and the range a..b appears only in a for header (§4.7), so the left-hand literal below is two elements rather than one range:

[
  a
  ..xs        # a spread element
]
[0..3]        # still refused: `..` between two values, and not at the start of an element, is
              # neither of its meanings

The three element forms hold only inside a list literal. Tuples, records and constructor arguments do not know them; the pattern [x, ..rest] (§5.1) is a different thing — the rest of a destructuring, spelled symmetrically with the spread here and meaning the opposite.

The spread ..xs: the operand must be a List[T], and each of its elements is laid out in place. Anything else is ".. spreads a list, but this is …". .. is never legal in expression position; it appears in exactly these places: the range in a for header (§4.7), the record spread P { ..p } (§2.4), the rest pattern (§5.1), and the element spread here.

The conditional element if c { x }: a true condition contributes one element x, a false one contributes none. x's type joins the element type, and it need not be Unit — the rule that an if without an else must be Unit (§4.6) does not apply at this position, because nothing here needs it to produce a value.

An else if chain is one element form as a whole: if a { x } else if b { y } contributes 0 or 1, taking the arm whose condition is first true, and none if no condition is. However deep the chain, it is one element form.

A chain that does end in an else is not an element form; it is an ordinary element, and it means exactly what it meant before this feature existed: [a, if c { x } else { y }, b] is always three elements. Hence a deliberate asymmetry — the else-less form may be omitted, the form with an else may not be expanded:

[a, if c { x }]              # 0 or 1: a conditional element
[a, if c { x } else { y }]   # always 1: an ordinary element, one of two
[a, if c { ..xs } else { ..ys }]   # illegal: `..` is not at an element position

The reason is to take the smallest cut. Letting the form with an else expand too means making both branches of an if be a run of elements rather than a value — Dart's collection-if/collection-else, a second if grammar that holds only inside a collection literal, and with it a string of further questions about whether the else branch may nest a for, another if, and so on. The else-less form needs none of that: in ordinary expression position it could only ever be Unit, so moving it to an element position collides with no existing meaning. The same reasoning rules out a collection-for ([for x in xs { f(x) }]): list.map already writes it, and adding for immediately raises "why is there no while".

Evaluation order is left to right, and the element forms do not change that. A conditional element's body is evaluated only when its arm is taken.

Typing: every element form's contribution joins one element type T, and the literal is a List[T]. An ordinary element contributes its own type, a spread contributes the T of its List[T], a conditional element contributes the common type of its arms' bodies.

The expected type is pushed down, which is what the element forms are really for: once T is settled — from the literal's expected type, or from any element already checked — every later element is checked at T. A spread's operand receives List[T], and each body of a conditional element receives T. So:

# text: fn text[M](s: String) -> Widget[M], where M appears only in the return type
[text(s)]                    # error: cannot infer type parameter(s) M
[header, text(s)]            # fine: header settles M as Msg first
[header, if c { text(s) }]   # equally fine: the expectation crosses into the body

The third line is why intermediate bindings like let note: List[Widget[Msg]] = if … disappear: a standalone [text(s)] binding has no sibling to ask and must be annotated, while the same things written as elements of one literal need no annotation. Elements that cannot be checked without an expectation (a bare None, a nested []) are still checked in a second round, so they do not depend on source order.

Breaking change in meaning (after v0.67.0): [if c { <a Unit expression> }] used to be legal, of type List[Unit], and always of length 1 — the if inside was an ordinary element, evaluated as a statement and producing (). The same source now has length 0 or 1, and the body is not evaluated at all when the condition is false. Nothing is reported; the behaviour changes silently.

The affected programs are exactly the family "a conditional element whose body has type Unit", no more and no less: before the element forms, an if without an else in expression position could only be Unit (§4.6). Landing this, every .dawn file in dawn-lang (566) and in the dawnop-site backend (84) was scanned file by file with the new parser: zero existing occurrences.

No transitional diagnostic was added, because it could only be an error: Dawn's diagnostics have no severity — Diag carries msg/lo/hi/hint and everything is an error. And making "a conditional element whose body is Unit" an error would carve a permanent hole in the new form's typing rule to protect a class of programs measured not to exist; a List[Unit] of length 0 or 1 is coherent under the new rule. A transition ends; a special case in a typing rule does not.

5.Pattern matching

match shape {
  Circle(r) if r > 100.0 -> "big circle"
  Circle(r)              -> "circle ${r}"
  Rect(w, h)             -> "rect ${w}x${h}"
  Point                  -> "point"
}

Adjacent match arms must be separated by a physical newline or ,. A comma may be followed by a newline, and a trailing comma after the final arm is allowed. Whitespace alone is not a separator: match x { 0 -> 1 1 -> 2 } reports the missing newline or comma at the second 1, rather than treating a token that looks like a pattern as an implicit boundary. This does not change §1.7 newline continuation: a newline nested inside (), [], or {} still belongs to the arm body expression.

5.1Pattern forms

PatternExampleMatches
Literal0, "yes", truematches if equal
Bindingxalways matches, and binds
Wildcard_always matches, binds nothing
ConstructorSome(x), Rect(w, h), Rect(w: w, ..)destructures by position or by name, .. ignores the remaining fields; parentheses only
RecordPoint { x, .. }field destructuring; braces only
Tuple(a, b)
List[], [x, ..rest]empty list / head and rest
Or0 | 1 | 2any alternative matches (the bindings of every alternative must agree)
Guardpat if condthe pattern matches and the guard is true

| has the lowest precedence in a pattern. It may occur recursively inside constructor, record, tuple, and list patterns, and is collected in source order as a flat n-ary or-pattern. (pat) is grouping only; a tuple pattern still requires a comma. The | may start a continuation line, as in A\n| B. A newline followed by a pattern without | still starts the next match arm. A pattern's first | is optional, the same rule as a sum-type declaration's (§2.3): | A | B -> 1 is A | B -> 1, so a multi-line or-pattern can give every alternative its own line and its own bar, and dawn fmt lines those bars up with the arm:

fn light(c: Color) -> Int =
  match c {
    | Red
    | Amber -> 0
    Green -> 1
  }

A line-leading | belongs to patterns alone: it does not continue a bitwise or from the line above (0 -> x followed by a line | A -> 2 is two arms, not x | A); a bitwise or that wraps keeps its | at the end of the line, the way a line-leading - is a prefix and never continues a subtraction (since v0.78.0).

At run time the first matching alternative is selected, with no backtracking inside that or-pattern. A match-arm guard applies to the whole or-pattern and runs at most once. If it is false, matching continues at the next arm. The body also runs at most once.

Every alternative must bind exactly the same name set, and each shared name must have the same type. The enclosing let or var selects mutability once for the whole pattern, so alternatives cannot differ on it. The first alternative supplies the canonical binding in the shared environment; later alternatives only provide another path that assigns its value.

5.2Exhaustiveness

match must be exhaustive. The compiler checks exhaustiveness on ADT/Bool/Option/Result/tuple; a missing arm is an error and the missing constructors are listed. A match on Int/String/Float must have a _ or a binding arm as the catch-all.

let also accepts irrefutable patterns: let (a, b) = pair, let Point { x, y } = p, and let m.Only(x) = value for an imported single-constructor type. Or-patterns use the same usefulness check, so let true | false = flag is valid while let true = flag remains refutable and is rejected.

The compiler normalizes type-known complete alternatives, including true | false, before the usefulness search. The remaining search has a deterministic work budget. If that budget is exhausted, an otherwise legal match or structural let is rejected with pattern analysis exceeded its complexity budget instead of guessing about exhaustiveness. The diagnostic advises simplifying nested alternatives or splitting the pattern into smaller matches.

6.Effect system

6.1Model

An effect row has two axes.

The base axis's two ground points are pure (the default, written nowhere) and io. !io covers every observable side effect: files, network, clock, random numbers, printing, mutable global state, and all Java interop. Two kinds of non-ground atom live on the base axis as well, beside io rather than as special cases of it: effect variables (§6.3) and associated-effect projections (§6.5).

The label axis is the finite set of named effects the user declares with effect (§6.5). It is independent of the base axis: !io does not cover named effects. So an !io function that performs !Ask still has to write !Ask in its signature.

Clocks. Reading a clock is !io, and there are two primitives: the wall clock io_clock_wall_ns (nanoseconds since 1970-01-01T00:00:00Z; the host may set it, so a later reading can be smaller and a reading can be negative) and the monotonic clock io_clock_mono_ns (an arbitrary origin, and only the difference of two readings means anything; both backends read the same clock, System.nanoTime on the JVM and CLOCK_MONOTONIC on native and wasi). Both are nanoseconds in one Int, representable to about 2262; the resolution is the host's and is not promised. Both are for std only (§10.6) and refused by compile-time evaluation (§7.2): a reading would make one source compile to different bytes at different times. A program reads the clocks through std/io's named effect Clock (§6.5), whose production handler is io.with_clock_real: io.now_wall_ns() answers the wall clock as an Int, io.now() a monotonic reading as an io.Instant (opaque, §2.7), and io.elapsed_ns(a, b) is b - a, or 0 when that is negative.

io wears two faces and they are read separately, which is this section's main clause: under containment io is an upper bound, so a signature that promises !io stands over a purer implementation (including one that only performs effect variables); under union io is not an absorbing element, so !io !e may not cancel !e and both atoms stay in the normal form (printed !(e|io)). The full rules are in §6.6.

Both axes are trivially decidable: union is componentwise union of finite sets plus one boolean or, containment is set containment per axis.

Ambient effects

io is the only ambient effect. Ambient effects are a tier, not "a lowercase atom": one is written into any row without a declaration, occupies no evidence slot, is answered by no handler and subtracted from the row by none, and any signature that writes it admits it. A program cannot declare an ambient effect (effect declares named effects on the label axis), so today the tier has exactly one member, io.

What an atom is comes from tables, not from its spelling, looked up in this order: the ambient table → the named effects in scope (including selective imports and renames, §10.2) → a module alias's exports (!dep.Ask) → a type parameter's associated effects (!T.E) → this signature's effect variables. For a name no table knows, the spelling only decides which diagnostic is reported: an uppercase name was meant as an effect and gets "unknown effect" (or "is a type, not an effect" when it is a type); a lowercase name is an effect variable, introduced by appearing (§6.3). The two always agree on a legal program because the case is enforced at the declaration site: effect takes only an uppercase name, an effect parameter only a lowercase one, and a rename may not change the case class.

pure is likewise reserved only in effect position: it is not a keyword, is an ordinary identifier outside effect position, and is refused everywhere inside one (§6.3).

6.2Rules

  1. The effect of a function body = the union of the effects of every call in it.
  2. A function whose signature is not marked !io, with an io effect appearing in its body → compile error (the error points out which call introduced io, and suggests adding !io to the signature or eliminating that call).
  3. Marked !io but the body is pure → allowed (room reserved for evolution). Dawn has one diagnostic level and no lints; a "redundant !io" rule will either be an error some day or not exist.
  4. A pure function is guaranteed: same arguments return the same value, no observable side effects. The compiler may fold it, deduplicate it, and call it at comptime on that basis. The one exception is dbg (§8.3): the stderr line it writes is defined as a diagnostic side channel and not a side effect of the program, which is why its type is pure. Named effects are inside that guarantee too: a function value's type carries its full effect row, and the only thing that can subtract a label from a row is the with handle that really answered it (§6.5), so a function whose signature says pure cannot run somebody else's handler arm.
  5. A function value's effects are answered at the call, not where the value was written. A closure's row is what its body performs, unrewritten at the creation point; if the row an individual call instantiates carries a named effect nobody answers, the error is reported on that call (§6.5).
  6. panic/todo/assert do not count as io — they do not return (divergence is not an effect).
  7. No absorption. An effect row may not drop a label, an effect variable or an associated-effect projection unless a handler answered it. Union drops nothing (§6.6); and when a function value goes into a slot, the slot's row must carry its row atom for atom, because a dropped atom is a dropped piece of evidence. The one subtraction point is with handle (§6.5), and it subtracts only the label it answers. A signature promising !io over a variable it binds is not a drop: that is containment (§6.6), and the variable still has an evidence slot from that signature's binder list.
  8. A local fn's row follows the same rule as a lambda's and a written function type's: fn g() -> Int !Ask = ask() is legal, and so are !e and !T.E when the enclosing signature binds them; the same body written as a lambda and as a local fn can do the same things. The one difference is that a lambda's row is inferred from its body while a local fn's is a written, fixed promise (as a top-level signature's is, §3.1), so using a label, variable or projection the row leaves out is an error; a local fn cannot introduce a new effect variable (it cannot declare type parameters either). Before v0.78.0 a local fn's row could only be !io or pure (SPC-19).

6.3Effect polymorphism

Higher-order functions use effect variables to forward the effects of their arguments:

fn map[T, U](xs: List[T], f: fn(T) -> U !e) -> List[U] !e
fn compose[A, B, C](f: fn(A) -> B !e1, g: fn(B) -> C !e2) -> fn(A) -> C !(e1 | e2)

6.4(removed) unsafe_pure

This section used to define unsafe_pure { <expression> }: an expression stamp, legal only inside std, that masked !io to pure, together with the compile-time Java folding it licensed (route C) and the --comptime-ffi switch. It was removed on 2026-09-24 along with the keyword (ruling 5): it had zero use sites in the whole ecosystem, and what it carried — "one host call supports a pure function" — is carried on the declaration side by the intrinsic contract (§11): a primitive's effect row ships with the compiler and is guarded by the bootstrap and the differentials, rather than vouched for one call site at a time. unsafe_pure is an ordinary identifier from now on. The design and the reasons for removal are in `docs/pure-ffi-design.md` and `docs/effects-window-design.md` §6. The section number is kept so that references to §6.5 and §6.6 across the tree do not shift.

6.5Named effects and with handle

Qualified names and renaming

An effect is an ordinary module member, reached by the same routes as a type or a function: with use library as dep, !dep.Ask names the public effect Ask declared by library; with use std/io, !io.Fs works the same way (io there is a module alias, not the ambient effect io, which is an undotted atom). The lowercase first segment is a module alias, not an effect variable; !T.E retains its uppercase-first associated-projection meaning. Qualification is available in every effect row, including function types, effect arguments and unions such as !(io | dep.Ask | e). It also names a single ground effect in trait defaults and impl bindings (effect E = !dep.Ask), and a handler selector (with handle dep.Ask { ask() => 42 }). Handler arms use the operation's unqualified name within the selected effect.

A selective import can rename an effect: after use std/io.{Fs as Files} a row writes !Files and a handler with handle Files { ... } (the general renaming rule is in §10.2). A rename changes this module's name table only; the effect's identity, the operation names it brings along and the name diagnostics print all stay the same.

Qualified, selectively imported and renamed names resolve to the same provider-owned effect identity. Different modules' same-named effects remain distinct; a whole-module import does not introduce the effect or its operations into the unqualified namespace. When two libraries export effects of the same name, using both means qualifying or renaming them; importing both bare is a clash error. Missing aliases, missing or private effects, and exported members of the wrong kind are errors, never implicit effect-variable binders. Only two segments are supported. Ground bindings still reject variables, associated projections and unions; qualification does not relax that rule.

effect declares a set of operation signatures; the call site calls an operation directly, and the with handle lexically nearest to the call answers it.

There are two tiers of arm. A tail-resumptive arm is an ordinary closure that is "called in place, its return value is the operation's result", with no continuation capture. A control arm carries one more clause (op(args…) resume k => expression): k binds the continuation of that operation, and the arm's value is the value of the whole with handle block. A control arm can be written only under an effect declared ctl, and the rules for it are collected in "Control arms" below. Whether the binding clause is there is the arm's kind marker. For the design and the verdicts see `docs/effects-design.md` and `docs/oneshot-design.md`.

Declaration

effect Ask {
  ## Ask the context for an Int.
  fn ask() -> Int
}

effect State {
  fn get() -> Int
  fn put(v: Int) -> Unit
}
ctl effect Fetch {
  fn fetch(url: String) -> String
}

Spelling and propagation

fn sum_three() -> Int !Ask = ask() + ask() + ask()

fn logged(x: Int) -> Int !Ask !io = {
  io.println("asking")
  ask() + x
}

with handle

fn demo() -> Unit !io = {
  with handle Ask { ask() => 42 }
  io.println("${sum_three()}")      # 126
}

with handle E { arms… } is one clause form of the with statement (§4.10): the rest of the block lives in that handler's scope, exactly isomorphic to with x <- f(…), and it inherits all of its discipline — legal only inside a block, the rest is a real closure, return/break/ continue are refused (the diagnostic names with handle), ? passes through transparently.

use std/io

effect Emit {
  fn emit(n: Int) -> Unit
}

fn body() -> Unit !Emit = {
  emit(1)
  emit(2)
}

pub fn main() -> Unit !io = {
  with handle Emit {
    var acc: List[Int] = []
    emit(n) => { acc = acc ++ [n] }
  }
  body()
  io.println("${acc}")
}
[1, 2]

That is the shape cells exist for: the emits scattered through body() accumulate into acc in the order they were performed, while body's signature says only that it performs !Emit and says nothing about where the values end up.

Lexical scope and the supply point

Evidence (the handler's arms) is resolved lexically: an operation call binds to the lexically nearest with handle. Evidence enters the callee with the call; a closure captures no handler at its creation point. Consequences:

use std/io

effect Ask {
  fn ask() -> Int
}

fn escaping() -> fn() -> Int !Ask = {
  with handle Ask { ask() => 7 }
  () => ask() + 1
}

pub fn main() -> Unit !io = {
  let f = escaping()
  with handle Ask { ask() => 2 }
  io.println("${f()}")
}
3

ask() => 7 answers the operations performed inside its own region, and f() happens outside it, so f's row keeps !Ask and the handler here in main answers it.

Control arms: the resume binding and one-shot continuations

A control arm has the form op(args…) resume k => expression, with k named by the author. It can be written only under a ctl effect; an arm of a non-ctl effect that carries the binding clause is a compile error, and the diagnostic names that arm and asks for the declaration to be changed. Suspendability is a property of the declaration, because a row names effects and that is all the Java boundary can read. ctl is a licence rather than a requirement: a tail-resumptive arm with no binding clause is legal under a ctl effect.

use std/io

ctl effect Ask {
  fn ask(n: Int) -> Int
}

fn release(tag: String) -> Unit !io = io.println("release ${tag}")

fn resumed() -> Int = {
  with handle Ask { ask(n) resume k => k(n + 1) }
  ask(1) + ask(10)
}

fn bare() -> String !io = {
  with handle Ask { ask(n) resume k => "dropped at ${to_string(n)}" }
  with r <- bracket("bare", release)
  "held ${r}, then ${to_string(ask(1))}"
}

fn explicit() -> String !io = {
  with handle Ask {
    ask(n) resume k => {
      discard(k)
      "discarded at ${to_string(n)}"
    }
  }
  with a <- bracket("outer", release)
  with b <- bracket("inner", release)
  "held ${a} and ${b}, then ${to_string(ask(1))}"
}

pub fn main() -> Unit !io = {
  io.println(to_string(resumed()))
  io.println(bare())
  io.println(explicit())
}
13
dropped at 1
release inner
release outer
discarded at 1

resumed is one round trip: k(n + 1) runs the rest of the block with that value as the result of that ask, and what the rest produces is the arm's value, which is the block's. bare and explicit are the two halves of the ruling below.

Abandoning a continuation

A continuation that was captured and never resumed ends in one of two ways, and the language recognises only an explicit trigger.

Each of the four misuses has a verbatim message, and they are written once, in the output of the program below, in this order: resuming a continuation already spent; discarding one already spent (discard-then-resume, resume-then-discard and discard-twice are one ticket, so they are one message); discard on a function value that is not a continuation; suspending during a discard's unwind. (Writing them a second time would be an uncorroborated copy: this document's gate runs the program and compares the output fence, and it does not read a table of prose.)

use std/io

ctl effect Ask {
  fn ask(n: Int) -> Int
}

type Held =
  | Ready(v: Int)
  | Waiting(k: fn(Int) -> Held)

fn plain(n: Int) -> Int = n

fn twice() -> Int = {
  with handle Ask { ask(n) resume k => k(n) + k(n) }
  ask(1)
}

fn escaping() -> Held = {
  with handle Ask { ask(n) resume k => Waiting(k) }
  Ready(ask(1))
}

fn spent() -> String !io =
  match escaping() {
    Ready(v) -> "resumed ${to_string(v)}"
    Waiting(k) -> {
      discard(k)
      match catch_panic(() => discard(k)) {
        Ok(_) -> "discarded twice"
        Err(e) -> e.message
      }
    }
  }

fn suspending() -> String !io = {
  with handle Ask {
    ask(n) resume k => {
      discard(k)
      "unreachable"
    }
  }
  with r <- bracket("r", tag => {
    let _ = ask(99)
    ()
  })
  "unreachable ${r} ${to_string(ask(1))}"
}

pub fn main() -> Unit !io = {
  match catch_panic(() => twice()) {
    Ok(v) -> io.println(to_string(v))
    Err(e) -> io.println(e.message)
  }
  io.println(spent())
  match catch_panic(() => discard(plain)) {
    Ok(_) -> io.println("discarded a plain function")
    Err(e) -> io.println(e.message)
  }
  match catch_panic(() => suspending()) {
    Ok(s) -> io.println(s)
    Err(e) -> io.println(e.message)
  }
}
dawn: continuation resumed twice
dawn: continuation discarded after it was already used
dawn: `discard` expects a continuation
dawn: a `ctl` operation was raised while a continuation was being discarded

Four more rules:

The two backends promise observational agreement and nothing more. The mechanism of freezing and resuming is deliberately left out of this specification: the JVM freezes the stack, native stops running that stack and switches to another, and that difference is intentional. What is promised is that one source program produces the same observable behaviour on both: the answers, the number and order of the releases, and the message and the position of a panic. The corpora that compare those byte for byte are scripts/spike-native/ctl_resume.dawn, ctl_nested.dawn and ctl_discard.dawn.

Boundaries (v1)

These are the v1 boundaries. "A written named effect" is no longer the reason for any of them; each has its own criterion.

Implementation (informative)

Each effect E makes lowering synthesise an ordinary record type (whose name the user cannot spell), with one field per operation holding its closure, plus one trailing env field: the evidence environment the arms run in, filled at the installation point. with handle constructs that record and binds it to a local; an operation call = read the field + call the closure, and the arm's evidence slot is taken from env rather than from the performing site.

There are two evidence conventions, and exactly one translation point.

A named call gives one slot per atom of the row. Every label written out in a signature appends one exactly-typed hidden evidence parameter to the function, placed after the dictionary parameters, in ascending effect id order; every signature-introduced effect variable appends one erased parameter; every associated-effect projection then appends exactly one erased parameter, after the labels' evidence, ordered by (subject, trait, member name), which the impl side's bridge restores to the concrete evidence record.

A function value always has exactly one slot. Whatever its row says, a function value's runtime arity is "the parameters written, plus one evidence slot", and a pure function value carries an empty pack there. A pack is an immutable chain of (key, evidence, outer) nodes addressed by atom key: labels, effect variables and associated projections take their keys from separate bands, so two rows meeting in one slot is a single cons and a query is a walk by key, with no reordering and no chance of a shifted slot. The rule for building a pack at a call site: every ground atom of the row (a written label, a projection already reduced to a label) conses one node on top of the non-ground environment the frame already holds; when the row has no ground atom and exactly one non-ground atom left, the pack is that slot, and nothing is allocated. A superset is harmless: lookup is by key, so a node nobody asks for costs one step. Only a missing key is an error.

The two conventions change hands in the wrapper lift_fn_value synthesises: each slot the named side wants is read out of the function value's single pack by key. Higher-order library functions (list.map and its ilk) take the "one non-ground atom left" path, forwarding as-is and building nothing.

The boundary clause: a value leaving the language carries a creation-point snapshot. Both conventions above put the supply point at the call, because the call is the only place a handler frame is known to be live. Once a function value has been converted to a Java functional interface (§9.4) there is no such place: the adapter is entered from a Java frame with no Dawn frame under it, and neither the moment nor the thread of the call is chosen by the language. So here, and only here, the value carries its own evidence: the conversion point builds the pack that is in scope at that point by the same rule as any other supply point, stores it in a field of the adapter object, and every entry Java makes hands it to the closure. The row is charged at the conversion like an ordinary call site, and an atom the scope cannot answer is still an error, so the snapshot is not a way of losing a label but a way of answering it at the last place an answer exists. Nothing about the rules inside the language changes: evidence is supplied at call sites, a snapshot is taken where a value crosses out, and the two meet only at that one step.

This is why union has no absorption (§6.6). Both conventions above read their shape off the effect row: the named side reads whether slots exist and how many, the function-value side reads which keys the pack should hold. So any row equation that deletes a label, a variable or a projection makes the static row and the runtime carrier disagree: a signature opens one slot fewer, or a pack is built one key short, while the reading side still looks the key up and finds nothing. That is the "effect evidence missing" compiler-invariant panic, on a program that checks clean. §6.6's absorption ban is the static half of the same fact.

One alternative is refused here explicitly: let the runtime fall back to a dynamic lookup by label whenever a slot is missing, so that absorption would cost performance and not correctness. Not adopted. It trades the invariant "an atom the row states has a place in the carrier" for a fallback path, and a fallback path runs only on the programs that happen to be short a slot, so the part nobody tests is exactly the part that is unsound; lookup would also become two semantics instead of one walk by key. The invariant stands.

6.6Row equivalence and normal form

An effect row is built from four kinds of atom: the base axis's io, effect variables (§6.3), associated-effect projections (§6.5), and the label axis's named effects. pure is the row with no atoms, written !(); it goes anywhere !io goes (a signature's row, a function type's row, an effect argument, an impl's associated-effect binding), and means what leaving the annotation off means. pure is not a spelling for that row: it is not a keyword, so written into a row it becomes an ordinary effect variable, and an effect variable is solved by any row at all. !pure is therefore an error (§6.3).

Row equivalence is generated by and only by the five rules below.

  1. Union is componentwise: the union of two rows is a boolean or on the io bit and plain set union on each of the three sets (effect variables, associated-effect projections, named labels). Hence | is commutative, associative and idempotent, and pure is the identity. Stacked annotations equal one union: !Ask !io is !(io | Ask).
  2. The normal form is the smallest shape: on the base axis, all components empty is pure, io alone is !io, no io and a single base atom left is that atom itself, and anything else is the union of those components; an empty label set carries no label layer, and a non-empty one is that base row plus those labels.
  3. The normal form has a settled order: effect variables in introduction order (first appearance within the signature, with explicit binders taking the front in the order written), associated-effect projections by (subject type parameter, trait, member name), named labels by effect id. That order is also the evidence slots' layout order (§6.5 "Implementation"). Rendering is a separate matter: printed atoms are sorted by name, so !io !e prints as !(e|io).
  4. Projections reduce through the impl: once the subject is settled, an associated-effect projection is replaced by the row that impl binds, and the result is normalised again by the rules above. A ground row contains no projection.
  5. Two rows are equivalent exactly when their normal forms are equal.

An equation not written here does not hold. In particular: union has no absorption law. !(io | Ask) and !(e | io) are normal forms that do not move, and any reading that equates them with !io is not a consequence of these five rules; it is a sixth rule being added.

Union does not distinguish effects that occupy an evidence slot from environment effects. io is an environment effect and occupies no slot of its own (§6.5 "Implementation"). That is not a reason for it to absorb !e: !e can be instantiated to a named effect that does occupy a slot, whether a slot exists is known only after instantiation, and union is computed before it. This is the clause most easily argued away in reverse ("io takes no slot, so what does absorbing cost?"), so it is written as a clause rather than a comment: what would be absorbed is an atom, not a slot.

Containment is a separate relation and takes no part in equivalence. !io covers pure, io and effect variables (including unions of them); named labels and associated-effect projections are judged by exact set containment, where !io covers neither !Ask nor !C.E. The division of labour is sharp:

Row subtraction is the one exception to "atom for atom". When a function value goes into a parameter of the form !(e | R), where e is the only effect variable the callee's signature binds and R is the set of concrete atoms in that row (named labels, io, associated-effect projections), then e is bound to S \ R, where S is the argument's row, and the argument is accepted. A parameter written !(e | io) therefore takes a closure that both does io and raises a named effect; before this rule the only spelling that took one was the bare !e.

The step carries a co-occurrence precondition: every row in the callee's signature that mentions e must also write down every atom of R. Every solution of !(e | R) ~ !S agrees on the rows that contain R, so which one was chosen can be observed only from a row that mentions e without R. Where the signature has no such row, e := S \ R is the only observable answer and choosing it costs no principality. Where it has one, any choice would be a choice made on the caller's behalf that the caller never wrote, so the argument is still refused, and the diagnostic names the occurrence that makes the choice observable.

Where one call passes several function-value arguments through the same e, each argument's residual S_i \ R is joined (the least upper bound on this lattice) into e's binding: neither the first argument nor the last one wins. This is what a bare !e parameter has always done, and two spellings of one parameter row do not answer differently.

The step carries a companion condition: e is looked for on each parameter's unsubstituted declared row. Once an earlier argument has bound e, the substituted row has no variable left to find.

The argument's row need not contain R. Where S is short of R, S \ R is S with atoms taken off it that it never had, and e is bound to that and the argument accepted. This is safe for the same reason widening upward is free: the call site builds the pack from the instantiated row rather than from the argument's own row, and the pack is read by a key chain rather than by index. A closure short of its slot is therefore handed a superset, and the extra keys go unread.

The other shapes are unchanged. The other direction is still refused: an atom in the argument's row that the slot does not have is the atom-for-atom clause above, which this section does not touch. A row with two or more effect variables is still refused as well: the remainder has no principal split between them, and this specification does not invent one.

7.comptime

7.1Form

const CRC_TABLE: List[Int] = comptime { crc32_table() }

fn lookup(d: Int) -> Float =
  SIN_TABLE.get(d % 360).expect("table covers 0..360")

comptime { ... } is an expression: it is evaluated at compile time by the compiler's built-in interpreter, and the result is embedded in the output as a constant. The right-hand side of a top-level const is implicitly in a comptime context.

7.2Constraints

  1. comptime code must be pure (it may call any pure function, including those of this module and of dependency modules).
  2. The result type must be constant-serialisable — that is, the compiler can rebuild the value at class initialisation time: Int/Float/Bool/String/Unit, plus List/tuples/records/ADTs made only of those. Function values are not allowed. An opaque type is as serialisable as its target (§2.7), with one exception: std/cursor's Cursor is not. Its Int is an offset into the backend's own representation of the string (UTF-16 code units on the JVM, UTF-8 bytes on native), and a constant is folded once and written into the Core both backends read, so a folded position holds for at most one of them. To compute a position at compile time, hold the string and walk to it where it is used. This exception is a corollary of §11's "the measure never becomes an observable value", not the whole of it: rendering is shut off too, or const S: String = to_string(c) would go around this clause and fold the measure into the artefact as a string (and the interpreter counts code points, so that would be a third answer again). The exception comes off once cursors have a single currency. Map/Set are not allowed for now: they are HAMTs over Array, and the comptime interpreter has no Array primitive; List works because the interpreter carries its own list representation, not because it can run std/pvec. Bytes is not allowed either, for the same kind of reason: the interpreter's value type has no byte-string case, so a Bytes value has nowhere to live at compile time, and the std/bytes primitives are refused at comptime across the board. That Bytes has Eq/Hash/Show does not change this; whether a type can be a constant asks whether the interpreter can hold it, not which traits it supports. To prepare byte data at compile time, compute a List[Int] or a String and turn it into Bytes where it is used.
  3. Evaluation has a step budget (10⁸ steps by default, tunable with --comptime-fuel); exceeding it is an error — which guarantees compilation always terminates. A primitive whose output grows with its input is charged by the size of what it produces, before it allocates: a String ++ by the code points of its result, a List ++ by the elements of its right operand (the left one is shared, see §2.2), and range, list slicing, join, code_points/from_code_points, case mapping, string slicing and quoting by the elements or code points they produce. The budget so bounds memory and the time of one step as well: doubling s = s ++ s pays the length of its result each time, not a few steps. A count too large for an Int (a range whose ends are further apart than an Int can say, for instance) is over any budget, not zero.
  4. There is no Java interop and no io inside comptime (constraint 1 guarantees this automatically).
  5. Pure does not mean foldable: some pure builtins are refused at comptime too, because the values they operate on are ones the interpreter cannot represent (the Array, Bytes and Map/Set mentioned above), or because the answer they would fold belongs to the build rather than to the program. Which ones is looked up per function, not enumerated here: dawn doc --builtins gives every compiler builtin's entry a "comptime" field whose value is "ok" or "refused". The flag is taken from the list the interpreter actually refuses, and a gate holds it, in both directions, equal to the interpreter and to the # comptime: rejected markers in selfhost/builtins.dawn. A std function written in Dawn carries no such field: whether it folds depends on which builtins its body reaches, and when a constant fails to evaluate the error names the refused one along the call chain (dawn check shows it).

7.3Explicitly out of scope

comptime cannot generate types, cannot generate declarations, and cannot introspect the AST. It is only "run a piece of pure Dawn code ahead of time". This specification provides no metaprogramming facility.

8.Error handling

8.1Recoverable: Result / Option + ?

fn parse_config(path: String) -> Result[Config, String] !io = {
  let text = read_file(path)?          # on Err, return that Err early
  let json = json.parse(text)?
  Config.from_json(json)
}

Across error types: write a local helper, don't wait for the language to give you one. ? requires E to agree, so a function returning Result[_, HttpError] cannot ? a Result[_, String] directly. The fix is a 4-line function at the boundary:

fn as_http[T](r: Result[T, String], status: Int) -> Result[T, HttpError] =
  match r { Ok(v) -> Ok(v)
            Err(m) -> Err(http_error(status, m)) }

After that let rows = as_http(repo_call(...), 500)? is all it takes, and ? handles the rest.

A map_err was once added to std for this, and reverted on 2026-07-19: of the 102 cross-layer matches in dawnop-site, 94 came apart with "? plus the helper above" (another 8 already had the same error type and needed no helper at all), and the entire effect of map_err was to shrink that helper from 4 lines to 1, once per project. What actually untangled those 102 sites was ? and a local helper, not a new library function.

? inside a lambda returns from that lambda, so bridges inside closures can collapse the same way.

8.2Unrecoverable: panic

panic(msg, at: Loc = caller()): prints panic: <msg> at <at> to stderr; the process exits non-zero. No stack is printed. An omitted at is the location of this call; a function that reports a failure on its caller's behalf passes its own at on (§8.4). todo(at: Loc = caller()) is equivalent to writing panic("not yet implemented") in the same place, and passes any type check (its return type is the bottom type Never).

Location suffix: when panic, todo, expect, postfix ! or assert (§3.4) fails, the message ends with the location of the call, at <path>:<line>:<col>, filled in by the compiler at compile time from the call site:

Postfix !: o! unwraps Option[T] into T, and panics on None. The semantics are those of expect(o, msg); the only difference is that the message is generated by the compiler — it contains the call that produced the None and the source location (unwrapped None from URI.create() at src/http.dawn:23:13), so there is no need to invent a placeholder string for it.

let uri = URI.create(url)!                      # instead of .expect("uri")
let base = HttpRequest.newBuilder()!.uri(uri)!  # instead of .expect("b") / .expect("b-uri")

The reason ! exists is exactly §9.2: Java wraps every reference return in Option, while the vast majority of JDK methods never return null in practice, so unwrapping is the normal case.

get/map.get return Option (enquiry); the subscript c[i] panics on an out-of-range index or a missing key (assertion, §4.8; the semantics are fixed by that type's Index impl, List/Map as above); Int division by zero (/ and %) panics — being a panic, catch_fault does not intercept it (§4.3, numeric edge semantics).

8.3Debug output: dbg

dbg[T: Show](x: T) -> T returns x unchanged and writes one line to stderr:

[<path>:<line>:<col>] <the argument's source text> = <show(x)>
let n = dbg(a * 2)        # stderr: [src/main.dawn:4:11] a * 2 = 8
let m = xs |> len |> dbg  # stderr: [src/main.dawn:5:11] xs |> len = 3

8.4Caller location: caller() and Loc

A function that reports a failure on its caller's behalf takes the line that called it through a parameter whose default is caller():

fn assert_eq[T: Eq + Show](a: T, b: T, at: Loc = caller()) -> Unit =
  if a != b { panic("${show(a)} != ${show(b)}", at: at) }

fn sums() -> Unit = assert_eq(1 + 1, 3)   # panic: 2 != 3 at src/t.dawn:4:21

9.Java interop

9.1Importing and calling

use java "java.nio.file.Files"
use java "java.nio.file.Path"
use java "java.lang.StringBuilder"

fn slurp(p: String) -> Option[String] !io =
  Files.readString(Path.of(p).expect("valid path"))

fn build() -> String !io = {
  let sb = StringBuilder.new()      # constructors are always spelled .new
  sb.append("a")
  sb.append("b")
  sb.toString().expect("non-null")
}

9.2Type mapping

DawnJavaDirection
Intlong (an incoming int is widened automatically)both ways
Floatdoubleboth ways
Boolbooleanboth ways
Stringjava.lang.Stringboth ways
Unitvoidreturn
an imported class Ta reference to that classboth ways

A Java method returning a reference type is always Option[T] — null is stopped at the boundary. Unwrap with ! (§8.2) or handle it with match:

use java "java.net.URI"
use java "java.lang.StringBuilder"

pub fn main() -> Unit !io = {
  let uri = URI.create("https://dawn-lang.org/spec")!   # method: wrapped in Option, unwrapped
  let sb = StringBuilder.new()                          # constructor: not wrapped, the object itself
  sb.append(uri.getHost()!)
  println(sb.toString()!)
}
dawn-lang.org

Why methods are wrapped and constructors are not — these are not two arbitrary rules; each has its basis:

Primitive return values are not wrapped in Option; a short/byte/int return is widened to Int automatically, float to Float. char in argument and return position is currently unsupported; arrays go through as opaque values (§9.5). Passing null for an Option argument is unsupported as well (Dawn currently cannot pass null to Java).

9.3Overload resolution

A unique candidate is picked by scoring on "argument count + static type" (an exact match on long/double beats narrowing to int/float, String beats CharSequence/Object); a tie for the highest score, and no candidate at all, are both compile errors (the message lists the candidate signatures). A function-value argument only matches a functional-interface parameter (§9.4); a Dawn List argument can match a List/Collection/Iterable parameter (§9.6); an exact array match beats widening to Object (§9.5).

Varargs follow the JLS in two phases: one round without packing first (phase 1), and only if all of that fails, packed as varargs (phase 2); phase takes precedence over score — the score is summed per argument and grows with the argument count, so without phases a packing candidate would overtake an exact match. The variable part is spread out inline, as it is written in Java:

use java "java.nio.file.Path"
use java "java.util.List"
use java "java.lang.String"

pub fn main() -> Unit !io = {
  let p = Path.of("a", "b")!                     # one trailing segment: packed into String[1]
  let q = Path.of("a", "b", "c")!                # same phase, String[2]
  let l = List.of("a", "b")!                     # phase 1 wins: of(E, E) is chosen
  let m = List.of("a", "b", "c")!                # phase 2: packed into E[]
  let e = List.of()!                             # no variable part = pack 0 = empty array
  println("${p.toString()!} ${q.toString()!}")
  println("${String.join(",", l)!} ${String.join(",", m)!} ${to_string(e.size())}")
}
a/b a/b/c
a,b a,b,c 0

The variable part takes Java references too (BodyPublishers.concat(head, file, tail)!). The trailing arguments are scored one by one against the array component type, by the same rules as an ordinary parameter, so SAM conversion (§9.4) and the List bridge (§9.6) are equally available inside the variable part. Passing a ready-made array as the variable part (a String[], say) goes through phase 1 and is passed as is, not repacked. Note that scalars are not boxed (§9.2), so Object... takes String and Java references but cannot take Int/Float/Bool; char is unsupported in argument and return position, and char... with it.

9.4SAM conversion: function values across the boundary

use java "java.lang.Thread"

fn spawn_hello(msg: String) -> Unit !io = {
  let t = Thread.new(() => println(msg))   # Dawn lambda → java.lang.Runnable
  t.start()
  t.join()
}

9.5Arrays: opaque pass-through; byte[] = first-class Bytes

An array value is treated the same as an unimported reference class (§9.1): it can be received, held and passed on — overload scoring matches the array type exactly, or widens to Object; in return position it is wrapped in Option per §9.2. But an array (except byte[], see below) is unnameable (the type cannot be written in a signature), cannot be created and cannot be indexed; for its length use Array.getLength(a) from use java "java.lang.reflect.Array".

byte[] is the one exception: it is the first-class type Bytes (§9.5.1). A concrete byte[] returned by a Java method (readAllBytes/toByteArray/Base64.decode /MessageDigest.digest) lands as Option[Bytes] per §9.2; Bytes can be written in a signature, stored in a record, sliced/indexed/concatenated/compared by content; passed back the other way it matches a Java byte[] parameter (OutputStream.write, MessageDigest.isEqual and so on) directly.

use java "java.nio.file.Files"
use java "java.nio.file.Path"

fn slurp(p: String) -> String !io = {
  let bytes: Bytes = Files.readAllBytes(Path.of(p).expect("path")).expect("readable")
  decode(bytes, "UTF-8")
}

9.5.1Bytes: a first-class immutable byte sequence

Bytes is an immutable sequence of bytes, at runtime a bare byte[]. The library functions (§11, the "bytes" group): utf8(s) -> Bytes (the UTF-8 bytes of a string), decode_utf8_lossy(b) -> String / decode_latin1(b) -> String (decoding, see §11), decode_utf8_checked(b) -> Result[String, Utf8Error] (strict decoding, see §11), len(b), bytes.at(b, i) -> Int (0..255, out of range panics), bytes.slice(b, start, end) ([start,end), subscripts clamped into range), bytes.index_of(b, needle, from = 0) -> Option[Int]. index_of clamps a negative from to zero; a non-empty needle is searched from that byte offset for its first complete match. An empty needle matches at every valid position in [0, len(b)] (so from == len(b) returns Some(len(b))), but from > len(b) returns None even for an empty needle. Bytes ++ Bytes concatenates, ==/!= compare by content (Show renders a <N bytes> summary). The hash of Bytes is a content hash (seed 1, byte by byte h = 31*h + the signed byte, wrapping at 32 bits, see §3.5 — the same shape as the composite rule there), consistent with == on content, so Bytes can be a Map/Set key. (It was once forbidden because the JVM hashCode of byte[] is reference identity; after both ends were changed to content the ban did not get withdrawn along with them, and was withdrawn on 2026-07-27.) Bytes does not take part in comptime constant folding, and cannot be a bare first-class function value either (wrap it in a lambda).

An erased Object may be claimed only explicitly. The return of an erased generic (§9.2) lands as an opaque Object. Overload resolution uses that static type only through ordinary Java assignability: it can be passed to an Object parameter, but it cannot match a concrete reference parameter such as Path, InputStream, or byte[] in the other direction. The compiler inserts no hidden CHECKCAST at the argument bridge; the same conversion cannot fail as a value when written explicitly but escape through a host exception when inserted implicitly.

If you know for certain that some opaque Object from an erased generic is at runtime a particular concrete reference type (such as byte[] when HttpResponse.body() is paired with BodyHandlers.ofByteArray()), use the generic builtin cast[T](x: Object) -> Result[T, ForeignError] to claim it as that type (T is taken from the expected type at the call site, e.g. let b: Result[Bytes, ForeignError] = cast(...)) — the claim does one runtime check, and a type mismatch is an Err, not an exception passing through; for the payload see §9.8.1 (on the JVM the kind is java.lang.ClassCastException). T must be a reference type (a primitive, or no expected type, is rejected at compile time). Java array or parameterized targets that cannot currently be named in Dawn get no implicit exception either; when a real use case needs one, the surface must first gain a writable target type.

A function with a pure signature should not be able to exit through a host exception (LANG-02) — cast used to throw ClassCastException, which is exactly the exit a pure signature is supposed to exclude. Failure is now a value. The three stages the migration went through (including a transitional spelling that lived for exactly one release) are recorded in `error-model-design.md` §6.10–§6.12, and it is closed.

9.6The List bridge: a Dawn List reaches a collection parameter directly

When a Java parameter is declared java.util.List / java.util.Collection / java.lang.Iterable, the argument may be a Dawn List[T]. The bridge is a copy, not a view: a Dawn List is a pure-Dawn persistent vector (std/pvec) that Java has no name for, so every crossing copies the elements, in order, into a fresh java.util.ArrayList and hands Java that list wrapped in an unmodifiable view (Collections.unmodifiableList). The mutating methods on the Java side throw UnsupportedOperationException; a reference Java keeps sees none of the versions the Dawn side makes afterwards.

9.7Limits

Java classes cannot be inherited from; Java interfaces cannot be implemented as a named class — handing a function value out through SAM conversion (§9.4) is the only path. Read-only static fields are accessible (Class.FIELD, §9.1) — enum constants and static constants are read directly (TimeUnit.SECONDS, Integer.MAX_VALUE); writing a static field, and instance fields, are still unsupported. Arrays cannot be created, indexed or named (§9.5); Map/Set are not bridged, and Java collections are not converted back into Dawn values (§9.6); passing null for an Option argument is unsupported (§9.2).

9.8The foreign-failure barrier: catch_fault

Up to v0.30.0 this builtin was called java_try; v0.31.0 renamed it. What it intercepts is a fault — a failure caused by the outside world — and ever since native grew failure kinds that classification has been shared by both backends (`native-backend-plan.md` §14.9) and has nothing to do with Java; the name outlived its reason by a while. The old name's migration hint was withdrawn together with the std/moved.txt mechanism (`std-moved-design.md`), so writing java_try today gets the ordinary undefined-function diagnostic.

Dawn has no exceptions: an exception thrown by a Java call passes through unchanged by default and terminates the program (panic semantics). But an expected foreign failure (the network drops, a SQL constraint is violated, a parse fails) is expressed in the Java world as an exception; those are not bugs and belong in a Result. The builtin catch_fault is the one conversion point:

use java "java.lang.Long"

fn parse(s: String) -> Result[Int, ForeignError] !io =
  catch_fault(() => Long.parseLong(s))
  # Err(ForeignError { kind: "java.lang.NumberFormatException", message: ..., cause: None })

The companion catch_panic[T, !e](f: fn() -> T !e) -> Result[T, ForeignError] !e has the same shape: the protected closure's row is the whole call's row, and the barrier adds no effect of its own (the end of §9.8.1 puts the three barriers side by side). It intercepts two kinds, a Dawn panic (PanicError) and Exception — not any Throwable: VirtualMachineError (heap exhausted, stack overflow) passes through, resource exhaustion is not a value. It is for a supervision boundary — one request on a server, one execution of a task runner: a panic in one request should become a 500 and be logged, rather than take down the whole connection or process. Its division of labour with catch_fault is clear: catch_fault handles expected foreign failure and lets panics through; catch_panic is an isolation point. Ordinary business failures still go through Result — do not use catch_panic as routine error handling.

This division of labour is backend-independent. The JVM gets it for free from the class hierarchy (Error versus Exception); native has no exceptions, every failure travels the same longjmp, so a failure carries a kind and a handler remembers whether it takes panics. The criterion is one and the same: a failure the language defines itself is a panic (panic, expect, an out-of-range subscript, division by zero, an illegal code point), a failure caused by the outside world is not (the io primitives — counted up, that is the only such class). The measured comparison of the two backends is in scripts/spike-native/catch_kinds.dawn; before it was written, native's catch_fault intercepted every panic that should have passed through.

9.8.1The payload ForeignError

"Match the string by prefix" used to be this section's advice and is now withdrawn: it builds control flow on one piece of text that can be refactored, localised, or changed by the next JDK. The payload is a prelude record:

type ForeignError = { kind: String, message: String, cause: Option[String] }

The payload contract (on every backend):

There is only this one pair of barriers (only this pair intercepts failure; the bracket of §9.8.2 intercepts nothing), only the ForeignError payload, and the String version is not kept.

This pair's effect row is one row: the protected closure's, with nothing added by the barrier. The promise of a pure function is the same arguments give the same value, within one program and one build (§6.2 rule 4), checked against which failure is observed:

So the three barriers share one row: the bracket of §9.8.2 observes nothing, catch_fault observes a failure io has already been charged for, and catch_panic observes one its arguments decide. All three carry the variable.

The line rests on an invariant: a fault only comes from io. It used to carry one named exception: a continuation's row was once unconditionally pure, so a function with a pure signature that resumed or discarded one brought the remainder's io, and its faults, back into its own frame (both backends were measured doing this). Since 2026-09-02 a continuation carries its remainder's io bit (§6.5 "Control arms"): a remainder that can fault hands out an !io continuation, no pure frame can call it, and the exception is gone. k is still an ordinary function value with no type of its own; what changed is the io bit of its row and nothing else (`docs/oneshot-design.md` §11.2, postscript). The one shape left is a remainder whose only effects are labels, where a label's arm does io at its own installation point: that is the standing supply-point doctrine (the boundary clause under §6.5 "Implementation", the same one the SAM snapshot rests on), the arm's io is charged to the frame that installed it, and it is not an exception to this clause.

The full argument, and the condition under which it reopens, is in `docs/audit/error-model-design.md` §7.

History: moving the payload from String to ForeignError took three releases, because a builtin's signature is bound by seed discipline just as its name is, and more tightly — a rename can have both tables know two spellings within one stage, a payload type cannot: the compiler's own call sites cannot satisfy a Result[T, String] table and a Result[T, ForeignError] table at the same time. So the new shape landed first under the transitional spellings catch_fault_e/catch_panic_e with zero call sites (v0.32.0); one release taught the previous generation of the compiler about them; the call sites moved and the entries under the original names were flipped (v0.33.0); then the call sites moved back to the original names and the transitional spellings were deleted (this release). That pair of names appeared in dawn doc --builtins for v0.32.0/v0.33.0 and does not exist after that. The staging is in docs/audit/error-model-design.md §6.

9.8.2Releasing, not intercepting: bracket

Dawn has no try/finally, and does not intend to (the pair of barriers in §9.8 intercept, they do not release). "Whichever way you leave, hand the resource back" is carried by a third builtin:

fn bracket[A, B, !e](resource: A, release: fn(A) -> Unit !e, body: fn(A) -> B !e) -> B !e

The third parameter is named body: use is a keyword, so the call bracket(r, close, use: f) cannot be written at all, and that spelling never had a caller -- it only ever appeared in the rendered signature.

let f = FileOutputStream.new(path)          # acquire the resource: ordinary code, before the call
bracket(f, s => s.close(), s => write_all(s, bytes))

The resource is a value, not an acquire closure. Haskell's bracket takes a thunk in order to close the window for asynchronous exceptions — another thread or a timer could interrupt between "acquired" and "handler installed". Dawn has no such thing: a failure is only raised from code the program itself calls, and between evaluating the arguments and this builtin installing its handler none of the caller's code runs, so a thunk closes no window at all (Koka's finally is the same, and likewise takes the resource directly). Acquiring the resource is therefore ordinary code before the call — a failure there needs no release, because nothing has been acquired yet.

It comes last to leave the road open for with (§4.10, landed 2026-07-31): that sugar attaches "the rest of the block" as the last argument, so a primitive holding it in the middle would have to be respelled. Once the resource is acquired up front, such a site does not need a single lambda:

with f <- bracket(open(path), close)
...the rest of the block is the body...

Three guarantees:

It gets no surface syntax like defer: the protected region is always one closure call, so return/?/break cannot cross out of it at the language level, and the compiler owes no escape rewriting. The criteria, and the earlier conclusion they overturned, are in docs/core-move2-design.md §2.6 and §6.

10.Module system

10.1Files and module paths

One .dawn file = one module. The module path = the path relative to the module root with the extension dropped: <root>/json/lexer.dawn → module json/lexer. Every segment of the path must match [a-z_][a-z0-9_]* (the same as the file name), otherwise it is a compile error.

How the module root is determined:

The directory convention is the project definition: the module root, the entry and the module paths are all decided by the directory structure; no manifest file is needed.

A project may optionally carry a dawn.toml, which holds only what the directory convention cannot express — project identity and dependencies. A project without one works exactly as described above. The contents of schema 1:

schema = 1                                      # must be the first key
name = "backend_dawn"                           # project identity ([a-z_][a-z0-9_]*)

[java-deps]                                     # Maven deps, for `use java`
sqlite = "org.xerial:sqlite-jdbc:3.36.0.3"      # exact coordinates; no SNAPSHOT, no ranges

[deps]                                          # Dawn source packages: alias = local dir
web = "../packages/web"

[deps.json]                                     # or a remote archive (zip / tar.gz)
url = "https://github.com/dawnop/dawn-lang/archive/refs/tags/v0.7.0.zip"
version = "1.0.0"                               # strict x.y.z; version solving = MVS
hash = "d1:<sha256>"                            # content hash of the unpacked file tree
subdir = "packages/json"                        # package root inside the archive (optional)

An alias in [deps] is only how this side's source spells it (use <alias>/<module>); a package's identity is the name in its own manifest — the class-name namespace, version solving and one-name-one-copy across the whole program all go by the real name, and an aliased import is normalised to the real name at load time. dawn add <coordinate|url|path> can write these entries for you (fetching the archive and computing the hash, preserving hand-written formatting).

One-name-one-copy compares directories: a path dependency reached through a symbolic link and through its real path is one directory, and so one package (directories are compared by their physical path with links resolved, falling back to the lexical spelling for a path that does not exist), and a .. steps to the physical parent, as the kernel does. Module paths are not affected and stay the spelling below the module root: a link inside src/ gives one file two module paths, and those are two modules.

dawn check|doc|run|test|build fetches [java-deps] (including those declared by each dependency package — the union) for compile-time use java resolution. Each target of check/doc gets an independent classpath; run/test/build instead merge it with --cp and use the result for both compilation and execution. dawn build additionally copies [java-deps] into a lib/ next to the jar. The repository address comes from $DAWN_MAVEN_MIRROR and does not go into the manifest.

A manifest is always data, never code — there is no executable build.dawn. The reasoning and the full design are in `package-design.md`.

10.2Imports

use json/lexer                 # whole-module import; alias = last segment lexer, qualified access lexer.next(...)
use json/lexer as jl           # explicit alias, qualified access jl.next(...)
use json/value.{Json, render}  # selective import, used unqualified
use java "java.lang.Math"      # Java interop (§9), form unchanged

10.3Name resolution (disambiguation rules)

10.4Visibility

All declarations are module-private by default; pub exports fn/type/alias/const/trait/effect (pub type brings the constructors and fields with it, see §3.3). Accessing or importing a non-pub item → error (`parse` is private to module json/parser, with a hint: add pub). A non-pub item of the standard library is the exception: std is not the user's to edit, so the error says the item is not part of std's public API (`atoi` is not part of std's public API (`std/fmt` declares it privately)) with no "add pub" hint (#296). An exported declaration must not leak a private type, trait or effect that cannot be named outside the module either; the full rules for transparent aliases, the opaque boundary, public traits/effects and reachable impls are in §3.3, and the error is reported at the declaration rather than at the use site.

Package visibility pub(pkg) (2026-09-24, design): there are three visibility levels — module-private (nothing written), pub(pkg), and pub. pub(pkg) may be written everywhere pub may, and means the same except for the boundary: a pub(pkg) declaration is visible to every module of the same package (one dawn.toml unit) and invisible outside it. A package is one source unit as the loader sees it: the project being checked (with or without a dawn.toml), each [deps] source package (by the real name in its manifest), and the bundled standard library as a whole. Importing or qualified access to a pub(pkg) item from outside the package → error (`seam` is package-private to package `web`).

Load scope (2026-07-30, LANG-07): dawn run/test/build <dir> loads every module under src/ by default — modules that are never referenced are checked too (bit-rot protection, and that is the right default). --closure narrows it to "the use closure of the entry src/main.dawn", for large projects producing an artifact; dawn check is always whole-repo. Recommended for CI: dawn check guards the whole repo and dawn build --closure produces the artifact. dawn check exits 1 on any diagnostic (§12.1), so the exit code alone is enough to act on that recommendation.

10.5Compilation units and evaluation order

10.6The bundled standard library and the prelude

The standard library is Dawn source bundled with the compiler, organised as real modules (`stdlib-naming.md`). The bundled modules are exactly these, one for one with the compiler's own list std/modules.txt (scripts/doc-check.py holds the two together; one module too many or too few fails it):

std/hamt and std/pvec are internal modules — the representations of Map/Set/List (§11). They are bundled along with std and reference each other inside std, but use std/hamt / use std/pvec outside std is a compile error: the representation has to be replaceable wholesale, and being replaceable requires that no program depends on it. (std/fmt is where number rendering and parsing are implemented — fmt.dtoa is to_string(Float) (§4.3); the implementations of the three parse_* (the EBNF in §11) are not exported, the builtin spelling is the only way to write them, and fmt.atoi/fmt.atod/fmt.atoi_radix are not names you can write. The module name exists because the implementation is a piece of ordinary Dawn source rather than some backend's host method, not because it is an API layer.) use std/x resolves to a resource inside the compiler jar rather than to disk (the src/std/ path on disk is reserved; putting a file there is an error); after that it behaves exactly like an ordinary module import — qualified access map.insert(m, k, v), selective import use std/list.{find} (§10.2/§10.3). The same short name can coexist across modules (str.at / bytes.at), disambiguated by qualification or by selective import.

The prelude is the high-traffic core of that, implicitly available without a use: the constructors of List/Option/Result, println/print, map/filter/fold, the sort family (std/list), parse_int (std/fmt), and the builtin panic/todo/caller/bracket/catch_fault/catch_panic/ discard/dbg/expect/unwrap_or/to_float/to_int/to_string/get/range/ sort_by/join/parse_float/code_points/ from_code_points/char_is_letter/char_is_digit/char_is_alnum/char_is_upper/ char_is_lower/char_is_space/args/cast, all within one screen (for the full set see the standard library reference, generated by dawn doc --stdlib).

A top-level declaration may shadow a builtin/std function name (§10.3, Rust-style): the resolution order is this module's declarations → std → builtins, and it is exactly this rule that makes the std module's own pub fn len legal. The method names of prelude traits get the same treatment: they enter the function namespace along with the prelude (for which names, see the "built-in traits" section of the standard library reference; the normative definition is in §3.5), and may be shadowed by a declaration in this module — it is not an error at declaration time. Only that spelling is shadowed, the trait itself is unchanged — impl Show[T] is declared and found as usual, and ${...}, ==, for..in still find their impl by trait (§10.3).

Adding to the prelude is compatible: adding a name to the prelude cannot make any program that already checks fail — the new name is either unused or shadowed by a declaration in that module. This is the precondition for the prelude being able to evolve (`prelude-namespace-design.md`).

The flat spellings from before modularisation (map_insert, str_len and so on) are no longer in the public namespace — only the prelude and module qualification are left; write an old spelling and the error tells you which module it moved to. The history is in `stdlib-naming.md`.

11.The standard library (semantics and criteria)

This section is not a listing. Which functions there are, what the signatures look like, how to use each one — the full set is in the standard library reference, generated straight from the compiler by dawn doc --stdlib and therefore never out of step with the implementation. Copying it out by hand into the specification would only rot: what this section keeps is the half a listing cannot answer — what input is accepted, what happens at the boundaries, why the trade-off is this one.

Where something is implemented is invisible to the user. These names come from two places: the compiler's builtin table, and the std/ modules bundled with the compiler (Dawn source, §10.6). Prelude names are implicitly visible; the rest are imported with use std/x and called qualified as x.fn(...). Which side implements a name (builtin or std wrapper) affects neither its spelling nor its semantics (`docs/builtins-to-stdlib.md`).

The textual form of numbers. The language accepted by parse_int / parse_float is this EBNF, enforced by std/fmt's own scanner (the two backends no longer each delegate the grammar to a host parser; the host only does the decimal→binary correct rounding after parse_float has validated, IEEE 754 round-to-nearest-even — on that subset strtod and Double.parseDouble are the same function). Leading and trailing whitespace is trimmed first according to Dawn's own whitespace table (the same char_is_space table str.trim uses, not the host's):

int    = [ "+" | "-" ] digit { digit }                    (* digit is ASCII 0-9 only *)
float  = [ "+" | "-" ] mant [ exp ] | "Infinity" | "-Infinity" | "NaN"
mant   = digit { digit } [ "." { digit } ] | "." digit { digit }
exp    = ( "e" | "E" ) [ "+" | "-" ] digit { digit }
radix  = [ "+" | "-" ] rdigit { rdigit }

parse_int(s, radix: r) (radix defaults to 10) uses the radix production: rdigit ∈ 0-9 a-z A-Z (value = 10..35, upper and lower case have the same value), and a digit whose value is ≥ radix is rejected; a radix outside 2..36 answers None. At radix 10 it is the same language as int. Before 0.83.0 the radix version was a separate builtin, parse_int_radix, now folded in. An integer outside the 64-bit range is None, not wrap-around. Deliberately excluded (things today's host parsers do accept and Dawn rejects across the board): underscores, the 0x prefix and hexadecimal floats (0x1p3), the f/F/d/D suffixes, lower-case variants such as inf/nan, a signed NaN and +Infinity (the legal special spellings are exactly the three to_string can emit, see the round-trip closure in §4.3), and non-ASCII digits such as the full-width and Arabic-Indic ones (the host's Character.digit accepts them; Dawn's digit set is closed over ASCII).

The accepted language belongs to the function, not to how it is called: after let f = parse_float, f(s) and parse_float(s) are the same function, and likewise for parse_int -- except that as a value it loses its default (§3.1): let g = parse_int has type fn(String, Int) -> Option[Int]. Up to v0.79.0 a call through a function value bypassed this EBNF (f("1.5d") answered Some(1.5)), and taking parse_int as a value panicked at compile time; that was an implementation defect, fixed as a bug rather than as a language change (issue #283, builtin-fn-value-lowering-design.md).

Case mapping. str.to_lower/str.to_upper are the Unicode simple (1:1) case mappings: one code point in, one code point out, no locale, no context, so the code point count does not change. That rules out the three kinds of special case in full mapping — the ones that change length (ß → SS), the locale-dependent ones (Turkish i) and the context-dependent ones (Greek final sigma). Taking the simple mapping is not about saving effort: full mapping is not a function a backend can implement from one table, and Dawn requires a primitive to be the same function on every backend. Cases that need full mapping belong to a library that can take a locale.

That table belongs to the compiler (selfhost/src/embed/unicode_case.dawn, a generated file that records the JDK which generated it), and the two backends each take a copy of their own: the JVM one is written into dawn/rt/Strings, the native one into the emitted C. So the answer str.to_upper gives does not move with the host JDK's Unicode version — upgrading to a new Unicode is the one explicit act of regenerating this table, not a silent change of answer because you compiled on a different machine. Classification (char_is_*) works the same way; its table is selfhost/src/embed/unicode_class.dawn.

A character is a code point. code_points(s) -> List[Char] splits into characters (a supplementary-plane surrogate pair merges into a single code point) and from_code_points(cs: List[Char]) assembles from characters; len(s) is the code point count, str.at returns a Char, and the one that returns List[String] is str.chars. Indexing into a string is always by code point index, never by UTF-16 code unit. char_is_letter/_digit/_alnum/_upper/_lower/_space take a Char, and std/char's is_* are their public spellings.

Where the three criteria (§4.8) land on the string family: str.at(s, i) out of range panics (criterion 1, i is a position the caller claims exists, the same as xs[i] and bytes.at); str.strip_prefix/strip_suffix return Option (criterion 2, the test and the stripping happen in one go, so the caller does not have to compute the offset itself); str.slice/take/drop and bytes.slice clamp both ends, and from > to gives the empty string (criterion 3, a range argument selects a stretch, it does not assert that the endpoints exist). truncate is just take; there is no separate name for it.

Bytes and text encodings. The language promises exactly two charsets, and the function name is the domain: bytes.decode_utf8_lossy and bytes.decode_latin1; there is no charset registry. With no charset parameter there is no "unknown charset" failure mode, so they return a bare String rather than an Option (the history is in `stdlib-impl-notes.md`).

UTF-8 decoding comes in a lossy and a strict form, told apart by the function name in the same way. decode_utf8_lossy replaces every illegal sequence with U+FFFD (the replacement rule of the paragraph above); decode_utf8_checked rewrites nothing and answers Err(Utf8Error { offset }) at the first illegal sequence, where offset is the byte index that sequence begins at, which is also how many leading bytes of the input were valid UTF-8. The two share one notion of what is illegal: the inputs decode_utf8_checked accepts are exactly the inputs decode_utf8_lossy returns unchanged, and that is normative. decode_latin1 has no strict form, because every byte is a code point and it cannot fail. decode_utf8 is the old name of decode_utf8_lossy, kept under the one-generation forwarder discipline of CONTRIBUTING §7 and removed in the next version.

hex and base64 are pure Dawn byte arithmetic (no use java, so both backends share one definition), and the rules are normative: to_hex writes two digits per byte and lower case is the canonical spelling, from_hex accepts either case and nothing else; the encoding of to_base64(b, enc: Base64 = Standard) and from_base64(s, enc: Base64 = Standard) is a value, Standard | StandardRaw | Url | UrlRaw (Go's four encoding/base64 values of the same names): Standard* uses the standard alphabet of RFC 4648 section 4, Url* the url/filename-safe alphabet of section 5, *Raw does not pad with = and the other two pad to a multiple of four. The decoder accepts only the spellings to_base64(_, enc) can write: a padded encoding requires its padding, a *Raw one refuses =, and each recognises only its own alphabet (guessing the encoding would turn misspelled input into wrong bytes); the spare low bits of the final group must be zero — otherwise one byte string would have several spellings. The decoders in this family all fall under criterion 2: text from outside is to be validated, not asserted.

Bytes and Buf are in §9.5.1; there are also the operator Bytes ++ Bytes and content-wise ==/!=. Binary request bodies (multipart upload, WebDAV PUT), crypto/signing and HTTP traffic all go through Bytes directly, no longer by way of a latin-1 string.

Naming families. Length has exactly one name, len, and emptiness exactly one name, is_empty — the same spelling in all five of str/list/map/set/bytes. The one named exception is bytes.buf_at(b: Buf, i): bytes.at is already the byte lookup of a finished Bytes, and the language has no overloading, so the write cursor had no choice but to take another name (the criteria and the exceptions are under "naming families" in CONTRIBUTING). A search that returns a position always returns an Option and never emits -1 (str.index_of and list.index_of are the same currency).

Sorting and extrema. The sort family requires the element/key type to have Ord (§3.5); all of them are stable and a tie takes the first. list.any/list.all short-circuit (the two faked with fold walk the whole thing); on an empty list they are false / true respectively. list.unique asks for one thing more than the rest, a Hash: deduplication with only Eq is quadratic, and Set's insertion order happens to be exactly the order deduplication wants.

Result has no accompanying library functions (no map_err, no ok). match and ? are enough; for crossing error types see the local helper in §8.1. Turning a Result into an Option did not occur once in 40,000 lines of Dawn (not one of the 32 -> None arms faces an Err), and throwing the error away runs against this language's grain.

Positions: Cursor. A function taking a code point index has to count from the start of the string to that index on every call — O(n) per call, and O(n²) once it is in a loop. A cursor is a position, not a count, so each step costs a constant. A position can only be obtained from, passed back to and compared by the functions of std/cursor (== and < <= > >= — the ordering of positions within one string is a legal operation on the position type), and stored in a container/record for backtracking (it is an ordinary value, and backtracking needs no extra machinery). Do not do arithmetic on it — arithmetic is the only thing that can conjure up an illegal position in the middle of a surrogate pair.

Both the arithmetic and the conjuring are compile errors: Cursor is declared by std/cursor as pub opaque type Cursor = Int (§2.7), and only that module may see it as an Int. To write Cursor in type position you need use std/cursor.{Cursor} on top of use std/cursor (the first binds a module alias, the second binds a name; two different things). cursor.seek / cursor.offset are the bridge between the two position currencies, one O(n) pass each, meant for the boundary (an Int index arriving from outside, a position being reported to the outside); put them in a loop and you are back to the O(n²) they exist to remove. A single call on a single string with the index version is fine, but inside a loop the cursor version is mandatory — the measurements are in docs/seq6-research.md §5's addendum.

The measure is the backend's, and never becomes an observable value. A position is an offset into the string's representation, and the execution models do not agree on that representation: UTF-16 code units on the JVM, UTF-8 bytes on native, and code points in the comptime interpreter, which has no representation to offset into. So the number does not leave std/cursor: it cannot be read (opaque), it cannot be folded into a constant (§7.2), and it does not render. Show[Cursor] renders <cursor> rather than the number, because otherwise a program's output would depend on who compiled it. To report a position, report cursor.offset(s, c): the count in characters, which every backend agrees on. Which measure is used is therefore an internal decision, changeable at any time, and not a breaking change.

Using a cursor on another string is undefined. A cursor belongs to the string it came from. An out-of-range position is clamped by char/next/prev and refused by slice, but an in-range one from another string is indistinguishable from a position of this one, so this specification promises no answer and the backends do in fact differ. Binding a cursor to its string needs a tag that is itself backend-independent (otherwise the check diverges exactly where the cursor did), which costs a walk to compute and a second word per position. That was weighed and declined on 2026-08-16 in favour of writing the boundary down; every other channel is held shut by scripts/spike-native/cursor_currency.dawn, which compares this module's public answers across both backends. Comptime evaluation is outside that trade-off: the interpreter's positions already know which string they were taken on (inside the interpreter only; nothing of it reaches an artifact or costs a word at run time), so a constant fold that uses a cursor on another string, or compares or tests for equality two cursors from different strings, is refused with an error rather than given a third answer.

Container representations. Map/Set are represented by the pure-Dawn std/hamt (a persistent HAMT) and List by std/pvec (a persistent vector); these are internal modules: use std/hamt / use std/pvec outside std is a compile error, and the diagnostic points back at std/map/std/set/std/list (§10.6). The representation has to be replaceable, and being replaceable requires that nobody depends on it — which is why the standard library reference does not list these two modules either. The semantics of the containers (persistent interface, keys must be Eq + Hash, iteration in insertion order, equality independent of order) are in §2.2.

Where IO stands. std/io's console, environment and subprocess functions are !io; the file functions ride the named effect Fs (§6.5), whose production handler is io.with_fs_real and which a test answers from a table. Anything that can fail returns Result[T, ForeignError] (§9.8.1) — a structured payload rather than the sentence a barrier has already rendered; the reasoning is in `audit/error-model-design.md`. The further normative behaviours are:

Math builtins. There is no general math-function family and no host-math wrapper. The builtin numeric surface is limited to Int/Float arithmetic operators; the builtin conversion functions are to_float and to_int. Additional operations live in pure Dawn source libraries; for example, std/narrow computes square roots with integer arithmetic and does not depend on a host math library. std/narrow's three formats have + - * / % and unary - (§3.5's Add to Neg, with the default rounding, nearest even; % is the exact truncating remainder) and FromFloat: let w: BF16 = 0.1 is bf16(0.1), folded at compile time. They take no integer literals.

Fixed-width integers. The compiler owns two numbers, Int and Float (literal-system-design.md D1); I8, I16, I32, U8, U16, U32 and U64 are opaque types over Int (§2.7), one std module each (std/int/i8 ... std/int/u64; use std/int/u32 binds the last segment, u32), made first-class numbers by §3.5's arithmetic and literal traits. The criteria:

Implementation strategy: wrap Java thinly wherever a thin wrapper will do (String simply is java.lang.String), while the persistent List/Map/Set are pure Dawn source throughout (List = the std/pvec persistent vector, Map/Set = the std/hamt persistent HAMT, all with deterministic insertion order), leaving the backends a single primitive to implement: Array.

12.The compilation model

12.1Outputs

There are two backends, each with its own driver. dawn is the JVM toolchain (it emits bytecode); dawnc is the C backend (it emits C11 source and then hands it to cc). They are not the same road: dawn build --native is still the JVM backend, it just hands the jar from the previous step to GraalVM native-image (§12.3); dawnc produces no bytecode at all.

The JVM toolchain dawn (wherever the rest of this chapter does not name a driver, it means this one):

CommandOutput
dawn check <file or dir>...Type checking only. Prints ok and exits 0 when clean; renders the diagnostics and exits 1 if there is any; exits 2 on a usage mistake
dawn run [compiler-options] <file.dawn or dir> [-- <program-args>...]Compiles into memory / a temporary directory, starts a JVM and runs it
dawn build <file or dir> -o app.jarAn executable jar (Main-Class: main is already set)
dawn build ... --native -o appThe previous step + GraalVM native-image, a standalone binary (§12.3)
dawn test <file or dir>Compiles the variant that includes the test blocks and runs it (directory mode aggregates the tests of every module)
dawn fmt <file or dir>...Formatting (directory mode recurses over every .dawn; a directly named file must end in .dawn, or it exits 2)
dawn __emitc <file or dir> -o out.cA C translation unit. A hidden subcommand: this is the C backend's entry point on the JVM toolchain, and dawnc's selfhost and differential comparison both go through it

The C backend driver dawnc (a single-file static executable, shipped with each release; it needs neither a JVM nor this repository):

CommandOutput
dawnc check <target>...Type checking only, aggregates diagnostics from every target
dawnc emitc <target> [-o out.c]A C translation unit (compiled together with the runtime in runtime/c/)
dawnc build <target> [-o out]The previous step + a call to cc ($CC overrides it), a standalone executable
dawnc build --target wasm [--reactor] <target> [-o out]The same C handed to clang, a WebAssembly module (§12.5)
dawnc run [--std <dir>] <target> [-- <program-args>...]The same, and runs it as soon as it is compiled
dawnc test <target>Compiles the variant that includes the test blocks and runs it
dawnc fmt / doc / add / lspOutput is byte-for-byte identical to dawn's subcommands of the same name (scripts/native-cli-diff.sh pins these four to the JVM's bytes)
dawnc versionThe version number (it reports (native) itself, so it is not literally identical to dawn --version)

The two lsp subcommands share one stdio-framing implementation. A header, from its first byte through CRLF CRLF, is at most 8192 bytes: a terminator completed exactly on byte 8192 is valid, while an incomplete header that reaches the limit is rejected immediately. A body is at most 67108864 bytes. Every nonempty header line must have the shape 1*tchar ":" field-value; tchar is an ASCII letter or digit, any of ! # $ % & ' * + - . ^ _ | ~, or a backtick. A missing colon, an empty field name, or a space/parenthesis in the field name is therefore a framing failure, while a syntactically valid unknown header is ignored. The field name Content-Length is compared ASCII-case-insensitively. Its value is one or more ASCII decimal digits, optionally padded at either end by SP/HTAB only. Empty values, signs, fractions, exponents, underscores, Unicode digits, Int overflow and values above the body limit are invalid; 0 is valid. Duplicate fields are valid only when every independently parsed numeric value is equal, so leading zeroes do not conflict; an invalid occurrence or a numeric conflict rejects the frame.

The body must be strict UTF-8. If a complete bounded frame has invalid UTF-8 or an invalid JSON body, the server replies with -32700, id: null, and continues with the next frame; a replacement decoder must not repair invalid wire bytes into valid JSON. Every other framing failure (a malformed or partial header, a partial body, a missing, invalid, conflicting or oversized length, or an oversized header) produces exactly one copy of the parse error below and closes the read loop; bytes after the failure are never interpreted as another frame. Clean EOF with zero header bytes is silent. Header syntax and all length validation are checked before the underlying stdin-read primitive is called.

{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}

The two drivers parse argv independently, but target cardinality is one shared contract (TOOL-04):

SubcommandTarget / selector cardinality
check1..N targets
testExactly one target, or --stdlib; the two are exclusive
docExactly one of one target, --stdlib, or --builtins
buildExactly one target
emitcExactly one target (the JVM entry point is the hidden command __emitc)
fmt1..N targets

A missing target, too many targets, or conflicting selectors is a usage error: it exits 2 before loading a target or producing a backend output, and both drivers use identical diagnostic bytes for the same error. N has no artificial upper bound for check or fmt; testing with two targets demonstrates that they really are batch commands, not that their maximum is two.

run uses two explicit argv namespaces (TOOL-03):

dawn run [compiler-options] <target> [-- <program-args>...]

Compiler options are parsed only before the target. The separator may be omitted when the program has no arguments; both run target and run target -- pass an empty argv. If any token follows the target, the first one must be --; otherwise stdout is empty, stderr is exactly the following line, and the command exits 2:

error: usage: dawn run [compiler-options] <target> [-- <program-args>...]

The separator itself is not forwarded. Every token after it reaches the program's args() verbatim and without further interpretation, including an empty string, --, --closure, and -o. args() is whole-program input: whether the call is in the entry module or any dependency module, it returns the same list supplied when that program was started. The JVM and native drivers keep independent parsers and are held to one absolute stdout/stderr/exit contract; see run-argv-boundary-design.md for the full rationale.

The few subcommands dawnc lacks are not holes, they are the backend's boundary: it refuses use java (Java interop is a JVM backend capability, §9), and build-to-jar, lock and cache likewise only mean something on the JVM side. Both drivers accept --std <dir> to swap the standard library source; without it they take DAWN_STD (when not empty), and otherwise the copy compiled into the toolchain, never a std/ under the working directory (std-dir-loading-design.md).

The argument may be a single file or a project directory (§10.1): directory mode loads every module under src/, with src/main.dawn as the entry point; single-file mode walks upwards for a src ancestor and takes it as the root. The jar collects every module class, and Main-Class = the entry module's class main.

Third-party jars: --cp <jars> (before run's target, and for test/build; separated by the path separator, repeatable). Compile-time use java resolution and run-time loading share this one classpath. build records each jar in the manifest's Class-Path (relative to the output directory, so moving the jars means moving them together), and the output still runs directly with java -jar; build --native instead passes them to native-image in -cp form (whether a third-party library's reflection/JNI survives native-image is the library's responsibility, see §12.3).

--cp itself does no dependency resolution: it mounts exactly what you give it, and you have to list the transitive dependencies yourself. A library that needs a dependency tree goes through [java-deps] (the dawn.toml of §10.1) — that path resolves Maven transitive dependencies via coursier. This section once said "Dawn has no dependency resolution — it only accepts single-jar, zero-transitive-dependency libraries", which was the fact before [java-deps] existed and directly contradicts §10.1.

Guaranteed: the same program behaves identically under all three outputs — the bytecode running on a JVM, the native-image binary from --native, and the executable from the C backend (apart from startup time and memory footprint). A program with use java only has the first two outputs; that is a boundary it declared itself, not an inconsistency.

12.2The bytecode mapping

Dawn constructJVM implementation
Module json/lexerOne class, internal name json/lexer (package json, class lexer), functions become static methods
ADT/recordClass names carry the module prefix: json/lexer$Token, constructor json/lexer$Token$Num
Cross-module callinvokestatic on the other module's class; constructors/fields as usual (the classes are public)
ADTabstract class + final subclasses; a payload-free constructor is a singleton
recordfinal class + fields (does not rely on Java records, so older bytecode targets still work)
matchAn instanceof chain + field reads (no indy, no pattern switch)
lambda/closureEach closure is an ordinary generated class implementing FnN, with captures in final fields; SAM conversion generates a separate adapter class holding that FnN
genericserasure + boxing
structurally equal typesADTs/records/tuples still get matching equals and hashCode, but those are for Java callers — Dawn's ==/hash are Core functions that lowering expands structurally (§4.3), and Map/Set reach them through dictionaries. When an impl Eq/impl Hash exists, these two methods forward to that impl
Int/Float/Boolnative long/double/boolean, boxed only in generic positions
UnitLdawn/rt/Unit; — a singleton reference; it takes one slot and is no different from any other reference in parameter/field/capture positions
NeverStatic Dawn calls use return descriptor V. Calls through erased FnN.apply return Object; the caller discards it with POP before terminating. When a SAM adapter calls its bridge, it follows the SAM return descriptor: void produces no stack value, a one-slot result is discarded with POP, and a two-slot result with POP2; the adapter then emits aconst_null; athrow. Never has no parameter, field, or other storage representation
panicThrows dawn.rt.PanicError (a subclass of Error, so catch_fault does not catch it; only the isolation point catch_panic does, see §9.8)

The runtime support classes (dawn/rt/Lists, Strings, Io, Show, Maps, Tuple*, Fn*, and so on) are generated once per program and shared by all module classes.

12.3Ahead-of-time compilation: the native-image contract and the C backend

Both roads get you an executable that does not depend on a JVM, but which layer of the compilation stack they fork at determines the constraints each one carries.

dawn build --native (GraalVM native-image): goes through the whole JVM backend and takes the jar for closed-world analysis. The language constructs are guaranteed not to produce reflective calls, custom indy bootstraps, dynamic class loading or JNI (Java interop uses ordinary invokes). A --native build therefore needs no reachability configuration. If a Java library you pull in uses reflection itself, that is the library's responsibility — the error message will point out that this is beyond what Dawn guarantees.

dawnc (the C backend): forks after Core, never passes through bytecode, so the contract above means nothing to it — there are no classes to analyse and no native-image involved. The price is that it has no Java: use java is refused outright (§12.1). The output is an ordinary executable compiled by cc, and the runtime lives in runtime/c/.

12.4Tail calls

Self-recursive tail calls are guaranteed to compile to a loop (the stack does not grow) — for top-level functions and for local named functions (§3.1) alike. Mutually recursive tail calls are not guaranteed. The rule: a call to the function itself inside its body sits in tail position (return position, the tail position of a match/if branch, the last expression of a block).

12.5Build targets

There are three build targets. Choosing a target means choosing a driver and a command; jvm and native are this section's names for them, not spellings you can write.

TargetCommandOutput
jvmdawn build <target> -o app.jar (with --native, then handed to GraalVM native-image, §12.3)An executable jar
nativedawnc build <target> [-o out]An executable compiled by cc
wasmdawnc build --target wasm [--reactor] <target> [-o out]A WebAssembly module (WASI preview 1)

Only dawnc build accepts --target, and its only value is wasm; any other value is a usage error (exit 2). dawn build has no --target, and writing one exits 2 as well. --reactor must come with --target wasm; otherwise the build exits 2.

wasm and native are one backend: the same emitted C and the same runtime runtime/c/dawn_rt.c, which swaps out what the target does not have under __wasi__ conditional compilation. The compiler is clang: DAWN_WASM_CC overrides it, the default is clang, and CC is not read. The triple is whichever one the compiler in hand has a sysroot for, wasm32-wasip1 first and wasm32-wasi otherwise. Without -o, the output is named after native's default with .wasm appended. use java is refused, as on native (§12.1).

A command module (no --reactor) exports _start and memory. The host calls _start once and the program ends when main does, with the same meaning as a native process.

Reactor mode (--reactor) links without a _start, and the module's exports are exactly three: memory, _initialize and dawn_turn.

The standard library on wasm (the same in both modes): every bundled std module compiles for wasm, and every difference is in the runtime. Each row below is an explicit refusal by the runtime, not an emulation; outside the table, behaviour matches the native output (§12.1's guarantee extends to wasm).

CapabilityOn wasm
File io (Fs)Through WASI preopens; which directories are visible is the host's decision
io.run (Proc)Err (a fault, io_run: no processes on wasi)
io.real_pathErr (a fault): wasm32-wasi has no absolute paths to resolve (§11)
io.temp_dir / io.temp_fileErr (a fault)
io.copy_permissionsSucceeds whenever src exists, but changes nothing: the target has no file modes
One-shot continuations (control arms, discard, §6.5)Panic: dawn: one-shot resumption is not available on wasm
std/gpu's with_gpu_realEvery operation that reaches the device answers gpu.unsupported_backend (§12.6)
Threads, a large stackNone; the recursion depth limit depends on the engine's call stack and is undefined

Checked by machine: scripts/wasm-contract/run.sh builds one corpus both natively and as wasm (command modules), runs the wasm under node's WASI, and requires stdout to equal the native run byte for byte, the runtime's ledger of object births and deaths to balance to zero, and an uncaught panic to exit 1 on both targets; scripts/wasm-dom-contract/run.sh runs the reactor and the DOM bridge against a recording document stub and compares the transcripts byte for byte. Both run in CI's wasm-target job.

12.6The device backend: GPUs

The device backend is not a third backend of the compiler. Neither driver knows what a kernel, Tile IR or a GPU is, and neither calls any device toolchain. It is two layers of library:

The reasons, the roadmap and the measurements are in `tile-backend-design.md` §4–§6 (in Chinese).

A kernel body is an ordinary Dawn function whose effect row is Dev alone, of the shape fn(a: Param[Float], b: Param[Float], out: Param[Float]) -> Unit !Dev.

The Gpu effect has seven operations (gpu_alloc, gpu_copy_from_host, gpu_copy_to_host, gpu_launch, gpu_module_global, gpu_free, gpu_sync), monomorphic and handle-level; a program uses the typed functions over them: alloc, copy_from_host, copy_to_host, free, launch, module_global and sync.

The two handlers:

pub fn with_gpu_fake[T](kernels: Map[String, (Int, WideRefFn)], body: fn() -> T !Gpu,
  globals: Map[String, List[(String, String, List[Float])]] = map.empty()) -> T
pub fn with_gpu_real[T, !e](kernels: Map[String, Bytes], body: fn() -> T !Gpu !e) -> T !io

The contract between the two handlers:

Types that cross the boundary: only buffers cross between host and device.

Checked by machine (where, and what):

LayerWhat is checkedWhereWhen
0Every kernel is recorded twice and the records are equal; text goldens (*.mlir) and bytecode goldens (*.tilebc), byte for byte on both backendsscripts/tile-golden/run.shCI tile.yml
1The pinned tileiras --gpu-name sm_86 accepts every bytecode golden: exit 0, no error: in its output, and GLOBAL FUNC <kernel> in the cubin's symbol tablethe assemble step of scripts/tile-golden/run.shCI tile.yml
2One set of !Gpu programs runs under both handlers and agrees bit for bit or within tolerance, by the kernel's tier; on the JVM the real handler answers gpu.unsupported_backend at the first operationscripts/tile-gpu-diff/run.sh, which appends its result to a ledgerBy hand, on a machine with a driver

Not promised:

13.Syntax cheat sheet

# ---- declarations ----
use geo/shape.{Shape, area}
use java "java.nio.file.Files"

pub type Color = Red | Green | Blue derive Show
type Point = { x: Float, y: Float }
alias Distance = Float           # transparent alias (§2.6)
pub opaque type UserId = Int     # opaque outside this module (§2.7)
const ORIGIN: Point = Point { x: 0.0, y: 0.0 }

pub trait Named[T] { fn name(x: T) -> String }
impl Named[Point] { fn name(p: Point) -> String = "point" }
pub effect Ask { fn ask() -> Int }

pub fn dist(a: Point, b: Point) -> Float =
  sqrt(pow(a.x - b.x, 2.0) + pow(a.y - b.y, 2.0))

fn double(x: Int) = x * 2        # a private function may omit the return type (§3.1)

# ---- expressions ----
let n = 42                       # immutable binding
var acc = 0                      # mutable binding
acc = acc + 1                    # assignment (var only)
let (a, b) = pair                # destructuring
if x > 0 { "pos" } else { "non-pos" }
match opt { Some(v) -> v, None -> fallback }
xs |> filter(x => x > 0) |> map(x => to_string(x)) |> join(", ")
xs[0]                            # subscript: goes through the Index trait; out of range panics, enquire with get (§4.8)
[a, ..xs, if c { b }]            # list elements: spread / conditional; newlines separate too (§4.11)
read_file(path)?                 # Result propagation
if n < 0 { return "negative" }   # early return (§4.9)
xs.each { x => println("${x}") }  # tail block: the last argument (§4.3)
with f <- bracket(open(p), close)  # the rest of the block becomes the use closure (§4.10)
comptime { heavy_pure_calc() }   # compile-time evaluation

# ---- local functions inside a block (recursive, §3.1) ----
fn sum(xs: List[Int]) -> Int = {
  fn go(i: Int, acc: Int) -> Int =
    if i == len(xs) { acc } else { go(i + 1, acc + xs[i]) }
  go(0, 0)
}

# ---- tests ----
test "dist is symmetric" {
  assert dist(p, q) == dist(q, p)
}
test dist { assert dist(p, p) == 0.0 }   # named by a declaration: dist's example (§3.4)