Wado Language Specification

Wado is a programming language that targets Wasm and WASI: Wasm in plain sight.

Status

The specification is the spec-*.md files, one per area of the language. It is normative: it says what the language is meant to be, and you read a program's meaning from here. It is not a record of what the compiler happens to do today. Chapters lists the files in reading order.

The specification states what a program can observe. How the compiler produces it, such as which copies it makes or what it inlines or folds, is not part of the language, so the specification does not say.

So if the specification and the implementation disagree, something is wrong. Which of the two is wrong is not decided in advance: the specification can be the mistaken one. That gets settled when the disagreement is found.

What is not allowed is leaving the disagreement in place as an accepted difference. If it is not resolved, it becomes a Known gap in the WEP that proposed the rule, saying what the disagreement is and what it admits. The specification itself records no bugs.

A rule the language has adopted but the compiler has not built yet stays in the specification. A note right after the rule marks it, saying what the compiler does until then:

Not yet implemented: a function writes a mutable global without declaring an effect.

Behavior Classes

Where the specification leaves behavior open, it says which of three classes the behavior belongs to.

• Unspecified: the specification lists the permitted outcomes, and the compiler chooses one. The choice may change with the optimization level or the compiler version, but a compiled program keeps it on every host. A correct program is correct under every listed outcome.
• Host-defined: unspecified, except that the compiled program need not fix the choice, so the host may make it. The same compiled program may behave differently on two hosts. Each case says whether the choice stays fixed on one host. What a world import returns is host-defined within what its interface promises: InsecureSeed may return the same value every time, for one.
• Unconstrained: the specification lists no outcomes, and the compiler may assume the case never arises. Its effects may appear anywhere in the program and at any later time. Only these guarantees remain: the Wasm instance stays memory-safe, components stay isolated from each other, no capability is used that the world's imports did not grant, and GC references stay well-typed. A trap, a wrong value, a loop that never ends, or data leaking inside the instance are all possible.

A contract violation is a program reaching an operation outside the contract the operation states, such as calling an _unchecked function on input it does not accept. It is always a bug, and each operation says which class of behavior its violation has. Unconstrained behavior arises from a contract violation and from nothing else.

Any build may detect a contract violation and trap, and Contract Checks says which builds do. No build may trap on unspecified or host-defined behavior that is not a contract violation.

Overview

See also: Cheatsheet for quick syntax reference.

Chapters

Each chapter builds on the ones before it.

1. Lexical Structure: whitespace, comments, identifiers and keywords.
2. Literals: numbers, strings, templates, tuples, lists and compile-time literals.
3. Statements and Expressions: statements, variables, globals, operators and ranges.
4. Types: primitives, strings, tuples, lists, newtypes, structs, enums and variants.
5. Patterns: taking a value apart in match, let and for.
6. Control Flow: branches, loops, labeled blocks and error handling.
7. Assertions: the assert statement and its failure message.
8. Functions: declarations, methods, generics, closures and default arguments.
9. Memory Model: value semantics and references.
10. Traits: declaring, implementing and bounding traits.
11. Standard Traits: the traits behind for-of, comparison, operators and indexing.
12. Static Reflection: the compile-time view of a type's members.
13. Effect System: declaring, propagating and handling effects.
14. Module System: visibility, imports and re-exports.
15. Packages: the manifest, dependencies and package specifiers.
16. Kiln Generators: imports that a build-time generator writes.
17. Worlds and Entry Points: what a program imports from its host and exports to it.
18. Components: the Component Model boundary, concurrency and resources.
19. Serialization: Serialize, Deserialize and wire formats.
20. Compiler Attributes: the #[...] attributes.
21. Testing: test blocks, their outcomes and how wado test finds them.

Design Philosophy

See Design Philosophy. The rules those principles produced are stated here, each where it applies: Memory Model, Concurrency Model, Effect System.

Appendix

Naming Conventions

At a component boundary, the compiler converts these names to WIT's kebab-case and back.

Terminology

• Wasm: WebAssembly (not WASM)
• WASI: WebAssembly System Interface
• CM: Wasm Component Model
• module: a Wado file
• package: a collection of modules, described by one wado.toml
• Wado standard library: consists of core: and wasi:
• effect: the concept; e.g., "the Stdout effect"
• effect interface: the declaration (interface Stdout { ... }); synonyms in literature: "effect signature", "effect type"
• operation: a function in an effect interface; synonym: "effect operation"
• handler: provides implementations for operations
• hosted world, library world: the two kinds of world, defined in What is a World?; a hosted world is informally called a "well-known world"