Language specification
The specifications below make the language architecture precise. That architecture chooses mechanisms for the invariants stated in foundations.md, which follow from the rationale in philosophy.md.
Status
These documents define the target language and are normative for it. Flow is pre-release (runtime architecture). Where an implementation disagrees with a rule here, the rule stands and the gap is an implementation gap. The runtime architecture alone owns the ledger of what is not yet implemented, and no specification in this directory discusses implementation status.
Snippets in flow fences are written in the language these documents define.
They illustrate rules; they are not fixtures and make no claim about any
toolchain. text fences hold notation and illustrations that are not Flow.
Ownership map
Each specification owns exactly one surface. A rule lives in its owner; other documents link to it rather than restating it.
Writing a program
| Specification | Owns |
|---|---|
| grammar.md | source text, lexical rules, names and case, keywords, comments, literals, operators and precedence, newlines, the shape of items, types, expressions and patterns, and the canonical formatter |
| types.md | records, enums, visibility and opaque, generics, aliases, tuples, Unit and Never, function types, constructors and their resolution, no subtyping, the data-type category, and equality, ordering and text |
| effects.md | the one effect !tool, purity, effects passing through function arguments, what a signature writes and what is inferred, and why timing is not an effect |
| data.md | the built-in data types: Int, Decimal, Bool, Text, Bytes, List, Dict, Set, Option, Duration and Instant; what literals denote, division, and normalization |
| modules.md | files as modules, use, qualified names, versions on the repository, pinning, one version per repository, std as the language version, the prelude, import cycles, submitted bundles, and name collisions |
Meaning
| Specification | Owns |
|---|---|
| semantics.md | functions and anonymous functions, local and top-level items, evaluation order, tail calls, return, if, match, guard, what patterns match and bind, method syntax, building and updating records, and entry functions |
| checking.md | what a checked program proves, the discard rules, exhaustive matching, and errors only |
| errors.md | Result, ? and x ? f, the four Tool problems, faults and their sources, and how a run ends |
| tools.md | @tool functions and types, generic Tools, what crosses the boundary, decoding, host tokens, a model choosing a Tool through an Action enum, an open tool registry, and a Flow run as a Tool |
| concurrency.md | task.spawn, await, stop and first, Stop<T>, task ownership and hand-off, tail calls and tasks, faults in tasks, task states, the task library functions, and clock.timeout |
Continuity
| Specification | Owns |
|---|---|
| history.md | what history records, fact ids, pauses as open calls, checkpoints, replay and its verdicts, closed evaluation, a run staying on its program, forks, holes, integrity, and program identity |
Library
| Specification | Owns |
|---|---|
| stdlib.md | the std modules, the rule that std functions are total and pure, the clock Tool module, @lang declarations, json encoding and decoding, and the functions other rules name |
Boundaries with the runtime track
The runtime specifications say how a conforming implementation realizes these rules. They may refine, and never redefine, the meaning owned here.
| Runtime specification | Owns |
|---|---|
| runtime/spec/abi.md | the value encoding and its canonical form, the Tool process protocol (describe, call, reply, cancel), schemas, Tool identity and fingerprints, the binding lifecycle, flow-tool.toml, toolkits and adapters |
| runtime/spec/execution.md | running a program: entry selection, input and output, run states and CLI exit codes, pause and resume, crash handling, limits, nested runs, forks, testing with @test and @fake, the CLI and MCP surface, and approval before running a repository's implementation |
| runtime/spec/trace.md | the history format: fact encoding, the hash chain, content-hashed values and module sources, checkpoint encoding, holes, and the data version |
| runtime/spec/diagnostics.md | the diagnostic principles, data shape, codes and fixes |
The language rules for each of these sit in the specification above that owns the surface: tools.md for what crosses and how replies are decoded, history.md for what history records, and checking.md for what acceptance means.
Rules every specification observes
No specification may add another way to observe or affect the outside world. Every outside value enters through a run's input or a Tool call, and time, randomness, files, network and human input are Tool calls (history.md).
No specification may add a language-level authority, policy, approval, budget, confinement or operator mechanism. Credentials, approvals, budgets, sandboxing, Tool implementations and their lifecycle, and recovery beyond the run belong to the application or host that enforces them, and may appear here only as non-normative context at a boundary.
No specification may give a program a path to its own history, position, mode or binding.
No specification names a particular type or function as a compiler rule. The
compiler knows mechanisms and categories; what it treats specially is declared
in std with @lang (stdlib.md).
Normative style
Each specification states exact rules, examples and refusals, and leaves implementation mechanics to the runtime track. Two kinds of text appear:
- Language rule: binds every conforming implementation.
- Non-normative guidance: examples, rationale and boundary explanations. An example illustrates a rule and cannot override the specification that owns it.
Productions, signatures and tables a specification introduces as definitions are normative, whatever their fence. No source block is a wire encoding unless a runtime specification defines it as one.
Precedence
A disagreement between two specifications is a defect in the one that does not own the surface. A disagreement between this directory and the language architecture is a defect, and the architecture owns the decision until the specification is repaired; where the architecture and the foundations disagree, the foundations own it. A disagreement between a language rule and an implementation is an implementation gap, not permission to weaken the rule.