volaro 0.0.2

package/language/spec.md

@@ -0,0 +1,1840 @@
+# Volaro Language Design Specification
+
+Version 0.2 (draft)
+Status: design, pre-implementation
+Changelog: see section 22
+File extension: `.vl`
+Reference implementation language: Rust
+
+---
+
+## 1. What Volaro is
+
+Volaro is an application language written to be generated by a model and read by a person. It targets one narrow band of software: the kind of application built from views, HTTP endpoints, outbound API calls, and user accounts. Inside that band it aims to express a working feature in roughly a fifth of the tokens a TypeScript, React, and Express stack needs, with no wiring layer and no framework glue. A project has exactly one configuration file, `volaro.toml`, and it holds only what cannot be derived from source: the project name, its version, and its dependencies (§7). Everything a framework would normally push into config — routes, schema, sessions, build steps — is a declaration in the language instead.
+
+The design starts from a specific failure pattern. When a model writes a login flow in a general-purpose stack, it produces four files, invents a session helper, forgets `httpOnly` on the cookie, and picks a password hash from whatever was popular in its training data. None of those mistakes are hard problems. They are boilerplate problems. Volaro removes the boilerplate by promoting views, API clients, HTTP services, and authentication into first-class syntax, so there is nothing left to wire incorrectly.
+
+### 1.1 Goals
+
+1. **Token density.** A feature should cost few tokens to write and few tokens to re-read. Density comes from removing redundant delimiters and from making common patterns into declarations, not from cryptic operators.
+2. **One canonical form.** For any given construct there is exactly one way to write it. No braces-or-indentation choice, no `function` versus arrow, no import style debate. A single target form makes generation more reliable and diffs stable.
+3. **Readable by a person who has never seen it.** A developer reviewing generated Volaro should follow it without a manual. Keywords are words, not sigils. Structure is visible as shape on the page.
+4. **Secure by construction.** Password storage, session cookies, CSRF tokens, and authorization checks are compiler concerns. The insecure version is not expressible.
+5. **Errors written as repair instructions.** Diagnostics are machine-readable and each one carries a suggested patch, so a model gets a fix rather than a complaint.
+
+### 1.2 Non-goals
+
+Volaro is not a systems language. There is no manual memory management, no pointer arithmetic, no unsafe escape hatch, no operator overloading, no user-defined macros, no inheritance, and no configurable code formatting. Anything outside the application band (drivers, kernels, game engines, numeric kernels) belongs in Rust, and Volaro calls into Rust through a foreign function boundary rather than growing to cover it.
+
+---
+
+## 2. Design principles
+
+### 2.1 Delimiters carry meaning once
+
+Most languages encode block structure twice: braces for the compiler and indentation for the reader. Volaro encodes it once. Newline ends a statement. Indentation opens a block. Dedent closes it. Semicolons and braces do not appear in statement position at all.
+
+The saving is not trivial. In a 200-line TypeScript module, roughly 8 to 12 percent of tokens are `{`, `}`, `;`, `(`, `)`, and `,` characters serving purely as structure. Removing the redundant half of those is free density with no loss of clarity.
+
+### 2.2 Declarations over instructions
+
+The stack a model finds hardest to write correctly is the part where a declarative intent gets expressed as a sequence of imperative steps: fetch data, track loading, track error, render three ways, clean up on unmount. Volaro names the intent. A `load` block in a view declares the request and its three visual states in five lines, and the compiler emits the state machine.
+
+The same logic applies to retries, rate limits, session rotation, and role checks. Each is a property of the thing, so each is written as a property of the thing.
+
+### 2.3 Inference where it is safe, annotation where it is contractual
+
+Local variables are inferred. Function parameters, return types, record fields, and anything crossing a module or network boundary are annotated. The rule is easy to state and easy for a generator to follow: if a human on the other side of the boundary would need to know the type, write it down.
+
+### 2.4 Compact project map
+
+Every project compiles to a generated `map.vks` summary: every type, view, route, outbound endpoint, and role in the codebase, one line each. A model editing a 40-file project reads the map, not the files. On a mid-sized app the map runs about 300 lines against 6,000 lines of source, which changes what fits in a context window.
+
+---
+
+## 3. Lexical structure
+
+### 3.1 Source encoding
+
+Source files are UTF-8. A byte-order mark at the start of a file is an error. Line endings are `\n`; a `\r\n` file is accepted by the reader and normalized by the formatter.
+
+### 3.2 Indentation
+
+Indentation is two spaces per level. Tabs in leading whitespace are a hard error with no configuration option, which removes an entire category of mixed-whitespace bug.
+
+The lexer maintains an indent stack. At the first non-whitespace token of a line it compares the line's indent width against the top of the stack and emits `INDENT`, one or more `DEDENT`, or nothing. A line whose indent matches no level on the stack is an error.
+
+Inside an open bracket pair (`(`, `[`, `{`), newlines and indentation produce no tokens. This allows multi-line argument lists and literals without indentation rules interfering.
+
+### 3.3 Comments
+
+```vl
+# line comment, runs to end of line
+## doc comment, attaches to the following declaration
+```
+
+There is no block comment form. Editors comment ranges line by line, and a single form keeps nesting rules out of the lexer.
+
+### 3.4 Identifiers
+
+Identifiers match `[a-z_][a-z0-9_]*` for values, functions, fields, and modules. Types match `[A-Z][A-Za-z0-9]*`, except the built-in primitives, which are lowercase words (`int`, `str`, `bool`).
+
+**Components may be either case, and the case carries meaning.** A lowercase component is a *primitive element* — the layout and input set in `std.ui` (`col`, `row`, `stack`, `grid`, `text`, `img`, `button`, `input`, `link`, `spacer`), which have no children beyond what they render and are the leaves and boxes of a tree. An uppercase component is a *user or library view* declared with `view` (`PostCard`, `Spinner`, `Avatar`). Reading a view body, the case tells you whether a line is layout or a call into another component, which is the distinction that matters when scanning a tree.
+
+A project shadowing a primitive keeps the lowercase name (§8.2). Case otherwise carries meaning as usual, so a reader knows what a bare name refers to without looking it up.
+
+### 3.5 Keywords
+
+**Reserved.** These are never identifiers, in any position:
+
+```
+and    as     auth   break  catch  derive else   err    false
+fn     for    if     in     let    match  mut    nil    not
+on     or     par    return skip   spawn  true   try    type
+use    while
+```
+
+Twenty-nine reserved words.
+
+**Contextual.** These are keywords only as the head of a declaration or of a block that expects them, and are ordinary identifiers everywhere else. `list` is the clearest case: `list posts as p key:p.id` is a view statement, while `list<Post>` is a type and `posts.list()` is a method call.
+
+```
+api    error  errors index  key    list   load   model  none
+pending prefix public role  service session state  theme  view
+```
+
+A contextual keyword is recognised by position, so a field named `state` or a
+function named `load` stays legal. Everything else, including all layout
+components, lives in the standard library.
+
+### 3.6 Literals
+
+```vl
+42              # int
+1_000_000       # int, underscores ignored
+3.14            # float
+0xff  0b1010    # int, alternate bases
+"hello"         # str
+"hi {name}"     # str with interpolation
+"""
+multi-line
+"""             # str, leading indent stripped to block level
+true  false     # bool
+nil             # absence
+10s  500ms  30d # duration
+[1, 2, 3]       # list
+{a: 1, b: 2}    # record or map, depending on inferred type
+0..10           # range, end exclusive
+0..=10          # range, end inclusive
+```
+
+Interpolation takes a full expression: `"total {price * qty}"`. Escapes are `\n`, `\t`, `\\`, `\"`, `\{`, `\u{1F600}`.
+
+Durations are a distinct literal type rather than an int, so `ttl 30` is a type error and `ttl 30d` is not. Timeouts and expiry windows are the two places where unit confusion causes real outages.
+
+### 3.7 Separators
+
+A newline separates items in block position. A comma separates items on one line. Both forms are accepted in list and record literals and in argument lists:
+
+```vl
+let ports = [80, 443, 8080]
+
+let ports = [
+  80
+  443
+  8080
+]
+```
+
+Trailing commas are a syntax error, since the newline form already handles clean diffs.
+
+---
+
+## 4. Types
+
+### 4.1 Primitives
+
+| Type | Notes |
+|---|---|
+| `int` | 64-bit signed |
+| `float` | IEEE 754 double |
+| `str` | UTF-8, immutable |
+| `bool` | |
+| `bytes` | immutable byte string |
+| `time` | instant, UTC, nanosecond resolution |
+| `dur` | duration, produced by duration literals |
+| `uuid` | RFC 9562 UUID |
+| `json` | dynamically shaped value, checked at use |
+| `nil` | the unit of absence, inhabits `T?` |
+
+There is no `char`, no unsigned family, and no width variants. Numeric width is a systems concern, and code needing it uses the Rust boundary.
+
+### 4.2 Type constructors
+
+```vl
+T?              # optional: T or nil
+list<T>
+map<K, V>
+set<T>
+T!              # fallible: T or the standard err type
+T!E             # fallible: T or E
+fn(int, str) bool   # function type
+```
+
+Optionals do not nest. `T??` is a type error, which removes a class of confusion that costs nothing to forbid.
+
+### 4.3 Records
+
+```vl
+type User
+  id uuid
+  email str
+  name str?
+  role Role = member
+  created_at time
+```
+
+Fields are ordered and immutable after construction. Records are **nominally typed and structurally compared**: two record types with identical fields are still different types and never interchangeable, but two values of the *same* type are equal when their fields are equal, with no identity or reference semantics. Nominal typing is what makes `distinct` (§4.5) meaningful; structural equality is what makes records usable as map keys and in tests. A field with a default may be omitted at construction. Construction uses record literal syntax with the type name:
+
+```vl
+let u = User{email: "ada@example.com", created_at: now()}
+```
+
+### 4.4 Unions
+
+```vl
+type Role = admin | member | guest
+
+type Shape =
+  circle(r float)
+  rect(w float, h float)
+```
+
+Bare variants take no payload and compare by identity. Payload variants construct as calls: `circle(2.0)`. Union names in pattern position do not need qualification, so `match role` matches on `admin`, not `Role.admin`.
+
+### 4.5 Aliases and newtypes
+
+```vl
+type Email = str            # alias, freely interchangeable
+type UserId = uuid distinct # newtype, requires explicit conversion
+```
+
+`distinct` exists because passing an order ID where a user ID belongs is the most common wrong-argument bug in application code, and the type system already has the machinery to prevent it.
+
+### 4.6 Inference rules
+
+Local bindings infer from their initializer. Function signatures never infer. Empty collection literals require an annotation:
+
+```vl
+let names = []              # error: cannot infer element type
+let names list<str> = []    # fine
+```
+
+Inference is local and unidirectional. There is no global constraint solving, no return-type polymorphism driven by call site, and no implicit numeric conversion. `1 + 1.0` is a type error; write `1.0 + 1.0` or `int_to_float(1) + 1.0`.
+
+---
+
+## 5. Expressions and statements
+
+### 5.1 Bindings
+
+```vl
+let name = "Ada"
+let mut count = 0
+count = count + 1
+count += 1
+```
+
+Bindings are immutable by default. `mut` is required for reassignment. Shadowing in the same scope is an error, since a generator that shadows accidentally produces code a reviewer misreads.
+
+### 5.2 Operators
+
+Precedence, tightest first:
+
+| Level | Operators | Associativity |
+|---|---|---|
+| 1 | `.` `()` `[]` `?` | left |
+| 2 | `not` unary `-` | right |
+| 3 | `*` `/` `%` | left |
+| 4 | `+` `-` | left |
+| 5 | `..` `..=` | none |
+| 6 | `<` `<=` `>` `>=` | none |
+| 7 | `==` `!=` | none |
+| 8 | `and` | left |
+| 9 | `or` | left |
+| 10 | `??` | right |
+| 11 | `\|>` | left |
+
+`and` and `or` short-circuit. Comparison operators do not chain, so `a < b < c` is a syntax error with a suggested fix of `a < b and b < c`.
+
+### 5.3 Pipeline
+
+```vl
+let top = posts
+  |> filter(fn(p) p.published)
+  |> sort_by(fn(p) p.score)
+  |> take(10)
+```
+
+`x |> f(a)` means `f(x, a)`. The pipeline exists because deeply nested calls are where generated code most often loses track of parentheses, and the linear form reads the way the data flows.
+
+### 5.4 Closures
+
+```vl
+fn(p) p.published                   # expression body
+fn(a int, b int) int                # annotated
+  a + b                             # block body
+```
+
+Closures capture by value. A captured `mut` binding is captured as a copy, so a closure never mutates its defining scope. Shared mutable state goes through explicit reference types in `std.sync`.
+
+### 5.5 Conditionals
+
+`if` is an expression. Both forms exist, and the formatter picks between them by whether the result fits on one line:
+
+```vl
+let label = if score > 50 "pass" else "fail"
+
+if user.role == admin
+  grant_all()
+else if user.verified
+  grant_basic()
+else
+  deny()
+```
+
+An `if` used as an expression requires an `else`. An `if` used as a statement does not.
+
+### 5.6 Match
+
+```vl
+let msg = match shape
+  circle(r) -> "circle of radius {r}"
+  rect(w, h) if w == h -> "square of {w}"
+  rect(w, h) -> "{w} by {h}"
+
+match response.status
+  200..=299 -> ok(response.body)
+  404 -> err(not_found)
+  _ -> err(unexpected(response.status))
+```
+
+Match is exhaustive. A missing case is a compile error listing the uncovered variants by name. Guards use `if` after the pattern. `_` matches anything and binds nothing.
+
+Patterns destructure records and lists:
+
+```vl
+match event
+  Click{x, y} -> move_to(x, y)
+  Key{code: "Escape"} -> close()
+  _ -> skip
+```
+
+### 5.7 Loops
+
+```vl
+for post in posts
+  render(post)
+
+for i in 0..10
+  emit(i)
+
+for k, v in headers
+  write("{k}: {v}")
+
+while queue.len() > 0
+  handle(queue.pop())
+```
+
+`break` exits. `skip` advances to the next iteration. Neither takes a label; nested loops needing early exit extract a function, which is the clearer shape anyway.
+
+### 5.8 Functions
+
+```vl
+## Returns the display name, falling back to the email local part.
+fn display_name(u User) str
+  u.name ?? u.email.split("@")[0]
+
+fn retry_count(kind str = "default") int
+  match kind
+    "aggressive" -> 5
+    _ -> 2
+```
+
+The final expression of a body is the return value. `return` exits early and is otherwise unnecessary. Parameters with defaults follow parameters without. Named arguments at call sites are allowed for any parameter and required for `bool` parameters, because `create(true, false)` tells a reviewer nothing.
+
+---
+
+## 6. Errors
+
+### 6.1 The fallible marker
+
+A function that fails declares it in the return type:
+
+```vl
+fn parse_port(s str) int!ParseErr
+  let n = to_int(s)?
+  if n < 1 or n > 65535
+    return err(out_of_range(n))
+  n
+```
+
+`T!` uses the standard `Err` record. `T!E` uses a declared union. There is no exception mechanism, no panic in user code, and no way to ignore a fallible result silently: an unused `T!` value is a compile error.
+
+### 6.2 Propagation and recovery
+
+```vl
+let user = load(id)?              # propagate to caller
+let user = load(id) ?? guest_user # fall back to a value
+
+let user = try load(id)
+catch not_found
+  create_guest()
+catch e
+  log.error("load failed", e)
+  return err(e)
+```
+
+`?` requires the enclosing function to be fallible with a compatible error type. `??` takes a value of the success type. `try`/`catch` matches on the error union with the same exhaustiveness rules as `match`.
+
+**A handled error does not fall through.** When a `catch` arm runs, the statements after the `try` block do **not** execute — the `try` statement is complete. This is the opposite of the usual imperative reading and it is chosen deliberately: the fall-through version produced a login form that showed an error message *and* redirected to the success page, which was the single most common bug in early Volaro examples.
+
+```vl
+try auth.sign_in(email: email, password: password)
+catch invalid_credentials
+  error = "Wrong email or password."     # no `return` needed
+catch e
+  error = "Something went wrong."
+route.to("/")                            # reached only when nothing was caught
+```
+
+In expression position both arms must produce a value of the same type, and the block's value is whichever arm ran:
+
+```vl
+let user = try load(id)
+catch not_found
+  create_guest()
+```
+
+Code that must run whether or not an error was caught goes **before** the `try`, or
+uses `spawn` (§12) for fire-and-forget; there is no fall-through and no keyword to
+opt into it.
+
+### 6.3 The standard error record
+
+```vl
+type Err
+  code str
+  message str
+  cause Err?
+  fields map<str, json>
+```
+
+`code` is a stable, machine-readable identifier. `message` is human text. `fields` carries structured context so a log line does not need string formatting to stay searchable.
+
+**Three spellings, three meanings**, which are distinguished by case and position and are worth stating once:
+
+| Spelling | What it is |
+|---|---|
+| `Err` | the record type above — a value's *type* |
+| `err(...)` | the constructor: wraps a variant or an `Err` into a failed `T!`, as in `return err(not_found("no such post"))` |
+| `err` | the reserved word, valid only as a `catch` binding or a match pattern head |
+
+An `Err` is never constructed with record-literal syntax (`Err{...}`); `err(...)` is the only way to produce one, so every failure has a single construction site.
+
+---
+
+## 7. Modules
+
+A file is a module and its path is its name. There is no export keyword. Names beginning with `_` are private to the file and everything else is public, which means visibility is readable from the name alone with no second place to check.
+
+```vl
+use std.http
+use std.time { now, Duration }
+use ./models { User, Role }
+use ../shared/format
+```
+
+`std.*` resolves to the standard library. `./` and `../` resolve relative to the current file. A bare name resolves to a dependency declared in `volaro.toml`. Circular imports are an error reported with the full cycle.
+
+A module holds **declarations only** — `use`, `type`, `model`, `fn`, `view`, `service`, `api`, `auth`, `theme`. There is no module-level value binding: `let x = …` at file scope is a syntax error. This keeps module load free of ordering and side-effect questions, and there is exactly one place a name at file scope can come from. Where a value is needed: configuration (limits, base URLs, tokens) lives in `volaro.toml` or `env`; a constant used by one `view` or `fn` is a `let` inside it; a value shared across a module is a zero-parameter `fn` (`fn tabs() list<Tab> …`, called as `tabs()`); a set of named cases is a `type` with variants. If real use shows a genuine need for a shared literal that none of these fit, a restricted module `let` (literal or const-expression right-hand side, evaluated once) can be added without breaking anything — it is left out until then.
+
+Project layout:
+
+```
+volaro.toml
+src/
+  main.vl
+  auth.vl
+  models.vl
+  views/
+    Feed.vl
+    UserCard.vl
+```
+
+---
+
+## 8. Views
+
+Views are the first of three domain constructs. A view declares a component: its inputs, its local state, its data dependencies, and its rendered tree.
+
+### 8.1 Shape
+
+```vl
+view UserCard(user User, compact bool = false)
+  state expanded = false
+  derive initials = (user.name ?? user.email) |> split(" ") |> map(first_char) |> join("")
+
+  col gap:12 pad:16 radius:8 bg:surface
+    row gap:8 align:center
+      Avatar(src: user.avatar, fallback: initials, size: 40)
+      col
+        text user.name size:16 weight:600
+        text user.email size:13 color:muted
+    if expanded and not compact
+      text user.bio ?? "No bio yet." size:14
+    button (if expanded "Hide details" else "Show details") variant:ghost
+      on tap
+        expanded = not expanded
+```
+
+Props are the parameter list. `state` declares reactive local state; assignment to it schedules a re-render. `derive` declares a value recomputed when its dependencies change, and the compiler works out the dependencies from the expression, so there is no dependency array to get wrong.
+
+### 8.2 Elements
+
+An element is a call in statement position with attribute syntax:
+
+```
+Name attr:value attr:value
+  children...
+```
+
+Attribute values are expressions. `attr:value` with no comma is the element form; the ordinary call form `Name(a: 1)` is used in expression position, such as inside a list. Both build the same node.
+
+Layout components (`col`, `row`, `stack`, `grid`, `text`, `img`, `button`, `input`, `link`, `spacer`) live in `std.ui` and are imported into every view automatically. They are ordinary components with no compiler privileges, so a project replaces them by shadowing the import. `dialog` and `tabs` / `tab` (§8.8) also live in `std.ui`, but have required structure the compiler checks and behaviour the compiler emits.
+
+### 8.3 Lists
+
+```vl
+list posts as p key:p.id
+  PostCard(post: p)
+```
+
+`key` is required. A list without a stable key is a compile error, which removes the single most common reconciliation bug in component frameworks.
+
+### 8.4 Data loading
+
+```vl
+view Feed(topic str)
+  load posts = blog.list_posts(topic: topic)
+    pending
+      Spinner()
+    error e
+      col gap:8
+        text "Could not load posts." color:danger
+        button "Retry" on tap: posts.reload()
+
+  list posts as p key:p.id
+    PostCard(post: p)
+```
+
+`load` binds a value and declares its pending and error rendering in the same block. Inside the success region the binding is the unwrapped value, not a wrapper, so `posts` is a `list<Post>` with no `.data` access and no null check. The binding also exposes `.reload()` and `.loading` for refresh cases.
+
+The compiler emits request deduplication, cancellation on unmount, and a cache keyed on the call arguments. Re-entering `Feed` with the same `topic` within the cache window does not refetch.
+
+### 8.5 Lifecycle and effects
+
+```vl
+  on mount
+    analytics.view("feed", topic)
+
+  on change topic
+    scroll_to_top()
+
+  on unmount
+    ws.close()
+```
+
+Effects run after the render that triggered them. `on change` takes one or more bindings and fires when any of them changes by value.
+
+`spawn` is legal in a view body, including inside an event handler. Unlike `load` (§8.4), a spawned task is not cancelled when the view unmounts: it runs to completion, and a failure logs without affecting the view.
+
+### 8.6 Slots
+
+```vl
+view Panel(title str, body slot)
+  col gap:8
+    text title weight:600
+    body
+
+# call site
+Panel(title: "Settings")
+  SettingsForm()
+```
+
+A `slot` parameter receives the element's children. One slot per component keeps composition obvious; multiple named regions use ordinary component props instead.
+
+### 8.7 Styling
+
+Attributes cover layout, spacing, color, typography, and border. A project may
+declare one conventional `theme.vl`; its nested categories replace Tailwind's
+owned scales and emit `--vl-<category>-<name>` properties:
+
+```vl
+theme
+  color
+    bg "#fff" dark "#0b0b0c"
+    fg "#111" dark "#f2f2f3"
+    accent "#2563eb" dark "#2563eb"
+  space xs 4 sm 8 md 16 lg 24
+  radius sm 4 md 8 lg 16
+  font sans "system-ui, sans-serif" mono "ui-monospace, monospace"
+  screen sm 640 md 768 lg 1024
+  motion reduce respect
+```
+
+Numbers in `gap:` / `pad:` remain pixels; a name such as `gap:sm` resolves to
+`theme.space.sm`. `color:muted` resolves to `var(--vl-color-muted)`. Dark values
+apply through both `prefers-color-scheme` and `html[data-theme="dark"]`.
+
+`recipe button`, `recipe input`, and `recipe card` declare literal Tailwind
+classes as one `base`, orthogonal axes, and defaults. `card` is a grouping
+`<div>` with a child slot. Interactive recipes require a `focus-visible:`
+treatment and motion utilities require a `motion-reduce:` counterpart:
+
+```vl
+recipe button
+  base "rounded-md focus-visible:outline focus-visible:outline-accent"
+  variant primary "bg-accent text-white"
+  default variant:primary
+
+button "Save" variant:primary class:"w-full sm:w-auto"
+```
+
+`class:` is the only escape hatch and must be one complete, non-interpolated
+literal. It is additive: it may not share a property group with the resolved
+recipe, carry `!important`, or overlap a recipe with an inline visual attr.
+Class-token order never decides precedence. Runtime compatibility rules occupy
+a lower cascade layer, generated utilities a later layer, and inline attrs stay
+highest only on recipe-less elements. Every requested utility must emit a
+parsed CSS selector or the build fails `E-CLASS-NO-CSS`; `group` / `peer`
+markers are the sole bounded exemption. The complete diagnostics and conflict
+groups are normative in the Tailwind-backed styling design contract.
+
+### 8.8 Accessible primitives
+
+Two `std.ui` primitives carry accessibility by construction: an inaccessible dialog or tab set is not expressible, the same property §1.1 goal 4 gives security.
+
+**`dialog`** — a modal dialog.
+
+```vl
+if confirming
+  dialog title:"Discard changes?" on dismiss: confirming = false
+    text "This cannot be undone." color:muted
+    row gap:8 justify:end
+      button "Cancel" variant:ghost on tap: confirming = false
+      button "Discard" variant:danger on tap: discard()
+```
+
+`title` is required and becomes the accessible name. `on dismiss` is required and runs on `Escape`, on a backdrop click, and on the close affordance. The compiler emits: a portal above the page, `role="dialog"` with `aria-modal`, the rest of the page made `inert`, focus moved into the dialog and trapped there while it is open, and focus restored to the previously focused element when it closes.
+
+A dialog is shown by rendering it — an `if` that includes `dialog`, as above — and hidden by not rendering it. **There is no `open` attribute.** A closed dialog is absent from the tree, so a control inside it cannot be reached, focused, activated, or found while it is closed; "is the dialog open" and "is its subtree present" cannot drift apart.
+
+**`tabs` / `tab`** — a tab set. `tab` is valid only as a direct child of `tabs`.
+
+```vl
+tabs bind:tab
+  tab "overview" label:"Overview"
+    text "Overview panel"
+  tab "changelog" label:"Changelog"
+    text "Changelog panel"
+```
+
+`bind:tab` is a two-way binding to a `state` holding the selected tab id (§8.2 `bind`); the explicit form is `tabs selected:<id> on select t: …`. Each `tab` takes an id — the first positional value — and a required `label`. The compiler emits `role="tablist"` / `"tab"` / `"tabpanel"`, `aria-selected`, `aria-controls` / `aria-labelledby` wiring, a roving `tabindex`, and `Arrow` / `Home` / `End` key handling. Only the selected tab's panel is in the tree.
+
+**Scope.** This is two primitives, added because two real features (`corpus/views/11-modal`, `12-tabs`) could not otherwise be expressed accessibly. It is **not** a component library. `menu`, `tooltip`, `combobox`, `disclosure` and the rest are not part of the language; each is added only when a feature demands it, the same evidence-first discipline the rest of the toolchain follows. Raw `role` / `aria-*` / `tabindex` are not an attribute surface — a primitive carries them or they are absent.
+
+### 8.9 Accessible inputs
+
+`input` is accessible by construction, the same way `dialog` and `tabs` are: **an `input` with no programmatic label is not expressible.** Every `input` must carry an accessible name through exactly one of:
+
+```vl
+col gap:4
+  input label:"Email" bind:email type:email help:"We never share it." error:email_error
+  input aria_label:"Search posts" bind:q type:search
+```
+
+- **`label:<text>`** — a visible label. The compiler emits a `<label for=…>` bound to the control by a generated id (the compiler owns both ends, so the pair cannot drift or be forgotten) and the text is the accessible name. Help and error text are rendered as siblings, never inside the label, so the name stays exactly the label text.
+- **`aria_label:<text>`** — an accessible name with **no** visible label, for a control whose purpose is already clear from adjacent visible content (a search field beside a search icon). Emits `aria-label`.
+
+**Exactly one, and never empty.** Giving both `label:` and `aria_label:` on one `input` is `E-INPUT-NAME-DUP` (a visible label plus a silent `aria-label` override is ambiguous — keep the visible one). A `label:` / `aria_label:` whose value is a statically empty or whitespace-only string is `E-INPUT-NAME`, the same as no name at all. A name that is a non-empty expression at build time but evaluates to empty / whitespace at **render** time raises `render.empty_input_name` — a control is never rendered without a name.
+
+**One id per rendered instance.** The generated `for` / `id` / `aria-describedby` ids are allocated per *rendered field*, not per source site, so a component used many times or a keyed-list row each gets its own label / help / error ids; every `<label>` activates its own control and every `aria-describedby` resolves within its own field. The links are rebuilt from one base each render, so they stay consistent across insertion and reordering. (The id *strings* are not stable across re-renders — like per-row handlers in a keyed list, they are refreshed each pass; the accessible name and the described text are what is stable.)
+
+`placeholder:` is **not** a label. It vanishes on the first keystroke, is exempt from contrast rules, and is skipped by some assistive tech. An `input` that has only `placeholder:` — or neither — is `E-INPUT-NAME`, an error, with the fix naming `label:` / `aria_label:`. `placeholder:` remains legal as a *supplement* to a real name.
+
+Two optional association attributes, both wired by the compiler so the author cannot forget the link:
+
+- **`help:<text>`** — persistent helper text, rendered after the control and referenced from the control's `aria-describedby`.
+- **`error:<text?>`** — a validation message. The expression is `nil` / empty while the field is valid. When it holds a message the compiler renders it, adds it to `aria-describedby`, and sets `aria-invalid="true"` on the control; when it is empty the live error region remains present but empty, without an error association or `aria-invalid` (§8.12). Typically a `derive` (§8.1), as in `corpus/views/08-validated-form`.
+
+**Scope.** This slice is the `input` primitive: its name, its help text, and its error association / invalid state. Live error/status semantics are defined in §8.12; page titles and heading/landmark structure are defined in §8.11. As with §8.8, raw `aria-*` is not an attribute surface: the primitive carries these or they are absent.
+
+---
+
+### 8.10 Accessible images
+
+`img` is accessible by construction, the same way `input` is (§8.9): **an `img` with no declared alternative is not expressible.** Every `img` states its alternative through exactly one form of a single `alt:` attribute:
+
+```vl
+col gap:8
+  img src:hero            alt:"The team on stage at the launch"
+  img src:user.avatar_url alt:"{user.name}'s profile photo"
+  img src:"divider.svg"   alt:decorative
+  img src:chart_png       alt_todo:"bar chart of weekly signups — confirm axis labels"
+```
+
+- **`alt:<text>`** — meaningful alternative text: what the image conveys, for a reader who cannot see it. Emits `alt="<text>"`. A dynamic value (`alt:"{caption}"`) is checked at render: an `alt:` that resolves to empty / whitespace raises `render.empty_alt` rather than silently emitting `alt=""` — the author said the image is meaningful, so an empty value contradicts the declaration.
+- **`alt:decorative`** — the bare word `decorative`: the image is purely presentational (a rule, a texture, an icon that only repeats adjacent text). Emits `alt=""`, the WAI-ARIA-sanctioned signal for "assistive tech may skip this". A *statically* empty `alt:""` is `E-IMG-ALT`, not a synonym for this — say `decorative` when that is the intent.
+- **`alt:todo`** / **`alt_todo:<text>`** — a development placeholder: real alt text is owed but not written. The build still emits a navigable `alt` (`alt_todo:`'s note, or `"TODO: describe this image"` for the bare `alt:todo`), and plain `vlcheck` / `vlbuild` **warn** (`W-IMG-ALT-TODO`). `vlcheck --release` / `vlbuild --release` promote it to `E-IMG-ALT-TODO` — the ship gate that fails a build with any unresolved placeholder.
+
+An `img` with none of these is `E-IMG-ALT`; with more than one (e.g. `alt:` and `alt_todo:` together) it is `E-IMG-ALT-ONE`. As with §8.8 / §8.9, raw `aria-*` / `role` are not an attribute surface.
+
+**Scope.** This slice is the `img` primitive's alternative text. Live error/status semantics are defined in §8.12.
+
+---
+
+### 8.11 Page title, headings, and landmarks
+
+A build produces one document, rendered by a **root view** (§8, the no-argument view `VL.mount` mounts). That document — not any reusable `view` — is the page. Navigation between pages is a full browser navigation; there is no client-side router.
+
+**Page title.** A module that builds as a page declares one, at module scope:
+
+```vl
+page title:"Weekly Report"
+```
+
+`title:` is an expression evaluated at module scope (a literal, or something a module-level `fn` / config produces — not view state). It becomes the document `<title>` when it is a literal, and is assigned to `document.title` at boot regardless, so a full navigation to another page picks up that page's own title. `page` with no `title:`, or a statically empty one, is `E-PAGE-TITLE`; a build that renders a page with no `page` declaration at all is refused (`E-PAGE-TITLE` at build time). A `title:` expression that resolves to empty at load time raises `render.empty_page_title`. One `page` per module (`E-PAGE-DUP`).
+
+**Headings.** `h1`…`h6` are `std.ui` primitives that emit the real HTML heading elements. The level is **semantic and independent of visual size** — `h2 "…" size:28` is a second-level heading that happens to be large. Within one view, a heading that jumps more than one level below the previous one is `W-HEADING-SKIP`, and a second `h1` is `W-HEADING-MULTI-H1` — warnings, not errors, and scoped to a single view so a reusable component that legitimately starts at `h2` or `h3` under some page's `h1` is never flagged.
+
+**Landmarks.** `main` and `nav` are `std.ui` primitives emitting `<main>` / `<nav>`. There is one `main` region per page (`E-MAIN-DUP` for two in a view). A `nav` takes `aria_label:` (emitted as `aria-label`); when a view has more than one `nav`, each **must** carry a distinct name (`E-NAV-NAME`) so assistive tech can tell them apart. These rules hold on the **composed** document, not just within one view: a `main` in the page-root view and in a view it renders (or a view whose `main` is reused) is `E-MAIN-COMPOSED` — every `main` emits `id="vl-main"`, so a second one is also a duplicate id and an ambiguous skip target; two `<nav>`s assistive tech cannot tell apart — both unnamed, or sharing one `aria_label:` — from different composed views are likewise `E-NAV-NAME`; and one static `id:` rendered by more than one element is `E-ID-DUP`. The composed pass follows component instantiation within a module from the page root and treats `if` / `else` branches as mutually exclusive (a landmark in both branches counts once); it does not evaluate conditions, and cross-file `use` composition is not yet followed.
+
+**Skip link.** When the page renders a `main` landmark, the compiler tags it with a stable id and `tabindex="-1"` and injects a **"Skip to main content"** link as the first thing in the tab order, off-screen until focused and then visible (styled `.vl-skip`). Activating it moves focus into `main`. The author writes nothing.
+
+As with §8.8–§8.10, raw `role` / `aria-*` are not an attribute surface.
+
+**Scope.** This slice is the page title, heading elements, the `main` / `nav` landmarks, and the skip link. These structural checks do not prove a page is accessible or replace screen-reader testing. Live error/status semantics are defined in §8.12.
+
+---
+
+### 8.12 Live status and validation feedback
+
+`status <message>` is a text-only `std.ui` primitive. It takes exactly one
+string-or-nil expression, no attributes and no children (`E-STATUS-SHAPE`
+with a repair example otherwise). This bounded form does not expose raw ARIA,
+priority switches or focus controls.
+
+```vl
+view Feedback()
+  state message = ""
+  status message
+  button "Save"
+    on tap
+      message = "Saved."
+```
+
+Keep the status element mounted, using nil or an empty string while idle,
+rather than conditionally inserting a populated region. The compiler emits a
+span with `role="status"`, `aria-live="polite"`, and `aria-atomic="true"`.
+The region remains exposed when empty. A non-string/non-nil runtime value
+raises `render.invalid_status`. Initial populated content is visible but is
+not promised to be announced; the contract concerns subsequent updates.
+
+An input declaring `error:` automatically gets the same polite atomic
+live-region behavior in its existing error span, outside the label. The
+region is present even when empty, without `hidden` or `display:none`.
+Non-empty errors still participate in `aria-describedby` and set
+`aria-invalid`; clearing removes those error associations and the invalid
+state, but retains the empty region.
+
+For a retained element, the runtime updates the existing text node only when
+its value changes. Unrelated renders and repeated assignment of the same
+message do not rewrite it. Clearing and subsequently setting a message allows
+a new update. There is no automatic reannouncement of an unchanged error on
+repeated submission. Updates do not move focus. Regions in dialogs live inside
+the dialog portal, not in an inert background or a global announcement queue.
+
+Authors choose when to expose validation errors (for example after submission
+or blur) and supply useful context in messages. The compiler cannot infer that
+ordinary dynamic `text` is a status message. Structural removal/reinsertion
+does not preserve region identity, and no speech guarantee is made for it.
+
+**Evidence boundary.** Browser checks establish live-region properties,
+in-place text mutation, unchanged-message suppression, clearing and portal
+behavior. They do not establish audible output, announcement order for multiple
+simultaneous regions, or screen-reader interoperability. Manual AT testing
+remains required. This follows the pre-existing-region approach in
+[W3C ARIA22](https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22);
+[ARIA19](https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA19) discusses error
+notification. Polite feedback is the language default; urgent alerts are
+outside this slice.
+
+---
+
+### 8.13 Project preferences and automation hooks
+
+The checker and builder read versioned `volaro.json`, independently of agent
+chat history. Version 1 is a JSON object with required integer
+`"schema_version": 1` and optional `"testing": {"emit_ids": true}`.
+The default is true. Unknown keys, duplicate JSON keys, wrong types and
+unsupported versions are errors (E-CONFIG-JSON / E-CONFIG-OPTION /
+E-CONFIG-VERSION); unreadable files are E-CONFIG-READ. A config found under the
+former name `volara.json` is E-CONFIG-LEGACY, never a silent skip and never a
+silent fallback to defaults. No accessibility opt-out or not-yet-supported
+wizard setting is accepted.
+
+Discovery starts at the entry source directory, selects the nearest
+`volaro.json`, and stops at a Git worktree boundary (a .git file or directory)
+or filesystem root. An explicit `--config PATH` selects exactly that file
+relative to the command's working directory. A bad nearest file is an error,
+not a fallback. A `volara.json` at or above the entry directory — or named by
+`--config` — raises E-CONFIG-LEGACY naming the `volara.json` → `volaro.json`
+rename, and if both names sit in one directory that is also E-CONFIG-LEGACY.
+Builds never write configuration. Included modules use the entry
+settings. No secrets or environment credentials belong in this file.
+
+`test_id:"save"` emits `data-testid="save"`. IDs are static, non-interpolated
+lowercase slugs matching `[a-z][a-z0-9-]{0,79}`. Empty/invalid/duplicate
+attributes and unsupported targets are E-TEST-ID. Supported targets are
+col/row/stack/grid/card/text/img/button/input/link/spacer, h1–h6, main/nav,
+and status. Input hooks attach to the input, not its field wrapper. Hook names
+do not replace HTML IDs, accessible names, or reconciliation keys.
+
+`test_scope:<string expression>` creates a namespace for its element and
+descendants, including local component calls and dialog content. Joined IDs
+use slash separators: `editor/name`. Each scope segment obeys the same slug
+rule. Static invalid scopes are E-TEST-ID-SCOPE; dynamic invalid scopes raise
+`render.invalid_test_scope` without echoing the value. Component calls,
+dialog and tabs may carry scopes, but not direct test_id hooks. Individual
+tab headers do not support either attribute in this pass; unsupported targets
+fail rather than being silently ignored.
+
+Repeated rows author an explicit stable public scope on their row or component.
+The compiler NEVER derives scope from the list key, index, label or source
+location. Authors must not use emails, credentials, tokens or private record
+identifiers. Validation cannot establish that an otherwise valid value is
+non-sensitive or stable; review remains required.
+
+Provable simultaneous literal collisions are E-TEST-ID-DUP. Static analysis
+expands local views, adds sibling counts and takes maximum per-ID counts over
+if/else alternatives; repeated literal scopes collide. Dynamic scopes and
+relationships not statically known are checked during rendering. The next
+render uses a fresh registry spanning page and prepared portals; a collision
+raises `render.duplicate_test_id` before committing the new page or portals,
+preserving the preceding valid DOM. Scope identity survives keyed reordering.
+Closed/removed content may reuse its IDs on a later render.
+
+With emission disabled, no hook attributes, scope-expression evaluation or
+hook registry calls are emitted in application code. Static validation still
+runs. Accessibility, handlers and reconciliation behaviour are unchanged;
+dynamic-hook errors are emission-only. Existing single-module view compilation
+boundaries remain: this does not add cross-file view loading or a router.
+
+## 9. Outbound API integration
+
+An `api` block declares a client for a service someone else runs.
+
+```vl
+api blog
+  base "https://api.example.com/v2"
+  auth bearer env.BLOG_TOKEN
+  timeout 10s
+  retry 3 backoff:exp on:[429, 502, 503, 504]
+  rate 100/min
+
+  headers
+    accept "application/json"
+
+  get list_posts(topic str, limit int = 20) list<Post>
+    path "/posts"
+    query topic, limit
+
+  get get_post(id uuid) Post!
+    path "/posts/{id}"
+
+  post create_post(body NewPost) Post!
+    path "/posts"
+
+  delete remove_post(id uuid) nil!
+    path "/posts/{id}"
+```
+
+Each endpoint becomes a function at `blog.list_posts(...)`, namespaced under the block name. Path parameters interpolate from the parameter list by name and are URL-escaped. `query` names which parameters go in the query string.
+
+Where an unrouted parameter goes depends on whether the method carries a request body. For `get`, `delete`, and `head` a parameter that is in neither the path nor `query` has nowhere to go: it is a compile error, so a forgotten parameter never silently disappears. For `post`, `put`, and `patch` the unrouted parameters form the request body — a parameter named `body` is sent as the body verbatim, and any other unrouted parameters are collected into a JSON object keyed by parameter name.
+
+Response bodies decode into the declared type. A field present in the type and missing from the response is a runtime `Err` with code `decode.missing_field` and the JSON pointer in `fields`. A field present in the response and absent from the type is ignored.
+
+`timeout` defaults to `30s` when the block omits it; `timeout none` disables it, and is the only way to make a call that can hang forever. `retry` applies only to idempotent methods unless `retry ... idempotent:true` is stated on a `post`. `rate` throttles client-side with a token bucket shared across the process.
+
+### 9.1 Generating a client from a schema
+
+```vl
+api stripe from openapi("./schemas/stripe.json")
+  auth bearer env.STRIPE_KEY
+  timeout 30s
+```
+
+The compiler reads the schema at build time and generates typed endpoints. Overrides are written in the block body and take precedence over the schema.
+
+---
+
+## 10. Inbound services
+
+A `service` block declares HTTP routes the application serves.
+
+```vl
+service api
+  prefix "/api/v1"
+
+  get /posts(topic str?, limit int = 20) list<Post>!
+    db.posts.where(topic: topic).limit(limit).all()?
+
+  get /posts/:id Post!
+    db.posts.get(id)?
+
+  post /posts(body NewPost) Post!
+    auth role:author
+    let post = db.posts.insert(body, author_id: session.user.id)?
+    events.emit("post.created", post.id)
+    post
+
+  patch /posts/:id(body PostPatch) Post!
+    auth owner:db.posts.get(id)?.author_id
+    db.posts.update(id, body)?
+
+  delete /posts/:id nil!
+    auth role:admin
+    db.posts.delete(id)?
+```
+
+Path parameters are typed from the route pattern and available as bindings. `:id` in a route whose handler expects `uuid` parses and validates before the body runs; a malformed value returns 400 without entering user code.
+
+Return values serialize to JSON. A `T!` handler maps error codes to status codes through a table declared once:
+
+```vl
+service api
+  errors
+    not_found -> 404
+    forbidden -> 403
+    conflict -> 409
+    _ -> 500
+```
+
+Unmapped error codes return 500 and log the full error with cause chain. The response body for a 500 never includes the internal message.
+
+**Public routes.** A route with no `auth` line is public, and the compiler warns when more than half of a service's routes are public, on the assumption that the guards were forgotten. A service that is *meant* to be public says so once and the warning does not apply:
+
+```vl
+service content public          # every route is public unless it says otherwise
+  get /posts list<Post>!
+  get /posts/:id Post!
+
+  post /posts(body NewPost) Post!
+    auth role:author            # a guard still overrides, per route
+```
+
+A single deliberately public route inside an otherwise guarded service uses `auth none`, which is distinct from omitting the line: it records the decision, and it silences the warning for that route only.
+
+```vl
+  get /health str
+    auth none
+```
+
+`auth none` on a write route (`post`/`put`/`patch`/`delete`) is still a warning, because an unauthenticated write is a different claim from an unauthenticated read and deserves a second look.
+
+A `service` also generates a typed client under its own name, so view code calls `api.posts(limit: 20)` and gets a `list<Post>` back with no URL string, no fetch wrapper, and no hand-written response type. Changing a route signature breaks its callers at compile time, which is the property a hand-rolled client never has.
+
+**Generated method names.** The name comes from the route's path *and* its HTTP method, not its handler. Three shapes, chosen by where the path parameters sit:
+
+1. **Collection** — no path parameters. `get` keeps the last segment as written (`get /posts` → `api.posts(...)`); `post` is `create_<singular>` (`post /posts` → `api.create_post(...)`); `put`/`patch` are `update_<singular>`; `delete` is `delete_<singular>`.
+2. **Item** — the path ends in a parameter. `get` is the singularised last non-parameter segment (`get /posts/:id` → `api.post(id: ...)`); `post` is `create_<singular>`; `put`/`patch` are `update_<singular>`; `delete` is `delete_<singular>` (`delete /posts/:id` → `api.delete_post(id: ...)`).
+3. **Action** — the path ends in a non-parameter segment but has a parameter earlier. The name is that segment verbatim, for any method (`post /posts/:id/publish` → `api.publish(id: ...)`).
+
+Singularisation strips a trailing `es` after `s`, `x`, `z`, `ch`, `sh`, then a trailing `s`; a name that neither rule changes gets the suffix `_item` (`/data/:id` → `api.data_item`).
+
+Path parameters become required named arguments, in path order, before any query or body arguments.
+
+Two routes generating the same name is a compile error naming both — a single namespace, regardless of method. Disambiguate with `as`:
+
+```vl
+get /users/:id/avatar File!                 # action → api.avatar(id:)
+get /teams/:id/avatar File! as team_avatar  # would also be `avatar` — clashes
+```
+
+Method names are part of the service's public surface: renaming a path renames the client call and breaks callers at compile time, which is the intent.
+
+### 10.1 Middleware
+
+```vl
+service api
+  before
+    log.request()
+    cors(origins: ["https://app.example.com"])
+
+  after
+    log.response()
+```
+
+`before` runs in declaration order and short-circuits on the first error. There is no `next()` call to forget.
+
+---
+
+## 11. Authentication and authorization
+
+The `auth` block is declared once per project.
+
+```vl
+auth
+  user User                       # the record sessions attach to
+  identity email                  # the field used as login identity
+
+  provider password
+    min_len 12
+    breached_check true
+    verify_email true
+
+  provider oauth google
+    client_id env.GOOGLE_CLIENT_ID
+    secret env.GOOGLE_SECRET
+    scopes ["openid", "email", "profile"]
+
+  provider totp
+    issuer "Example"
+    required_for [admin]
+
+  session
+    store cookie
+    ttl 30d
+    idle_timeout 12h
+    rotate_on_login true
+    rotate_on_privilege_change true
+
+  roles admin, author, member
+  default_role member
+```
+
+### 11.1 What the compiler guarantees
+
+These properties hold with no way to disable them from Volaro source:
+
+- Passwords hash with Argon2id at parameters the compiler pins and updates by release. There is no field type that stores a plaintext password and no library call that accepts one.
+- Session cookies are `HttpOnly`, `Secure`, and `SameSite=Lax` (`Strict` when no OAuth provider is declared). The names and flags are not user-settable.
+- State-changing routes (`post`, `patch`, `put`, `delete`) require a valid CSRF token when the session store is `cookie`. The token is issued and checked without appearing in application code.
+- Session identifiers are 256 bits from the platform CSPRNG, stored hashed, and rotated on login and on any role change.
+- Login, password reset, and TOTP verification routes are rate-limited by identity and by source address.
+- Timing-safe comparison is the only comparison available for secrets, tokens, and hashes.
+- Password reset tokens are single-use, expire in 30 minutes, and never appear in logs or error messages.
+- Email verification tokens carry the same discipline with a longer life: single-use, expiring in 24 hours, stored hashed, and never appearing in logs, error messages, or response bodies. Redeeming one marks the account verified through the auth API. This does not make the model's `verified` field compiler-owned or prohibit ordinary model updates to it.
+
+An audit of generated authentication code usually finds two or three of these missing. Moving them below the source line means a generator cannot omit them.
+
+These guarantees cover *who may call a route*. They do **not** yet cover *what a caller may see*: nothing stops `db.posts.get(id)` from returning a row outside a record's intended public scope (e.g. an unpublished `Post`). Data-scope authorization is open question §20.7.
+
+### 11.2 Guards
+
+```vl
+auth required                   # any signed-in user
+auth role:admin                 # role check
+auth role:[admin, author]       # any listed role
+auth owner:post.author_id       # session user owns the resource
+auth optional                   # populate session if present, allow if not
+```
+
+A route with no `auth` line is public, and the compiler warns once per project if more than half the routes are public, which catches the case where a generator forgot the guards entirely.
+
+Inside a guarded handler, `session.user` is the non-optional user record. Inside an `auth optional` handler it is `User?`. The type difference is what stops a null dereference.
+
+Guards do not currently compose. In particular, there is no declarative form
+for the common policy “an administrator **or** this resource's owner.” Writing
+that comparison in the handler is possible, but makes authorization omissible
+application code and therefore weakens goal 4 in §1.1. This is an explicit v0.3
+language gap, not an idiomatic workaround; see open question §20.8.
+
+### 11.3 Auth in views
+
+```vl
+view Nav()
+  row gap:16
+    link "Home" to:"/"
+    if session.user
+      link "Write" to:"/new"
+      if session.user.role == admin
+        link "Admin" to:"/admin"
+      button "Sign out" on tap: auth.sign_out()
+    else
+      link "Sign in" to:"/login"
+```
+
+The client-side surface is eight calls. Each returns a fallible value with a documented error union, so a form handles failures by name rather than by string matching an error message.
+
+| Call | Returns | Error union |
+|---|---|---|
+| `auth.sign_up(email:, password:)` | `Session!` | `email_taken`, `weak_password`, `breached_password`, `rate_limited(retry_after dur)` |
+| `auth.sign_in(email:, password:)` | `Session!` | `invalid_credentials`, `unverified_email`, `totp_required`, `rate_limited(retry_after dur)` |
+| `auth.sign_out()` | `nil!` | — |
+| `auth.start_oauth(provider)` | `nil!` | `provider_error`, `rate_limited(retry_after dur)` |
+| `auth.reset_password(email:)` | `nil!` | `rate_limited(retry_after dur)` |
+| `auth.confirm_reset(token:, password:)` | `Session!` | `invalid_token`, `expired_token`, `weak_password`, `breached_password` |
+| `auth.confirm_verify(token:)` | `Session!` | `invalid_token`, `expired_token` |
+| `auth.verify_totp(code:)` | `Session!` | `invalid_code`, `no_totp_enrolled`, `rate_limited(retry_after dur)` |
+
+`sign_up` returns a session only when `verify_email false`; with `verify_email true` (the default) it returns after sending the verification mail and the caller routes to a "check your email" state. `confirm_verify` is the other half of that flow, and without it `verify_email true` has no exit: it redeems the token from that mail, marks the account verified, and establishes a session. **Because it returns `Session!`, a successful confirmation also signs the user in** — the newcomer follows the link and lands in the application authenticated, with no sign-in form in between. A caller that presents one anyway is asking an already-authenticated user to prove themselves twice. `reset_password` never reveals whether the address is registered: it succeeds uniformly for known and unknown addresses. `confirm_reset`, `confirm_verify` and `verify_totp` establish a fresh session and rotate the session id, so no separate sign-in call follows them.
+
+`start_oauth` takes a bare provider name matching a `provider oauth <name>` declaration in the `auth` block (`auth.start_oauth(google)`).
+
+---
+
+## 12. Concurrency
+
+Every IO operation is asynchronous. There is no `async` keyword and no `await`, because the color of a function is derivable from its body and carrying it in the signature adds tokens without adding information. The compiler computes it and the type system enforces the same rules a colored system would.
+
+Sequential code is sequential:
+
+```vl
+let user = db.users.get(id)?
+let posts = db.posts.by_author(user.id)?
+```
+
+Parallel code says so:
+
+```vl
+par
+  let user = db.users.get(id)?
+  let posts = blog.list_posts(topic: "rust")?
+  let quota = billing.quota(id)?
+```
+
+Bindings inside `par` start together and are available after the block. A failure in any branch cancels the others and propagates.
+
+Background work is explicit and does not block a response:
+
+```vl
+spawn
+  mailer.send_welcome(user.email)
+```
+
+A spawned task that fails logs and does not affect the caller. Fire-and-forget is the only spawn form; anything needing a result uses `par`.
+
+`spawn` is legal in a view body, including inside an event handler. Unlike `load` (§8.4), a spawned task is not cancelled when the view unmounts: it runs to completion, and a failure logs without affecting the view.
+
+---
+
+## 13. Standard library surface
+
+The library is small on purpose. A large surface is a large thing to remember and a large thing to hallucinate.
+
+| Module | Contents |
+|---|---|
+| `std.ui` | layout and input components, auto-imported in views |
+| `std.http` | request, response, status codes, header helpers |
+| `std.db` | query builder, migrations, transactions |
+| `std.time` | `now`, formatting, parsing, arithmetic on `time` and `dur` |
+| `std.str` | split, join, trim, case, replace, regex |
+| `std.list` | map, filter, fold, sort_by, group_by, take, chunk, concat, append |
+| `std.map` | keys, values, merge, get_or |
+| `std.json` | encode, decode, pointer access |
+| `std.crypto` | random bytes, hashing, timing-safe compare |
+| `std.log` | structured logging at five levels |
+| `std.test` | assertions, fixtures, HTTP and view test harnesses |
+| `std.sync` | reference cells, channels, mutex |
+| `std.ffi` | Rust boundary |
+
+### 13.1 Database access
+
+```vl
+model Post
+  id uuid pk
+  title str
+  body text
+  author_id uuid ref:User.id
+  published bool = false
+  created_at time = now()
+
+  index (author_id, created_at desc)
+```
+
+`model` is a record with persistence. Migrations generate from the diff between committed models and the database schema, and `vl migrate` applies them with a printed plan and a required confirmation for destructive steps.
+
+Queries are typed:
+
+```vl
+db.posts
+  .where(published: true, author_id: user.id)
+  .order(created_at: desc)
+  .limit(20)
+  .all()?
+```
+
+A bare value in `where` is exact equality, as above. A **comparison predicate**
+wraps the value instead of matching it, for everything equality can't express —
+`where` still ANDs one predicate per named column:
+
+```vl
+db.posts
+  .where(published: true, created_at: lt(cursor))
+  .order(created_at: desc)
+  .limit(20)
+  .all()?
+```
+
+| predicate | SQL |
+|---|---|
+| `lt(x)` / `lte(x)` | `< x` / `<= x` |
+| `gt(x)` / `gte(x)` | `> x` / `>= x` |
+| `ne(x)` | `!= x` |
+| `between(lo, hi)` | `BETWEEN lo AND hi` |
+| `any_of(xs)` | `IN (xs…)` — `xs` a `list<T>`; an empty list matches no rows |
+
+Each predicate lowers to exactly one parameterized SQL fragment — there is no
+way to interpolate a raw comparison, and the emitter rejects a `where` value
+it does not recognize (a call to any name outside this table) rather than
+silently binding it as an opaque parameter. `where` composes **only** by AND
+across its named arguments; there is no `or` or nested-boolean form. A query
+needing one is a `db.raw` case, not a reason to grow this table speculatively
+— add the next predicate when a real feature needs it, the same discipline
+`std.ui` follows for accessible primitives (§8.8).
+
+Raw SQL is available through `db.raw("...", args)` and returns `list<json>`, forcing an explicit decode. Interpolation into `db.raw` is a compile error; parameters are positional only.
+
+
+---
+
+## 14. Token economy
+
+The claim to test is that a feature costs fewer tokens in Volaro. Here is one feature, written both ways: a sign-in form that posts credentials, handles four failure modes, and redirects on success.
+
+### 14.1 Volaro
+
+```vl
+view SignIn()
+  state email = ""
+  state password = ""
+  state error str? = nil
+
+  col gap:12 pad:24 max_w:360
+    text "Sign in" size:24 weight:600
+    input bind:email type:email placeholder:"Email"
+    input bind:password type:password placeholder:"Password"
+    if error
+      text error color:danger size:13
+    button "Sign in" variant:primary
+      on tap
+        error = nil
+        try auth.sign_in(email: email, password: password)
+        catch invalid_credentials
+          error = "Wrong email or password."
+        catch unverified_email
+          route.to("/verify")
+        catch rate_limited(retry_after)
+          error = "Too many attempts. Try again in {retry_after}."
+        catch e
+          error = "Something went wrong."
+        route.to("/")
+```
+
+24 lines, 768 characters.
+
+### 14.2 The same feature on a React, Express, and Passport stack
+
+The equivalent needs a client component with four `useState` hooks and a submit handler, a `POST /login` route, a Passport local strategy, a session middleware configuration, a bcrypt comparison, and a rate limiter registration. Across those files the working version runs 180 to 220 lines and 5,500 to 6,500 characters, before the imports.
+
+### 14.3 Ratio
+
+**Measured, 2026-09-03** (`o200k_base`, 7 hand-written features, both arms, against Next.js 15 + Auth.js v5 + Prisma + `@node-rs/argon2` — a stack that already collapses much of the boilerplate):
+
+| | per feature |
+|---|---|
+| Volaro | 297 tokens |
+| baseline | 1 192 tokens |
+| **ratio** | **4.01×** |
+
+That is below the 5:1–8:1 the earlier draft projected, and the band structure is not what was predicted either: the widest feature is TOTP (7.0×) and the narrowest so far is a list-and-detail view (2.2×), so "views are the wide end" does not hold against modern server components. Authentication is where the claim is strongest.
+
+The number that matters for an agent is context: a feature costs 895 fewer tokens to hold in a window, so a 40-feature codebase is 3.5× cheaper to work in, and the ~1 700-token generation cheatsheet pays for itself after two files.
+
+Seven of the planned forty features are written. The measurement is provisional in n, not in method.
+
+### 14.4 Reading cost
+
+Generation cost is only half the number. A model editing an existing project spends most of its budget reading. `vl map` emits the project surface:
+
+```
+view SignIn()
+view Feed(topic str)
+view UserCard(user User, compact bool = false)
+model Post{id, title, body, author_id -> User.id, published, created_at}
+model User{id, email, name?, role, created_at}
+service api GET  /api/v1/posts(topic str?, limit int) -> list<Post>!  public
+service api POST /api/v1/posts(body NewPost) -> Post!  auth:role[author]
+api blog GET list_posts(topic str, limit int) -> list<Post>
+auth providers[password, oauth:google, totp] roles[admin, author, member]
+```
+
+One line per surface element. A 6,000-line project produces a map of roughly 300 lines, so the whole shape of the application fits in a few thousand tokens and a model reads only the files it intends to change.
+
+---
+
+## 15. Worked example
+
+A complete application: a blog with public reading, authenticated writing, and an outbound call to a moderation API.
+
+```vl
+# src/models.vl
+use std.time { now }
+
+type Role = admin | author | member
+
+model User
+  id uuid pk
+  email str unique
+  name str?
+  role Role = member
+  created_at time = now()
+
+model Post
+  id uuid pk
+  title str
+  body text
+  author_id uuid ref:User.id
+  published bool = false
+  created_at time = now()
+
+  index (published, created_at desc)
+
+type NewPost
+  title str
+  body text
+```
+
+```vl
+# src/auth.vl
+use ./models { User }
+
+auth
+  user User
+  identity email
+
+  provider password
+    min_len 12
+    breached_check true
+    verify_email true
+
+  session
+    store cookie
+    ttl 14d
+    rotate_on_login true
+
+  roles admin, author, member
+  default_role member
+```
+
+```vl
+# src/api.vl
+use ./models { Post, NewPost }
+
+api moderation
+  base "https://mod.example.com/v1"
+  auth bearer env.MOD_TOKEN
+  timeout 5s
+  retry 2 backoff:exp on:[429, 503]
+
+  post check(text str) Verdict!
+    path "/check"
+
+type Verdict
+  allowed bool
+  reason str?
+
+service api
+  prefix "/api"
+
+  errors
+    not_found -> 404
+    forbidden -> 403
+    rejected -> 422
+    _ -> 500
+
+  get /posts(limit int = 20) list<Post>!
+    db.posts.where(published: true).order(created_at: desc).limit(limit).all()?
+
+  get /posts/:id Post!
+    db.posts.get(id)?
+
+  post /posts(body NewPost) Post!
+    auth role:[author, admin]
+    let verdict = moderation.check(text: body.body)?
+    if not verdict.allowed
+      return err(rejected(verdict.reason ?? "content rejected"))
+    db.posts.insert(body, author_id: session.user.id)?
+
+  delete /posts/:id nil!
+    auth owner:db.posts.get(id)?.author_id
+    db.posts.delete(id)?
+```
+
+```vl
+# src/views/Feed.vl
+use ../models { Post }
+
+view Feed()
+  load posts = api.posts(limit: 20)
+    pending
+      Spinner()
+    error e
+      col gap:8 pad:24
+        text "Could not load posts." color:danger
+        button "Retry" on tap: posts.reload()
+
+  col gap:16 pad:24 max_w:720
+    row justify:between align:center
+      text "Latest" size:28 weight:700
+      if session.user and session.user.role != member
+        link "Write" to:"/new"
+
+    if posts.len() == 0
+      text "Nothing published yet." color:muted
+    list posts as p key:p.id
+      col gap:4
+        link p.title to:"/posts/{p.id}" size:18 weight:600
+        text p.created_at.format("MMM d, yyyy") size:13 color:muted
+```
+
+Four files, 109 lines, and the result is a deployable application with hashed passwords, rotated sessions, CSRF protection on the write routes, a retrying moderation client, keyed list rendering, and a loading state.
+
+---
+
+## 16. Grammar
+
+Core grammar in EBNF. `NL`, `INDENT`, and `DEDENT` are lexer-synthesized tokens. `block(X)` abbreviates `NL INDENT X+ DEDENT`.
+
+```ebnf
+program     = { item } ;
+item        = use | type_decl | model_decl | fn_decl | view_decl
+            | api_decl | service_decl | auth_decl | theme_decl ;
+
+use         = "use" path [ "{" ident { "," ident } "}" ] NL ;
+path        = ident { "." ident } | rel_path ;
+
+type_decl   = "type" TypeName ( record_body | "=" union_body | "=" type ) ;
+record_body = block( field ) ;
+field       = ident type [ "=" expr ] NL ;
+union_body  = variant { "|" variant } NL
+            | block( variant ) ;
+variant     = ident [ "(" param { "," param } ")" ] ;
+
+model_decl  = "model" TypeName block( field | index_decl ) ;
+index_decl  = "index" "(" ident [ "desc" ] { "," ident [ "desc" ] } ")" NL ;
+
+fn_decl     = [ doc ] "fn" ident "(" [ params ] ")" [ type ] block( stmt ) ;
+params      = param { "," param } ;
+param       = ident type [ "=" expr ] ;
+
+type        = TypeName [ "<" type { "," type } ">" ]
+            | prim
+            | type "?"
+            | type "!" [ type ]
+            | "fn" "(" [ type { "," type } ] ")" type ;
+
+stmt        = let | assign | if_stmt | match_stmt | for | while
+            | "break" NL | "skip" NL | "return" [ expr ] NL
+            | par | spawn | try_stmt | expr NL ;
+
+let         = "let" [ "mut" ] ident [ type ] "=" expr NL ;
+assign      = lvalue ( "=" | "+=" | "-=" | "*=" | "/=" ) expr NL ;
+
+if_stmt     = "if" expr block( stmt ) { "else" "if" expr block( stmt ) }
+              [ "else" block( stmt ) ] ;
+match_stmt  = "match" expr block( arm ) ;
+arm         = pattern [ "if" expr ] "->" ( expr NL | block( stmt ) ) ;
+
+for         = "for" ident [ "," ident ] "in" expr block( stmt ) ;
+while       = "while" expr block( stmt ) ;
+par         = "par" block( let ) ;
+spawn       = "spawn" block( stmt ) ;
+try_stmt    = "try" expr NL { "catch" pattern block( stmt ) } ;
+
+view_decl   = "view" TypeName "(" [ params ] ")" block( view_stmt ) ;
+view_stmt   = "state" ident [ type ] "=" expr NL
+            | "derive" ident "=" expr NL
+            | load_stmt
+            | "on" lifecycle block( stmt )
+            | "list" expr "as" ident "key" ":" expr block( view_stmt )
+            | element
+            | if_stmt | match_stmt | stmt ;
+load_stmt   = "load" ident "=" expr
+              block( "pending" block( view_stmt )
+                   | "error" ident block( view_stmt ) ) ;
+lifecycle   = "mount" | "unmount" | "change" ident { "," ident } ;
+element     = TypeName { attr } [ block( view_stmt ) ] NL ;
+attr        = ident ":" expr ;
+
+api_decl    = "api" ident [ "from" expr ] block( api_setting | endpoint ) ;
+endpoint    = method ident "(" [ params ] ")" type block( ep_setting ) ;
+ep_setting  = "path" str NL | "query" ident { "," ident } NL | "body" ident NL ;
+
+service_decl= "service" ident block( svc_setting | route ) ;
+route       = method route_path [ "(" params ")" ] type block( route_stmt ) ;
+route_stmt  = "auth" guard NL | stmt ;
+guard       = "required" | "optional" | "role" ":" role_list
+            | "owner" ":" expr ;
+
+auth_decl   = "auth" block( auth_setting ) ;
+method      = "get" | "post" | "put" | "patch" | "delete" ;
+```
+
+The full grammar including operator precedence and the theme block lives in `grammar/volaro.ebnf` in the reference repository.
+
+---
+
+## 17. Reference implementation in Rust
+
+Rust is the implementation language for three reasons: the compiler ships as a single static binary with no runtime dependency, the server backend compiles to Rust and reuses the same type representations, and the incremental query and CST libraries the project needs already exist there and are proven in `rust-analyzer`.
+
+### 17.1 Workspace layout
+
+```
+volaro/
+  crates/
+    vl-lexer      # source -> tokens, indentation handling
+    vl-syntax     # CST (rowan), parser, typed AST view
+    vl-hir        # desugared, name-resolved tree
+    vl-types      # type checker, inference, exhaustiveness
+    vl-vir        # typed IR, the input to every backend
+    vl-interp     # tree-walking interpreter over VIR
+    vl-emit-ts    # TypeScript emitter for views
+    vl-emit-rs    # Rust emitter for services
+    vl-auth       # auth code generation, pinned crypto parameters
+    vl-db         # model diffing, migration generation
+    vl-diag       # diagnostic types, rendering, JSON output
+    vl-fmt        # canonical formatter
+    vl-lsp        # language server
+    vl-cli        # the `vl` binary
+```
+
+### 17.2 Lexer
+
+Hand-written rather than generated. `logos` handles token patterns well but does not model an indent stack, and the indentation rules are the part most worth controlling directly.
+
+The lexer holds:
+
+- a byte cursor and a line-start flag
+- a `Vec<u32>` indent stack, initialized to `[0]`
+- a bracket depth counter
+
+At each line start it measures indent width, rejects tabs, and compares against the stack top. Greater width pushes and emits `Indent`. Lesser width pops repeatedly, emitting `Dedent` per pop, and errors if no stack entry matches. Blank lines and comment-only lines emit nothing. When bracket depth is above zero the whole procedure is skipped.
+
+Tokens carry a `TextRange` of byte offsets, never line and column pairs. Line numbers are computed once, at diagnostic rendering time, from a line-index table.
+
+```rust
+pub struct Token {
+    pub kind: SyntaxKind,
+    pub range: TextRange,
+}
+
+pub struct Lexer<'src> {
+    src: &'src str,
+    pos: TextSize,
+    indents: Vec<u32>,
+    bracket_depth: u32,
+    at_line_start: bool,
+    errors: Vec<LexError>,
+}
+```
+
+The lexer never fails hard. An unterminated string produces a token covering the rest of the line plus an error, so the parser keeps making progress and the editor keeps highlighting.
+
+### 17.3 Parser
+
+Recursive descent for statements and declarations, Pratt parsing for expressions. The parser writes into a `rowan` green tree builder, producing a lossless CST that preserves whitespace and comments. The formatter and language server read the CST; everything past name resolution reads the typed AST view layered on top.
+
+Error recovery synchronizes on three anchors: a `Dedent` to the enclosing block level, a statement-start keyword, and end of file. A parse error inside a view body recovers at the next sibling element, so one bad attribute does not lose the rest of the tree.
+
+Expression parsing uses a binding-power table matching the precedence in section 5.2:
+
+```rust
+fn binding_power(op: SyntaxKind) -> Option<(u8, u8)> {
+    Some(match op {
+        T![|>]        => (1, 2),
+        T![??]        => (4, 3),   // right associative
+        T![or]        => (5, 6),
+        T![and]       => (7, 8),
+        T![==] | T![!=] => (9, 9), // non-associative, checked after parse
+        T![<] | T![<=] | T![>] | T![>=] => (11, 11),
+        T![..] | T![..=] => (12, 12), // non-associative, section 5.2 level 5
+        T![+] | T![-] => (13, 14),
+        T![*] | T![/] | T![%] => (15, 16),
+        _ => return None,
+    })
+}
+```
+
+Equal binding powers on both sides mark non-associative operators; the parser detects a second occurrence at the same level and emits the chained-comparison diagnostic with its suggested rewrite.
+
+### 17.4 Name resolution and HIR
+
+`vl-hir` lowers the CST into an arena-allocated tree with every name resolved to a `DefId`. Desugaring happens here, so later stages see a smaller language:
+
+- `x |> f(a)` becomes `f(x, a)`
+- `a ?? b` becomes a match on the optional
+- `if` as expression becomes a match on the condition
+- string interpolation becomes a `concat` call over formatted parts
+- `derive` becomes a memoized function plus a dependency set computed from the free variables of its body
+- `load` becomes a state machine with four states and a cache key derived from the call arguments
+- an `auth role:x` guard becomes a `before` handler prepended to the route body
+
+Views, routes, and endpoints reduce to ordinary functions and records by the end of lowering. Everything domain-specific lives in the front end, which keeps the backends small.
+
+### 17.5 Type checking
+
+Local Hindley-Milner with no let-generalization across item boundaries, since item signatures are always annotated. Unification runs over a union-find of type variables. Row polymorphism is not needed, since records are nominal (§4.3); equality is structural but plays no part in unification.
+
+Three checks run alongside inference:
+
+1. **Exhaustiveness** over union patterns, using the usefulness algorithm from Maranget's work on ML pattern matching, adapted to handle guards conservatively (a guarded arm never counts toward coverage).
+2. **Fallibility**, verifying `?` appears only in fallible functions with a compatible error type, and that no `T!` value goes unused.
+3. **Effect coloring**, marking every function that reaches IO transitively. The result drives async code generation without appearing in signatures.
+
+### 17.6 VIR and backends
+
+VIR is a typed tree IR, not SSA. Application code is not compute-bound, and the optimizations worth doing (dead code, constant folding, request deduplication) are tree rewrites. Skipping SSA saves a large amount of implementation effort with little cost.
+
+Three consumers:
+
+- **`vl-interp`** walks VIR directly. It backs `vl run`, the REPL, and the test harness. Startup is under 50 ms on a mid-sized project, which makes the edit-test loop fast enough that the compiled backends are not needed during development.
+- **`vl-emit-ts`** emits TypeScript for views. Reactive state becomes signals, `load` becomes a request hook, and elements become framework component calls. The emitter targets a thin runtime library rather than a specific framework, so the framework is a swappable backend detail.
+- **`vl-emit-rs`** emits Rust for services. Routes become `axum` handlers, models become `sqlx` queries checked at build time, and `par` becomes `tokio::try_join!`. The generated crate is readable and committed to the build directory, which means a team can inspect what runs in production.
+
+Generated code carries source maps back to Volaro spans so a runtime stack trace names `.vl` files and lines.
+
+### 17.7 Crate dependencies
+
+| Crate | Use |
+|---|---|
+| `rowan` | lossless CST |
+| `la-arena` | HIR and VIR arenas |
+| `salsa` | incremental query framework for the LSP |
+| `rustc-hash` | fast hash maps |
+| `text-size` | byte offsets and ranges |
+| `ariadne` | terminal diagnostic rendering |
+| `serde` / `serde_json` | JSON diagnostics, schema import |
+| `tokio` | async runtime for generated services and the LSP |
+| `argon2` | password hashing, parameters pinned by `vl-auth` |
+| `insta` | snapshot tests for parser, formatter, and emitters |
+| `proptest` | round-trip property tests |
+
+The compiler itself has no `unsafe` blocks, enforced by `#![forbid(unsafe_code)]` at every crate root.
+
+### 17.8 Testing strategy
+
+- **Parser**: snapshot tests over a corpus of `.vl` files, plus a property test asserting that formatting is idempotent and that print-then-parse round-trips to an identical CST modulo whitespace.
+- **Type checker**: a `tests/ui` directory of files with expected diagnostics inline as comments, in the style of `rustc`'s UI tests.
+- **Backends**: differential testing. The same program runs on the interpreter and on each emitted backend, and the outputs must match.
+- **Auth**: an adversarial suite asserting that no reachable source program produces a cookie without `HttpOnly`, a password comparison that is not timing-safe, or a state-changing route without CSRF verification.
+
+---
+
+## 18. Diagnostics
+
+Errors are the interface between the compiler and whatever is writing the code. Two formats, one source.
+
+Human format:
+
+```
+error[E0412]: missing `key` on list
+   ┌─ src/views/Feed.vl:19:5
+   │
+19 │     list posts as p
+   │     ^^^^^^^^^^^^^^^ list needs a stable key expression
+   │
+   = fix: list posts as p key:p.id
+```
+
+Machine format, from `vl check --json`:
+
+```json
+{
+  "code": "E0412",
+  "severity": "error",
+  "message": "missing `key` on list",
+  "file": "src/views/Feed.vl",
+  "range": { "start": 412, "end": 427 },
+  "fix": {
+    "description": "add a key expression",
+    "edits": [{ "start": 427, "end": 427, "text": " key:p.id" }]
+  }
+}
+```
+
+Every diagnostic carries at most one suggested fix, and the fix is a byte-range edit rather than prose. A generator applies it without re-reading the file. Where a fix is ambiguous the compiler emits no fix rather than a guess, since a wrong automatic edit is worse than none.
+
+`vl explain E0412` prints the extended description with a correct and an incorrect example.
+
+---
+
+## 19. Tooling
+
+| Command | Behavior |
+|---|---|
+| `vl new NAME` | scaffold a project |
+| `vl check` | typecheck, no output artifacts; `--json` for machine format |
+| `vl fmt` | canonical formatting, no options, exits non-zero on change with `--check` |
+| `vl run` | interpret, watch, hot reload |
+| `vl build` | emit TypeScript and Rust, compile, bundle |
+| `vl test` | run `std.test` suites on the interpreter |
+| `vl map` | print the project surface summary |
+| `vl migrate` | diff models against the database, print plan, apply |
+| `vl explain CODE` | extended diagnostic description |
+| `vl lsp` | language server over stdio |
+
+The formatter has no configuration. Line width is 100. A single canonical form means generated and hand-written code are indistinguishable after formatting, and diffs never carry style noise.
+
+---
+
+## 20. Open questions
+
+These are unresolved and should be settled before the grammar freezes.
+
+1. **Mutation inside closures.** Capture-by-value keeps reasoning simple but makes some event-handler patterns awkward. The alternative is capture-by-reference for `state` bindings specifically, which is a special case in exchange for ergonomics.
+2. **Generics for user code.** The specification has generic types in the library (`list<T>`) but no way to declare one. Adding them costs syntax and inference complexity; omitting them forces duplication. A restricted form allowing type parameters on functions but not on records may be the right middle.
+3. **Streaming responses.** `load` covers request and response. Server-sent events and WebSocket subscriptions have no construct yet, and bolting them onto `load` versus adding a `subscribe` block is undecided.
+4. **The `distinct` boundary.** Newtypes prevent argument mix-ups but multiply conversion calls at the database and JSON edges. Automatic conversion at serialization boundaries would help and would also hide a real conversion.
+5. **Whether `derive` dependency inference is legible.** Automatic dependency tracking removes a common bug and also removes a visible declaration. If a reader cannot predict when a `derive` recomputes, the feature has traded one confusion for another.
+6. **Multi-tenancy in `auth`.** Roles are global. Organization-scoped roles are the common case in business software, and modeling them as a guard (`auth role:admin in:org`) versus leaving them to application code is open.
+7. **Data-scope authorization.** §11 makes auth *guards* a compiler concern, but the *public scope* of a record — a `Post` is visible only where `published: true` — is not expressible. `db.posts.get(id)` reads any row by id, so a route can leak a draft even with every guard in place, and the §15 hand-written reference did exactly that (a `TASK.md` requirement: "a missing post and an unpublished post look the same … do not reveal that a draft exists"). Candidates: a `scope published: true` clause on the `model`, or requiring a public read to name its scope. This is the gap between "secure by construction" covering *who can call* and covering *what they can see*, surfaced by a real information-disclosure bug — it should feed v0.3.
+8. **Disjunctive and composable authorization guards.** §11.2 can express one role set or one ownership predicate, but not a common policy such as “`admin` **or** the post's owner.” Feature 06 therefore had to fall back to `auth required` plus a hand-written handler condition. If that condition is omitted, the destructive route still compiles and deletes any matching row — the exact security-boilerplate failure goal 4 in §1.1 is meant to remove. Candidates include an explicit boolean guard form (`auth any(role:admin, owner:<expr>)`), a small `any`/`all` guard block, or a named reusable policy. Any design must define evaluation order, missing-resource behavior (including non-enumerating 403s), `session.user` typing, and how composed guards interact with CSRF and data scopes. Until resolved, hand-written authorization composition must be marked as a language gap rather than presented as idiomatic Volaro.
+9. ~~**List growth: concatenation, append, or spread.**~~ **Resolved
+   2026-09-05.** There was no way to combine two `list<T>` values or add one
+   element to an existing list — no operator (`+` on two lists lowered
+   straight to the host's binary `+`, which is not list concatenation in
+   every target), no `STD_FNS` entry, no spread syntax in the grammar.
+   Found implementing feature 10 (infinite scroll): the reactive `load`
+   re-fetches and replaces its bound value on every dependency change, so a
+   paginated feed had no expressible way to keep earlier pages when a later
+   one arrived — confirmed against emitted output, not just reasoned about.
+   Decided over a `+` overload (would make one symbol mean two things, and
+   `xs + x` vs `xs + ys` is genuinely ambiguous for a generating model —
+   §4.6 is deliberate about avoiding exactly this kind of implicit,
+   context-dependent meaning) and over spread syntax (new grammar for one
+   operation, and `...` means nothing else in Volaro today): **`std.list`
+   gains `concat(a, b)` and `append(xs, x)`**, ordinary functions that
+   compose with the pipeline (`xs |> append(x)`) like `map`/`filter`
+   already do, adding zero grammar. Resolving the primitive alone was not
+   sufficient — see the companion decision below — and feature 10's own
+   `Feed` view needed genuine compiler-bug fixes (`on mount` was
+   AST-complete and precheck-passed but silently unemitted; the spec's own
+   §6.2 expression-form `try`/`catch` had never been implemented) before it
+   could actually use it. Full account: `views/10-infinite-scroll/DOGFOOD.md`.
+
+   **Companion decision: `load` does not gain an accumulate mode.** The
+   alternative to a list primitive was extending `load` itself to keep
+   prior pages instead of replacing them. Rejected: `load`'s `pending`
+   region rendering *replaces the whole view body* while a fetch is in
+   flight — correct for one first fetch, wrong for a later page, where
+   already-loaded rows must stay visible with a loading indicator alongside
+   them, not disappear behind a full-screen spinner. Redesigning `load`'s
+   pending/error contract to support that was judged a bigger change than
+   this pass's scope. The idiom instead: explicit `state` for the
+   accumulator plus `on mount` (now real) and the feature's own event
+   handlers drive fetches directly, giving full control over what stays
+   visible — at the cost of losing `load`'s automatic request
+   dedup/cache/cancellation-on-unmount for any feature that needs to
+   accumulate, which is why this is recorded as a real trade-off, not a
+   free win.
+
+---
+
+## 21. Milestones
+
+| Milestone | Scope | Exit criterion |
+|---|---|---|
+| M0 | Lexer, parser, CST, formatter | Round-trip and idempotence property tests pass on a 5,000-line corpus |
+| M1 | HIR, type checker, interpreter | The worked example in section 15 runs, minus views |
+| M2 | Views, TypeScript emitter, token benchmark | 40-feature corpus implemented both ways, ratio measured and published |
+| M3 | `service`, `api`, Rust emitter | Worked example deploys and serves traffic |
+| M4 | `auth`, `vl-db`, migrations | Adversarial auth suite passes with zero reachable insecure programs |
+| M5 | LSP, incremental compilation, `vl map` | Sub-100 ms keystroke-to-diagnostic on a 6,000-line project |
+
+M0 through M2 are the point where the central claim becomes testable. The density half is now measured ahead of M2 at **4.01×** on a 7-feature corpus (§14.3), above the 3:1 floor that would have called the design into question. What remains untested is whether an agent *writes* it correctly and whether "secure by construction" survives contact with an implementation — neither of which a token count can answer.
+
+
+---
+
+## 22. Changelog
+
+### v0.2 — 2026-09-03
+
+Ten inconsistencies found by implementing a 7-feature corpus by hand in both Volaro and a mainstream stack, and by writing a validator (`vlcheck`) against the grammar. Every change below closes a gap that made a real program unwritable or ambiguous.
+
+**Blocking gaps — these made corpus features unwritable:**
+
+1. **§11.3 client surface was incomplete.** It defined four calls; a signup, a reset-confirm and a TOTP step need three more. Added `auth.sign_up`, `auth.confirm_reset` and `auth.verify_totp`, and gave all seven a documented return type and error union in a table. Without these, features that the spec's own §14 motivates could not be expressed.
+2. **Item-route client names were undefined.** §10 showed `get /posts` and `get /posts/:id` as siblings but only ever called the collection. Added the naming rule (last non-parameter segment; singularised when the route has path parameters; `as` to disambiguate; duplicate names are a compile error). This unblocks generating a client for any route with a path parameter.
+3. **No way to declare a service intentionally public.** A genuine public-read API always tripped the "more than half these routes are public" warning, training the reader to ignore it. Added `service X public` and per-route `auth none`, with `auth none` on a write route still warning.
+
+**Semantic corrections:**
+
+4. **`try`/`catch` fell through to the success path.** The §14.1 sign-in example showed an error message being set *and* the success redirect running. Specified that a handled error terminates the `try` statement; code that must run regardless is placed **before** the `try`, or uses `spawn` for fire-and-forget. The example in §14.1 was right; the semantics were wrong. *(Amended below: an earlier draft of this fix added a `resume` keyword, since removed.)*
+5. **Records were "structurally compared" (§4.3) and "nominal" (§17.5).** Both are true of different things: nominal typing, structural equality. Stated precisely, and noted that nominal typing is what makes `distinct` meaningful.
+6. **`err` meant three things.** Separated the type `Err`, the constructor `err(...)`, and the reserved word `err`, and specified that `Err` is never record-literal constructed.
+
+**Grammar corrections:**
+
+7. **The keyword list omitted words the spec itself uses as declaration heads** — `model`, `spawn`, `theme`, `list`. Split into a reserved set and a contextual set recognised by position, so a field named `state` or a function named `load` stays legal. (Reserved count settled at 29 in the v0.2 amendments below.)
+8. **§3.4 required components to be `[A-Z]`** while every example used `col`, `row`, `text`. Made the case distinction meaningful: lowercase is a `std.ui` primitive element, uppercase is a `view`.
+9. **§17.3's binding-power table omitted `..` and `..=`**, which §5.2 places at level 5. Added at (12, 12), non-associative.
+10. **§1 said "no configuration files" while §7 and §13 required `volaro.toml`.** Narrowed the claim: one config file holding only what cannot be derived from source.
+
+**Known follow-on:** the corpus adds an explicit `return` to every `catch` arm to work around finding 4. Those returns are now redundant. Removing them will shrink the Volaro side of the corpus and improve the measured ratio in §14.3, so the corpus should be simplified and re-measured rather than left as-is.
+
+### v0.2 amendments — 2026-09-05
+
+One blocking gap, found by tracing the default signup path through the reference implementation rather than by writing a feature against it.
+
+1. **§11.3 had no way to complete email verification — so `verify_email true`, the default, was a dead end.** `sign_up` issues a verification token and leaves the account unverified; `sign_in` refuses an unverified account with `unverified_email`. Nothing in the seven-call client surface redeemed that token, so the compiler-owned auth API had no verification-completion path; ordinary model writes could still change the flag without redeeming a token. A project built on default settings therefore compiled, ran, accepted signups, and could not complete verification through the auth API, with no diagnostic for this missing step. The reference implementation's own tests concealed it: they marked the seeded user verified with a direct `UPDATE`, so the path was never exercised end to end. Added **`auth.confirm_verify(token:)` → `Session!`** with the error union `invalid_token`, `expired_token`, bringing the client surface to eight calls; §11.1 gains a matching bullet giving verification tokens the same single-use, hashed-at-rest, never-logged discipline as reset tokens, with a 24-hour life. This is the same class of gap as v0.2 finding 1 above and is recorded the same way.
+
+   **A successful confirmation also signs the user in.** `confirm_verify` returns `Session!`, so it establishes a session and rotates the session id exactly as `confirm_reset` does — the verification link is the last step before the application, not a step before a login form. This is a deliberate semantic choice and is stated in §11.3 rather than left to be inferred from the return type.
+
+### v0.2 amendments — 2026-09-03
+
+Corrections made while catching `vlcheck` up to v0.2 and building the first outbound demo, before either encoded the rules.
+
+1. **§10 client naming is method-aware.** Finding 2 above keyed the generated name on the path alone, which made `get /x/:id` + `patch /x/:id` — ordinary CRUD — a name clash, and invalidated the §15 worked example. The name now depends on the HTTP method too: a collection `get` keeps the plural segment, every other collection verb and every item verb takes a `create_` / `update_` / `delete_` prefix on the singular, and an action segment (`…/:id/publish`) is used verbatim. The single-namespace clash rule stands; it just stops firing on well-formed REST.
+2. **`resume` removed.** Finding 4 above added a `resume` keyword to opt into `try` fall-through. Its one motivating call site (the corpus password-reset request form) is better written by putting the shared statement before the `try`, which leaves `resume` with no use — a second way to say one thing, and pure hallucination surface. §3.5 drops it: **29 reserved words**, not the 30 the list held or the "Thirty-one" the prose claimed. §6.2 drops the sentence.
+3. **`spawn` is legal in a view.** §12 and §8.5 now state that a `spawn` block may appear in a view body or event handler, and that — unlike `load` — it is not cancelled on unmount: it runs to completion and a failure only logs. This is the fire-and-forget form for view code, and the replacement for `resume` in the reset-request form.
+4. **§9 parameter routing is split by method body** (the 11th §9 inconsistency, found building the outbound weather demo). §9 said any parameter in neither the path nor `query` is a compile error, but its own examples — `post check(text str)` with `path "/check"`, `post create_post(body NewPost)` with `path "/posts"` — put `text` / `body` in neither. Resolved: the compile error applies to `get` / `delete` / `head` only; for `post` / `put` / `patch` the unrouted parameters are the request body (`body` verbatim, others as a JSON object).
+5. **§9 `timeout` has a default** (finding 12). It was optional with no stated value, so an omitted `timeout` meant "no timeout" — a call that hangs forever, silently. Now: `30s` when omitted, `timeout none` to opt out explicitly.
+6. **No module-level value binding** (surfaced by the feature-12 dogfood, which wrote `let tabs = […]` at file scope). §7 listed only declarations at module scope but never said `let` there was disallowed, and `vlcheck` rejected it with a bare `E-PARSE`. Settled as a **non-goal**: a module is declarations only; a file-scope constant is a zero-parameter `fn`, a `let` inside the one consumer, `volaro.toml` / `env` for config, or a `type` for named cases. Reversible — a restricted `let` (const-expression RHS) can be added later if a real need appears. §7 now states this.
+7. **Accessible compound primitives `dialog` and `tabs` / `tab`** (§8.8), from the feature 11/12 dogfood — a modal or tab set could be authored as valid Volaro but its keyboard, focus, portal and ARIA half was inexpressible, so the only expressible version was an inaccessible one. Resolved with **option A** of the v0.3 accessibility decision: two `std.ui` primitives that carry accessibility by construction. Option B (raw `role` / `aria-*` / key events) was rejected — it restores expressiveness by also making the broken version expressible again. The portal + `inert` + focus-save/restore runtime (`VL.overlay`) was built first and is decision-independent. Scope is deliberately two primitives behind two real features, not a component library; further widgets earn their place one real feature at a time.
+8. **Comparison predicates in `where`** (§13.1), from the feature 10 dogfood — the worst defect class this project has found. `where` was equality-only with no stated limitation, so `where(created_at: cursor)`, written to mean "before this timestamp", passed `vlcheck` clean and `vlbuild` built it — compiling silently to `created_at = ?`. A build that reports success and returns the wrong rows, unlike every prior failure mode (no output, or a crash). Resolved by adding seven named predicate constructors (`lt`, `lte`, `gt`, `gte`, `ne`, `between`, `any_of`) as `where` values, each lowering to exactly one parameterized SQL fragment; the emitter now hard-errors on a `where` value it does not recognize instead of binding it as an opaque parameter, closing the same silent-success class for any future or mistyped predicate name. `where` still composes only by AND across named columns; a query needing `or` or nesting is a `db.raw` case. `db.raw` itself remains unlowered (a real gap, tracked separately) — this amendment fixes the common case, not raw SQL.
+9. **List growth (§20.9) and two dead/unimplemented constructs found closing it**, from the feature 10 dogfood, fourth pass. `std.list` gains `concat(a, b)` / `append(xs, x)` — see §20.9 for why these and not a `+` overload or spread syntax. Closing the feature that motivated it also surfaced that `on mount` (§8.5) was AST-complete and `vlcheck`-clean but silently unemitted (a warning, not a build failure — dead code behind a passing check, the same shape as finding 8 above but one layer further from the network) and that the §6.2 expression-position `try`/`catch` (`let user = try load(id) catch not_found create_guest()`, shown in this very document) had never been implemented by the parser at all (`expected an expression, found 'try'`). Both fixed. A live-verified example clicking through a real running server now exists (`views/10-infinite-scroll/`); the `load` accumulate-mode alternative was considered and rejected — see §20.9's companion decision.
+10. **Accessible inputs `label` / `aria_label` / `help` / `error`** (§8.9), first slice of the accessibility-by-default milestone. `input` was a plain `std.ui` element: the only way to name one was an adjacent `text` (not associated) or a `placeholder:` (not a label). `vlcheck` and `vlbuild` both accepted a nameless field, so the expressible form of a form was the inaccessible one — the same gap §8.8 closed for `dialog` / `tabs`, resolved the same way (option A: the primitive carries accessibility; no raw `aria-*` surface). `input` now requires `label:` or `aria_label:`; `E-INPUT-NAME` is an error naming the fix, and `placeholder:`-only does not satisfy it. `help:` and `error:` are compiler-wired to the control's `aria-describedby`, and a non-empty `error:` sets `aria-invalid="true"`. Bounded deliberately: live error announcement (`aria-live`), image alt text, page titles and heading / landmark structure are the rest of the milestone, not this amendment. `corpus/views/08-validated-form` was rewritten onto the syntax — its adjacent-`text` labels were the motivating case — so measured source moved and density was re-run; see `corpus/G1-RESULTS.md`. **Hardened 2026-09-06** (two review follow-ups, one patch): the name form is now *exactly one* of `label:` / `aria_label:` (`E-INPUT-NAME-DUP` when both are given), a statically empty / whitespace name is `E-INPUT-NAME`, and an at-runtime-empty name raises `render.empty_input_name` rather than rendering nameless. The generated `for` / `id` / `aria-describedby` ids are allocated **per rendered field instance** (lowering moved to a `VL.field` runtime helper), so a repeated component or a keyed-list row gets its own links and every `<label>` activates its own control — verified in real Chromium including inside a `dialog` and across a list reorder.
+11. **Accessible images `alt` / `alt_todo`** (§8.10), second slice of the accessibility-by-default milestone. `img` was a plain `std.ui` element with `alt` a straight pass-through attribute — `img src:…` with no `alt` built and rendered, so the inaccessible image was the expressible default, the same gap §8.9 had for inputs. Resolved the same way (option A): `img` now declares its alternative through exactly one form of `alt:` — real text (`E-IMG-ALT` if absent or statically empty, `E-IMG-ALT-ONE` if two forms are given), `alt:decorative` for a presentational image (`alt=""`), or `alt:todo` / `alt_todo:"…"` for an unfinished description. The placeholder forms build with a navigable `alt` and **warn** (`W-IMG-ALT-TODO`); a new **`--release`** flag on `vlcheck` and `vlbuild` promotes them to `E-IMG-ALT-TODO` — the ship gate for unresolved markers. A meaningful `alt:` is lowered through `VL.reqAlt`, so a dynamic value (`alt:"{caption}"`) that resolves to empty raises `render.empty_alt` instead of silently degrading to `alt=""`. No measured corpus source uses `img`, so density is unchanged; only the spec / crib grew. Live error announcement (`aria-live`), page titles and heading / landmark structure remain the rest of the milestone.
+12. **Page title, headings, and landmarks `page` / `h1`–`h6` / `main` / `nav`** (§8.11), third slice of the accessibility-by-default milestone. A build's root view is the page; there is no client-side router. New module-level `page title:<expr>` — written into `<title>` when literal, assigned to `document.title` at boot, so each full navigation carries its own title. A build that renders a page without one is refused (`E-PAGE-TITLE`); an empty title is `E-PAGE-TITLE`; a title that goes empty at load raises `render.empty_page_title`; two `page` blocks are `E-PAGE-DUP`. `h1`–`h6` emit real heading elements with the level independent of `size:`; an intra-view level skip is `W-HEADING-SKIP` and a second `h1` is `W-HEADING-MULTI-H1` — warnings only, per-view, so a reusable component starting at `h2`/`h3` is not flagged. `main` / `nav` emit the landmarks; one `main` per page (`E-MAIN-DUP`), and sibling `nav` regions need distinct `aria_label:` (`E-NAV-NAME`). When a `main` renders, the compiler tags it focusable and injects a keyboard-operable, focus-visible “Skip to main content” link — the author writes nothing. The 12 corpus features each gained a one-line `page title:`, so measured source moved and density was re-run 3.05× → 3.00× (`corpus/G1-RESULTS.md`). These structural checks do not prove accessibility or replace screen-reader testing. Live `aria-live` announcements are the remaining slice.
+
+13. **Live status and error regions** (§8.12). Added text-only `status message` with E-STATUS-SHAPE, compiler-owned polite/atomic semantics, and runtime string-or-nil validation. Existing input error regions remain exposed while empty and update retained text nodes without focus movement or repeated unchanged-message mutations. Browser Part 10 proves DOM behavior, not audible screen-reader output; no measured corpus source changed.
+
+14. **Composed-page landmark review** (§8.11), the accessibility-milestone review before styled-app work. The §8.11 landmark checks were per-view; the runtime composes one document from a page-root view that renders and repeats other views. Added a composition pass (runs when a module declares a `page`, follows component instantiation within the module from the page root, treats `if` / `else` branches as mutually exclusive, does not evaluate conditions): a second `main` across composed views or a reused `main` is `E-MAIN-COMPOSED`; two `<nav>`s that share one name or are both unnamed across composed views are `E-NAV-NAME`; one static `id:` rendered by more than one element is `E-ID-DUP`. Runtime: the auto-injected skip link is removed when its `main` target leaves the document and re-resolves the target at activation time. Cross-file `use` composition is not yet followed. Automated structural checks still do not prove accessibility or replace screen-reader testing; that pass is recorded separately. No measured corpus source changed.
+
+15. **Tailwind-backed styling Slice 1** (§8.7). Replaced the abandoned flat
+theme / `space unit:` / `raw_style:` sketch with nested `theme` categories,
+static `recipe button|input|card` declarations, the `card` grouping primitive,
+literal additive `class:`, and named space-token layout attrs. The compiler
+generates an explicit candidate manifest, invokes pinned upstream Tailwind at
+build time, parses the output and refuses unknown utilities. Runtime CSS is in
+a lower cascade layer; generated utilities are later; recipe-vs-class and
+recipe-vs-inline property conflicts are errors, so class token order is never
+claimed as precedence. Both dark selectors and reduced-motion output are
+generated. This implementation and its browser checks do not complete or
+replace the pending full-screen-reader acceptance protocol.