ww/docs/spec.md

# The ww Language Specification

Version 0.1 (2026-06-21). **Status: normative-intent, in progress.**

ww is a systems language: *Hare semantics + CSP concurrency, no garbage
collector*, with a Rob-Pike / Plan-9 sensibility and Go-style explicit
`package`/`import`. This document is the language contract. Where the two
compiler stages disagree with this text, the text is wrong and is a bug
to be filed (CLAUDE.md rule 10 requires the stages to agree with each
other; this spec requires them to agree with *it*).

Two implementations track this spec and must stay byte-identical
(rule 10): the C bootstrap frontend `cmd/wcc` (the reference) and the ww
reimplementation `lib/ww/syntax`. The token table in §2 is kept
numerically identical between them on purpose.

This is not a tutorial. It is terse by design, modelled on the Go
language specification (golang.org/ref/spec): EBNF where a grammar is
worth pinning, prose for semantics, and a normative appendix (§12) that
consolidates every sanctioned divergence from Hare. The appendix is the
highest-value part of this document — it is the single normative home
for rules currently scattered across CLAUDE.md, `.ai/`, and project
memory.

Sections marked **(reserved)** describe surface that is tokenised but not
yet given meaning; they are written when the feature lands.

---

## 1. Notation

The grammar uses Extended Backus-Naur Form, following the Go spec's
conventions:

```
Production  = production_name "=" [ Expression ] "." .
Expression  = Term { "|" Term } .
Term        = Factor { Factor } .
Factor      = production_name | token | Group | Option | Repetition .
Group       = "(" Expression ")" .
Option      = "[" Expression "]" .
Repetition  = "{" Expression "}" .
```

`|` is alternation, `{}` is zero-or-more, `[]` is zero-or-one, `()` is
grouping. Terminal tokens are in `"quotes"` or are the named token
classes from §2 (`ident`, `int_lit`, …).

---

## 2. Lexical elements

### 2.1 Source representation

Source is UTF-8. One UTF-8-encoded byte order mark (U+FEFF, bytes
`EF BB BF`) is ignored when it is the first code point of a physical source
file. Its three encoded bytes still count in source positions, so a following
token on the first line begins at column 4. U+FEFF is invalid at
every other source position, including inside string and rune literals and
comments. Apart from that marker rule, the lexer operates on bytes and
non-ASCII bytes are legal only inside string and rune literals and comments.

Every malformed UTF-8 byte in an eligible selected physical source produces
one positioned `invalid UTF-8 encoding` error at its 1-based physical line and
raw-byte column. The byte is consumed and omitted from the lexer's logical
character stream before token recovery. A malformed multi-byte spelling is
therefore diagnosed once for each byte that decodes as U+FFFD with width one;
a correctly encoded U+FFFD is valid. Malformed bytes cannot split an
identifier, number or suffix, operator, escape, comment delimiter, package
keyword, or import spelling into different tokens. Filename and test-role
eligibility precede validation, so an excluded physical file contributes no
UTF-8 diagnostic. This rule is independent of the leading-BOM and raw-NUL
rules below and does not make source bytes package, import, graph, action,
artifact, publication, or persistence identity.

Each raw byte `00` (U+0000) is invalid at every physical source position,
including in comments and string or rune literal text. It produces one
positioned `invalid NUL character` error at that byte's source position and
is omitted from the lexer's logical character stream before token recovery.
It therefore cannot split an identifier, number, operator, escape, or comment
boundary into different tokens. This is a source-representation rule, before
package/import interpretation; it does not make U+0000 a package, import, or
artifact identity component. An escape spelling such as `"\\x00"` is not a
raw source byte and remains a legal literal value.

### 2.2 Comments

Line comments only, introduced by `//` and running to end of line. There
are no block comments (Hare lineage; `/* */` is not recognised).

Two comment forms are *driver directives*, not ordinary comments — they
carry module-bundle structure and lex to dedicated tokens:

- `//ww:module <dotted.path>` — set the mangling module path for the
  decls that follow (token `MODPATH`).
- `//ww:module-reset` — reset the current module to the empty string
  before a package-less bundled file (token `MODRESET`).

These exist for the build driver's source bundling and are not written
by hand in ordinary source.

### 2.3 Tokens

Tokens are identifiers, keywords, operators/punctuation, and literals.
Whitespace (space, tab, CR, LF) separates tokens and is otherwise
ignored. A semicolon `;` terminates declarations and statements and is
written explicitly (no automatic insertion).

### 2.4 Keywords

The following 30 identifiers are reserved and may not be used as ordinary
identifiers:

```
as       break    case     chan     const    continue
def      defer    else     enum     export   false
fn       for      if       is       import   let
match    nil      package  proc     return   static
struct   switch   true     type     void     yield
```

`chan` and `proc` are reserved for the concurrency surface (§11,
reserved). `package` is the package-clause keyword; `import` introduces
an import.

### 2.5 Operators and punctuation

```
Assignment:  =  +=  -=  *=  /=  %=  &=  |=  ^=  <<=  >>=
Arithmetic:  +  -  *  /  %
Bitwise:     &  |  ^  ~  <<  >>
Comparison:  ==  !=  <  <=  >  >=
Logical:     &&  ||  !
Grouping:    (  )  {  }  [  ]
Punctuation: ,  ;  :  .  ..  ...  @  ?
Arrows:      <-  ->  =>
```

`<-` (channel send/receive) and `->` are tokenised but reserved (§11).
`=>` separates a `match` arm pattern from its body. `?` and `!` are the
error operators (§9). `:` introduces a type ascription / cast (§8) and a
field/binding type. `..` is the range operator (`for` range form, §7);
`...` is the variadic / spread marker (§6.3). `@` introduces an
attribute (§5.7).

### 2.6 Identifiers

```
ident = letter { letter | digit } .
letter = "A"…"Z" | "a"…"z" | "_" .
digit  = "0"…"9" .
```

A lone `_` is the *discard* identifier: legal as a binding name to mean
"ignore this", never as a reference.

### 2.7 Literals

```
int_lit   = decimal | hex | octal | binary [ suffix ] .
float_lit = digits "." digits [ exponent ] [ suffix ] .
rune_lit  = "'" ( byte | escape ) "'" .
str_lit   = '"' { byte | escape } '"' .
bool_lit  = "true" | "false" .
nil_lit   = "nil" .
```

- `int_lit` is held as a `u64`. `nil` is the null pointer value (§3.6).
- A numeric literal may carry a *type suffix* naming its type directly:
  `42u8`, `0u64`, `1i64`, `3.0f32`. Suffixes are the fixed-width type
  names (`i8 i16 i32 i64 u8 u16 u32 u64 f32 f64`). Without a suffix a
  literal is an *untyped constant* (§3.5) whose type is inferred from
  context.
- Escapes in rune and string literals: `\\ \" \' \n \t \r \0` and
  `\xNN` (two hex digits). Rune literals additionally accept the
  Unicode escapes `\uHHHH` and `\UHHHHHHHH`, yielding a codepoint.

---

## 3. Types

A type describes the layout and operations of a value. Every type has a
`size` and an alignment, both queryable with `size(T)` (§8). No size is
ever written as a bare literal in size-computing code — it is routed
through the type table (CLAUDE.md rule 13).

### 3.1 Boolean and void

`bool` (1 byte; `true`/`false`). `void` (size 0) is the empty type, used
as a fn result and as the second arm of a nullable pointer (§3.6).

### 3.2 Numeric types

Fixed-width integers: `i8 i16 i32 i64` (signed), `u8 u16 u32 u64`
(unsigned). Floats: `f32 f64`.

Machine-word types (8 bytes on amd64): `int`, `uint`, `uintptr`, `size`.
`int` and `uint` are a full machine word — Go-style, **not** Hare's 32-bit
`int`. The limit constants (`INT_MIN`, `INT_MAX`, `UINT_MAX`) are
**derived** from `size(int)`, never hardcoded to a width (§12).

`rune` is a 32-bit Unicode codepoint (4 bytes).

### 3.3 String and slice

`str` and `[]T` (slice of `T`) are both **24-byte three-word headers**:
`{ ptr, len, cap }`. Their `.ptr`, `.len`, and `.cap` pseudo-fields are
readable (§8.4). A `str` is UTF-8 bytes; reinterpreting `[]u8` as `str`
is `strings.frombytes` (a pure cast — there is no validation; §12).

Array: `[N]T` is `N` elements inline (size `N * size(T)`). `[_]T`
infers `N` from the initialiser's element count.

### 3.4 Aggregate and named types

```
type S = struct { f0: T0, f1: T1, … };   // struct
type Name = T;                            // named type / alias
```

- `struct` — named fields laid out in declaration order with natural
  alignment padding. Duplicate field names are rejected.
- `tuple` — `(T0, T1, …)`. Each element occupies an **8-byte slot**
  (`size((u32, u32)) == 16`), diverging from Hare's packed tuples (§12).
- `enum` — `enum i32 { A = 0, B, … }` (a named integer type with named
  constants) or bare `enum { … }`.
- A named type / alias introduces a new spelling for an underlying type.

TODO(spec): structs carry an internal `packed` property (no padding);
surface its syntax (an `@packed` attribute? a `struct` modifier?) once
confirmed against `cmd/wcc`. Likewise pin the `static let` qualifier
spelling and whether `static` applies outside function bodies.

### 3.5 Untyped constants

A literal without a suffix has an *untyped* type (`untyped int`,
`untyped float`, `untyped str`, `untyped rune`, `untyped bool`,
`untyped nil`). An untyped constant takes a concrete type from its use
context (assignment target, operand of a typed operation, fn argument).
This is the inference that lets `let x: u8 = 5;` work without a suffix.

### 3.6 Pointers and nullability

`*T` is a pointer to `T`. **A plain `*T` is non-null**; dereferencing it
is unconditional and free. A *nullable* pointer is written as the tagged
union `(*T | void)`; `nil` inhabits it. This is a one-flag fold, zero
extra cost for the non-null case, and it is the only optionality
mechanism — there is no separate `nullable` qualifier keyword (§12).
ww has no runtime null-check net, so a non-null `*T` carries the
no-null obligation the way C does.

### 3.7 Tagged unions and the error tag

```
TaggedType = "(" Type { "|" Type } ")" .
```

A tagged union `(A | B | …)` holds one of its variants plus a runtime
tag. Variants are discriminated with `match` (§7) or tested with `is`
and narrowed with `as` (§8). A variant may carry the error mark `!T`,
which participates in the error model (§9): `(i64 | invalid | overflow)`
is a typical fallible result.

### 3.8 Function and channel types

`fn(P0, P1, …) R` is a function type. `chan T` is a channel of `T`
(**reserved**, §11). `never` is the bottom type of an expression that
does not return (e.g. a call to `abort`).

---

## 4. Packages and imports

```
SourceFile = PackageClause { ImportDecl } { TopDecl } .
PackageClause = "package" PackageName ";" .
PackageName   = ident .
ImportDecl    = "import" ( ImportPath | ImportName ImportPath ) ";" .
ImportName    = ident .
ImportPath    = ident { "." ident } .
```

- Every source file begins with a package clause. Within one semantic source
  action, eligible `.ww` files share one declared package name. Ordinary
  production and same-package test sources use `p`; external test sources may
  use the related `p_test`, and the actions remain separate even though one
  canonical directory owns their test product. The declared name need not equal
  the directory name or the final component of its canonical import identity.
- The discard identifier `_` is syntactically valid as `PackageName`, but it
  is never a valid declared package name. A complete source with
  `package _;` reaches checker initialization, which reports exactly
  `invalid package name _` at the underscore token and continues checking the
  retained file. The package-clause parser admits the discard token only in
  this grammar slot; no other identifier position is broadened. A malformed or
  missing package name remains a parser error, and any complete-file syntax
  error prevents this checker diagnostic.

  Loading may retain `_` transiently to compare declared source families,
  record imports, and construct the applicable action, but it is not canonical
  package, import, graph, action, symbol, `.wwi`, artifact, publication, or
  persistence identity. Direct sources retain `__root`; dotted directories
  and providers retain their dotted identities. Selected files with distinct
  declared names remain a loader/family conflict. In an all-blank action the
  checker emits one blank-name diagnostic per retained package marker in
  deterministic source order.

  Observable ordering is source eligibility and loader-visible header/family
  validation, recursive import loading, the `ww run` main-package check,
  eligible dependency producers, complete parent-source parsing, then the
  blank-name, reached imported-package, and later checker diagnostics. Thus
  missing or invalid imports may precede the parent check; a blank run root is
  not `main` and starts no producer; and a full-source syntax error suppresses
  the blank-name error. An
  ordinary blank source provider cannot publish an interface or archive for an
  importer. A supplied or caller-corrupted `.wwi` can nevertheless contain
  that spelling and is defensively validated when reached.

  Import interfaces are read, owner-checked, and syntax-parsed as separate
  lists before the primary source is parsed. Interface structural errors keep
  their existing precedence, but a primary syntax error returns before
  imported-package semantic checking and therefore suppresses every
  blank-provider import diagnostic. After successful primary syntax, compiler
  test mode first materializes its required `test` or collision-safe
  `__wwtest` support occurrence unless an equivalent primary occurrence
  exists. With no matching interface that occurrence retains the external
  support fallback; with a matching interface its provider name is validated,
  and the reserved spelling does not bypass the check.

  Each represented canonical interface package is classified as valid,
  missing, conflicting, or invalid, where invalid means one nonconflicting
  real declared name `_`. Imported-interface reachability is rooted only at
  canonical uses in the primary and compiler-required lists. A reached valid
  interface owner may contribute its imported uses transitively; an invalid,
  missing, conflicting, unreachable, or ownerless section may not. Before
  interface facts are bound or merged, every declaration and use whose owner
  is not both reached and valid is discarded. An unused invalid interface is
  therefore wholly inert, even when it embeds a valid-origin section that
  imports the invalid path: it emits no diagnostic, installs no scope or
  declaration, changes no output, and is byte-equivalent to supplying no such
  interface. If primary source separately reaches that valid origin, its
  retained edge may legitimately reach and diagnose the invalid provider.

  A retained use of an invalid provider is marked used. A nonblank use receives
  a fake empty-scope package binding under its explicit alias or, without one,
  the canonical path leaf; a blank use creates no visible binding. This
  recovery prevents qualified values, calls, and types from producing
  missing-member, unknown-type, export, or calling-nonfunction cascades.
  Ordinary lexical shadowing of a nonblank recovery alias still applies.

  Immediately after primary blank-name diagnostics, the first retained use of
  each invalid canonical path reports exactly
  `could not import PATH (invalid package name: "_")`; later uses of that path
  are deduplicated, distinct paths retain occurrence order, and independent
  checker errors continue. Default, explicit, and blank import forms all
  position this error at the path's first identifier rather than at the alias.
  Canonical path, source spelling, alias, declared provider name, owner marker,
  placeholder, edge, and binding remain separate facts. A physical `.wwi`
  path is observation metadata and a same-named `.ww` file remains an import
  decoy.

  Ordinary `ww build` still omits a valid visible literal `*_test.ww` after
  header loading, so `package _;` in that omitted role has no action or
  diagnostic. Under `ww test`, production plus a same-package blank test forms
  one augmented internal-test action; the test recompile substitutes for the
  separate production node and one compiler invocation diagnoses every
  retained blank marker. A test-only blank source has one test-package action.
  Mixed valid/blank production and test names retain family-mismatch
  precedence, and no failed blank product reaches generated main, link, or
  runtime.

  Normal blank-package failure publishes no assembly, interface, object,
  archive, executable, retained test, or new semantic generation. Existing
  request rollback removes owned stages and preserves prior public and
  committed bytes; a public build or test consuming a reached corrupted
  committed interface likewise publishes no replacement consumer generation,
  retained test, or downstream artifact. Exact valid-interface restoration
  follows ordinary reuse. Independent requests share no blank-name,
  reachability, deduplication, or fake-binding state. Cstage and WWstage have
  the same path-positioned diagnostic stream and artifact outcome. The private
  in-memory AST adds only path-position fields; AST enum/printing, `.wwi`
  schema, build workdir format 18, test workdir format 19, and semantic storage
  format 3 do not change. External driver interruption is unchanged; the fixed
  `.new` residue and later persistent request poisoning remain open.
- Each source file has one contiguous import section immediately after its
  package clause. Once a non-import top-level declaration begins, a later
  `import` is rejected as `imports must appear before other declarations`.
  Parsing continues for recovery: consecutive imports in that late section
  produce one ordering diagnostic, while another ordinary declaration followed
  by another import starts a separately diagnosed late section. Existing
  aggregate module/reset boundaries and constituent package clauses reset this
  parser state per source; they do not relax the rule within a source or become
  package/import identity.
  A filename excluded by the target-selection rule below reaches no parser and
  therefore cannot contribute an ordering diagnostic or import edge.
- Directory source eligibility uses Go 1.26.5 filename suffix semantics for
  WW's fixed `linux/amd64` target. In the basename stem before the first dot, a
  final `_test` token is ignored for platform matching. A final known OS or
  architecture token must match `linux` or `amd64`; a final known OS followed
  by a known architecture takes precedence and both must match. The known-name
  sets are Go 1.26.5's `syslist.KnownOS` and `syslist.KnownArch`. Unknown or
  misplaced suffixes are ordinary, and a platform word without a nonempty
  underscore prefix is ordinary (`linux.ww` and `plan9_test.ww` are selected;
  `x_windows.ww` and `x_plan9_test.ww` are not). Leading-dot/underscore entries
  are ignored. Eligible names are byte-sorted before source validation.
  Production excludes selected `*_test.ww`; test variants classify only those
  selected test files. An excluded file contributes no declarations, imports,
  filename collision, package edge, action, export, artifact, initialization,
  test, diagnostic, or persistent invalidation. After eligibility, each
  selected physical source is validated for malformed UTF-8 and raw NUL before
  package-clause or import interpretation, in the existing byte-sorted file
  order. After that source preflight, two distinct selected
  basenames in one canonical directory that are equal under Go 1.26.5 Unicode
  simple folding are rejected after the coordinator's required package-clause
  classification and production `@test` validation parses, but before the
  delegated graph-import scan or tools. An ordinary build compares production
  names only; one test product compares its production, same-package test, and
  external-test selections without merging their units.
- After existing filename, target, kind, and test-role eligibility, a selected
  source whose package/import header successfully declares the exact name
  `documentation` is omitted before semantic source membership and import
  scanning. The loader accepts the ordinary leading BOM, whitespace, comments,
  internal line directives, and package-clause trivia when recognizing this
  exact candidate. `documentation_test`, `documentationx`, and all other names
  remain ordinary sources.

  Candidate recognition is silent. A malformed package clause, malformed
  contiguous import, reached header NUL, or unterminated header-trivia comment
  retains its existing positioned load error before omission. After a valid
  exact package/import prefix, a non-`i` first raw byte establishes the body
  boundary and the remaining bytes are not parsed. A first raw `i` that does
  not form the exact `import` token is instead diagnosed at that byte as
  `expected top-level decl`; exact `import` followed by malformed import syntax
  retains the ordinary import-parser diagnostic. Thus syntax, types, late
  imports, imports missing only in the body, declarations, initializers,
  tests, and runtime behavior after a successful non-`i` boundary are not
  observed.

  An omitted documentation source creates no package member or family,
  source-file import occurrence, binding or graph edge, qualifier,
  initializer, declaration, symbol, `.wwi`, action, publication destination,
  or persistence identity. A mixed package is semantically identical to the
  same source set without that file. A doc-only dotted directory provider has
  no package sources and cannot satisfy an import. A same-named `.ww` file is
  still not an import provider under the directory-only import rule; when such
  a file is selected as a logical CLI root, it receives the established
  `__root` identity only if retained as ordinary. The rule applies equally to
  selected literal and logical roots, directory members, raw tests, recursive
  discovery, and dotted directory providers.

  Named-file documentation preflight applies only after symlink-following
  `stat` classifies the literal or resolved source as regular, including a
  symlink to a regular file. It retains one exact read buffer: documentation
  bytes are suppressed from that buffer, while ordinary bytes from the same
  preflight are reused by graph loading rather than reopened. FIFO and other
  nonregular named-source routes keep their prior behavior and are not touched
  by this preflight.

  Coordinator directory discovery records metadata only. Selected paths are
  canonicalized and deduplicated before source reads; each unique source is
  then classified exactly once. For an ordinary result, the same buffered bytes
  feed existing coordinator source validation. Direct-root failure and
  recursive pattern/group accounting are performed per request after
  classification, without rereading or reclassifying a source reached by more
  than one spelling or pattern. Independently, one delegated driver request
  enumerates each canonical directory once and lazily snapshots each
  role-eligible regular source once; that observation supplies classification,
  package/test attestation, import scanning, copied test actions, and unit
  emission across every variant in the request. A production-only request does
  not open excluded `*_test.ww` entries. Coordinator and delegated-driver
  observations remain separate process boundaries; concurrent rewriting between
  them gains no new atomic-snapshot guarantee.

  Test-role precedence remains route-specific. A visible literal named
  `_test.ww` passed to `ww build` validates its package/import header and then
  follows the test-only empty-selection rule below without documentation
  classification. A production directory build leaves `*_test.ww` unopened.
  Raw `ww test` and selected directory test variants do classify documentation
  sources. A logical request whose resolved provider merely has an `_test.ww`
  physical basename is not the literal named-build special case. Directory
  `ww test -S` without its required `-o` rejects as
  `ww test: -S needs -o`; with a valid `-o`, a directory rejects as
  `ww test: -S needs a single test file`. Both checks precede classification.

  A doc-only direct build or run root takes its route's existing
  `directory contains no WW package sources` result; recursive doc-only
  directories do not become packages, while mixed roots are exactly the
  source-absent control. No compiler, assembler, archiver, linker, generated
  test support/main, test child, initializer, or program runtime is attributable
  to the omitted source, and it creates no unit, interface, assembly, object,
  archive, executable, output, transaction, capture, or retained result.
  Changing only an ignored documentation body cannot invalidate or replace a
  committed semantic generation. Cold failure publishes nothing; warm
  no-source or header failure preserves prior public and semantic bytes.
  Classification state is ephemeral: a process-local named-root preload is
  cleared at the build boundary, and directory observations die with the
  request graph. No state is shared or persisted across requests, and no lock,
  schema, cache, or serialized identity is added. Build workdir format remains
  18, test workdir format remains 19, and semantic storage format remains 3.
- A single existing raw `.ww` operand is also subject to the unconditional
  leading-name rule: if its final requested basename begins `.` or `_`, it is
  ignored before the source is opened. Named raw sources otherwise retain their
  existing all-files behavior, so a visible wrong-platform suffix remains
  eligible. Only the requested basename participates: a hidden parent does not
  hide visible `main.ww`, a hidden symlink spelling stays hidden for any
  existing non-directory target, and a visible symlink spelling stays eligible.
  The prefix-excluded operand creates no package, declaration, import
  binding/edge, action, artifact, initialization, test, publication, or
  persistent state. `ww build` reports the existing `directory contains no WW
  package sources` condition; an explicit running raw `ww test` also emits its
  command-owned `FAIL`, while `-c` and `-S` do not.
- A visible single raw operand passed to `ww build` whose requested final
  basename ends exactly `_test.ww` is test-only after its package clause and
  contiguous initial import section have been read. Prefix exclusion remains
  first, so a bare `_test.ww` is never opened. Header read, package-clause, and
  initial-import syntax errors retain their ordinary precedence; after a valid
  header the sole root is omitted. Its dotted imports are not resolved, and a
  late import, body parse/type error, or runtime behavior is not observed. The
  first ordinary body token is not lexed, so an immediately following malformed
  UTF-8 byte or non-leading BOM is outside the header. A raw NUL reached while
  locating that token and an unterminated comment in header trivia remain load
  errors. Go's byte reader probes a following `i` as a possible `import`; the
  corresponding WW boundary is the exact lexical `import` token, so an ordinary
  WW identifier merely beginning with `i` is body syntax. This named-source
  rule retains all-files platform behavior: a
  visible `x_windows_test.ww` is still test-only. It classifies the requested
  basename of a visible symlink, not its target name; a symlink whose target is
  a directory remains a directory request.
- Omission creates no canonical package, command-line package node, import
  binding or edge, graph/action, symbol, initializer, executable, archive,
  interface, publication, transaction, default `.sepwork`, or work-state
  mutation. It does not alter `ww test`, `ww test -c`, `ww test -S`, logical
  operands, directory/recursive selection, multiple named-source support,
  imports, or `ww run`. Physical directory and symlink-target data remain
  observation metadata, never package, import, graph, action, artifact,
  symbol, `.wwi`, publication, or persistence identity. Build workdir format
  remains 18, test workdir format remains 19, and semantic storage format
  remains 3.
- A local literal passed to `ww build` whose requested final basename ends
  `.ww` remains a directory request when ordinary `stat` reports a directory,
  including when the spelling is a symlink or ends `_test.ww`. The directory
  target therefore bypasses raw named-source prefix and test-source
  classification and enters ordinary directory enumeration. Actual eligible
  production entries, package declarations, imports, graph actions, producers,
  output policy, publication, persistence, invalidation, rollback, and cleanup
  are exactly those of the existing directory package route. The requested
  spelling and physical target are loader/presentation metadata only and create
  no new package, dotted-import, graph, action, symbol, artifact, `.wwi`,
  publication, or persistence identity. Raw `ww test`, `ww test -c`, and
  `ww test -S` already use the same directory classification and are unchanged.
  `ww run` retains its separate named-operand front door, with its
  `.ww`-spelled directory rule specified next. Multiple operands, recursive
  and logical requests, regular and non-regular source targets, and dangling
  symlinks are not changed. Build workdir format remains 18, test workdir
  format remains 19, and semantic storage format remains 3.
- For `ww run`, an existing selected target whose exact requested spelling
  ends `.ww` is a named-source request when symlink-following `stat` reports a
  directory. The command rejects it before shared resolution, directory
  enumeration, source/import loading, graph/action construction, private run
  scratch, producers, or runtime. A requested suffix `_test.ww` has the earlier
  exact diagnostic
  `ww: cannot run *_test.ww files (OPERAND)\n`; every other such directory has
  exact diagnostic `OPERAND is a directory, should be a WW file\n`. Both forms
  return status 1 with empty stdout and reproduce the requested operand bytes
  unchanged. The rule follows a terminal symlink, includes `.hidden.ww` and
  `_hidden.ww` directory spellings, and precedes any malformed package or
  missing import inside the directory. A trailing separator does not end
  `.ww`; ordinary non-`.ww` directories, dotted logical requests, regular and
  missing operands, multiple named operands, and non-directory non-regular
  targets retain their established routes. The rejected spelling and followed
  target are diagnostic metadata only and create no package/import identity,
  graph/action, symbol, artifact, `.wwi`, publication, transaction,
  persistence, process, or filesystem owner. Build and all test forms retain
  their distinct stat-first directory behavior. Build workdir format remains
  18, test workdir format remains 19, and semantic storage format remains 3.
- A public operand is eligible for direct named-source adoption only when its
  exact requested spelling ends `.ww` and that command's existing file-kind
  rule admits it. An existing non-directory object with another suffix is not
  source: its bytes, package clause, imports, syntax, test declarations,
  runtime behavior, mode, and timestamp are not read as source, and ordinary
  dotted resolution continues exactly as though the colliding object were
  absent. Thus request `foo.bar` may resolve `foo/bar.ww` or `foo/bar/` even
  while a physical non-directory `foo.bar` exists. A wrong-suffix symlink to a
  non-directory is the same ignored collision; a symlink to a directory remains
  an ordinary stat-first directory request. A visible `.ww` symlink to a
  regular source remains eligible, and the established stage-specific handling
  of visible `.ww` special files is not broadened by this rule.

  A resolved logical single file retains the established `__root` command-line
  package/action/artifact identity. A resolved logical directory retains its
  dotted package, import, graph, action, symbol, `.wwi`, initializer, artifact,
  publication, and persistence identity. The ignored physical pathname/object
  creates no membership, binding, edge, action, key, or alternate identity.
  Build and run use only the logical provider's production/import/initializer
  closure and runtime. Raw running test, its historical second-positional
  test-name filter, `test -c`, and `test -S` use only the provider's test
  package, descriptors, support closure, binary, and assembly.

  When no provider exists, collision-present behavior is byte-for-byte the
  existing collision-absent behavior. An ordinary single target retains its
  direct build/run/test cannot-find result and creates no producer action. A
  second positional retains the established package-coordinator route,
  diagnostics, status, selection lifecycle, and cleanup; this source gate does
  not reinterpret that positional form. Mutation invariance covers only absent
  and stat-successful non-directory collision states. A transition to a
  directory leaves this rule and follows ordinary directory routing, with no
  new atomic-snapshot guarantee for concurrent kind changes.

  Provider compilation failure preserves the prior public and semantic
  generation. A retained running-test runtime failure occurs after the complete
  logical build generation commits: it preserves prior retained public bytes by
  skipping deferred installation, while that semantic generation remains
  committed and reusable. Restoring prior source bytes requires a later
  successful rebuild and commit, not runtime-failure rollback. Controlled-
  failure cleanup otherwise remains unchanged. External signal
  interruption after action start is unchanged, including the verified-open
  fixed `.new` residue and later persistent-request poisoning. Multiple named
  sources, remaining suffix-first run behavior, finite `.ww` FIFOs, test
  process topology, and `-run` regular expressions are not completed here.
  Build workdir format remains 18, test workdir format remains 19, and semantic
  storage format remains 3.
- `import acme.codec;` loads the canonical package `acme.codec`. If that
  package declares `package wire;`, the importing file sees its exported names
  as `wire.Name`; `codec.Name` is not an additional binding. An explicit alias
  replaces only that visible qualifier: `import stable acme.codec;` exposes
  `stable.Name`, not `wire.Name` or `codec.Name`. Each effective default or
  explicit named binding is a file-local package-name object usable only as
  the left qualifier of a selector. A bare occurrence in a value context is
  rejected as `use of package BINDING not in selector`; a bare occurrence in
  a type context is rejected as `BINDING (package name) is not a type`. Such a
  rejected bare occurrence does not count as use of the import for
  unused-import accounting. A legal selector does count as use, but does not
  excuse any separate bare occurrence. Both kinds of named binding are scoped
  to that source file. A sibling file must declare its own import; without one,
  its otherwise equal spelling follows ordinary undefined-name or unknown-type
  lookup rather than package-name diagnostics. Builtin spelling does not alter
  the object: an import bound as `len`, `size`, `align`, or another builtin name
  remains a selector-only package-name object.
  An ordinary lexical binding may shadow that file-local package-name object.
  Lookup at each occurrence chooses the nearest enclosing binding: a selector
  before a later local declaration can use and count the import, while the
  same spelling after that declaration denotes the local. Parameters bind for
  their whole function body; local `let` bindings begin after their declared
  type and initializer have been checked; tuple bindings begin after their
  right-hand side and declared types; and loop, range, and match-arm bindings
  begin only after their respective initializer/iterable or pattern/type has
  been checked. Nested blocks and loop scopes restore the imported package-name
  object on exit. These declaration-point rules apply equally to default,
  explicit, and builtin-spelled qualifiers. A selector counts as an import use
  only when its receiver resolves to that package-name object; a selector on a
  closer local, including a field or pseudo-field selector, does not.
  Go has no range-loop `else` clause; that WW-only extension is not assigned a
  Go-derived scope rule by this paragraph.
  Neither form exposes an imported declaration as a bare `Name`; ordinary
  unqualified lookup remains limited to lexical, builtin, and same-package
  declarations. A blank import creates no package-name object, an effective
  `init` import is rejected before installing one, and a missing target fails
  during import resolution, so none of those cases acquires the bare-package
  diagnostics or satisfies a named import's unused accounting.
- An import whose effective file-local qualifier is `init` is invalid. This
  includes both `import init acme.codec;` and an unaliased import whose target
  declares `package init;`. Each resolved occurrence is rejected at its first
  import-spec token (the explicit alias when present, otherwise the first path
  token) as `cannot import package as init - init must be a func`. The rejected
  qualifier is never installed and does not participate in unused-import,
  duplicate-binding, or declaration/import-collision recovery; consequently a
  later `init.Name` independently reports an undefined `init`. Repeated invalid
  occurrences each report the core error. Import resolution retains
  precedence, so a missing target fails as missing without an additional
  effective-`init` error. A resolved rejected occurrence remains source and
  graph provenance for its exact dotted target: only its file-local qualifier
  binding is absent. Canonical package, import, graph, action, artifact,
  symbol, `.wwi`, publication, and persistence identity never derives from the
  rejected qualifier or from the target's declared name.
- `import _ acme.codec;` is a blank side-effect import. The lone `_` creates no
  qualifier, exposes no bare declaration, and is never diagnosed as unused.
  It is nevertheless a real import occurrence: resolution and all missing,
  self-import, cycle, `internal`, vendor, and imported-command checks use the
  dotted path, and the dependency participates in executable and test package
  initialization. Repeated blank occurrences and blank plus default/explicit
  named occurrences of one path are valid; every named occurrence remains
  independently subject to duplicate-binding and unused checks.
  Each semantic action's package dependency graph is the sorted, deduplicated
  union of real imports in that action's eligible source set. Occurrences retain
  their owning file and position, but equal canonical targets create one graph
  edge. Test-only occurrences never enter ordinary production. Self-import is
  rejected, except that toolchain-owned external-test self wiring is rebound to
  the effective augmented package action after ordinary per-site validation.
- Canonical import identity is exact and case-sensitive. After contextual local
  or vendor expansion, two distinct effective identities that are equal under
  Go 1.26.5 simple folding are a request-wide structural error. Folding is only
  a temporary collision key: it never changes lookup, action identity, `.wwi`
  ownership, symbols, artifacts, storage, or diagnostics. Repeated occurrences
  of the same exact identity remain valid and deduplicate normally.
- An executable package is one declared `package main` and containing a
  `fn main`; path and directory spelling do not classify commands. Within a
  package declared `main`, a package-scope declaration named `main` must be a
  function: `let`, `const`, `def`, and `type` forms reject as
  `cannot declare main - must be func` and do not enter package scope. The
  restriction depends only on the declared package name. A package with any
  other declared name may use or export `main` regardless of its dotted import
  path, path leaf, physical directory, or selection role. WW retains its
  established program-entry ABI, so a function `main` may carry WW's supported
  arguments and result; this rule does not adopt Go's source signature. An
  ordinary import of a package declared `main` is rejected, except for the
  toolchain's colocated external-test wiring.
- For `ww build`, the output-option name is exactly `o`. The accepted forms are
  `-o VALUE`, `--o VALUE`, `-o=VALUE`, and `--o=VALUE`. An equals form splits
  at its first `=` and preserves every later byte, including further `=`
  characters; an empty value is valid. Repetition is last-value-wins, and a
  final empty value means that there is no effective explicit output, so the
  ordinary default-output or no-public-output rule applies. A concatenated
  spelling such as `-oVALUE` or `--oVALUE` is an unknown flag, not an output
  option. Build option parsing stops at the first package or source operand;
  later flag-like arguments remain operands and are not reparsed as `-o`.
  These spelling and placement rules select only caller-visible output
  disposition and never supply package, import, graph, action, symbol,
  artifact, `.wwi`, or persistence identity.
  A nonempty effective `-o` names an output directory when ordinary
  `stat` reports an existing directory (following symlinks) or its spelling
  ends in `/`. This classification is independent of whether one or many
  package roots were requested. Each selected command is published beneath
  that directory using the final component of its requested contextual import
  name, with the selected local directory leaf as the fallback when no such
  identity exists. Independently selected non-main roots load but do not enter
  the action list; non-main command dependencies retain ordinary actions, and
  a selection containing no command rejects before tools or output creation.
  A raw command-line `.ww` source uses its source basename without `.ww`, and
  a raw non-main source is the same no-command rejection. An existing
  directory whose requested basename ends `.ww` is not such a raw source: it
  retains directory-package output naming. With no `-o`, its requested leaf
  is used verbatim (for example, `directory_test.ww`); with an existing
  output-directory `-o`, publication instead uses the canonical selected
  target leaf (for example, `directory-target`).
  Missing trailing-slash hierarchies are created transactionally from `0777`,
  filtered by the caller's umask.
  Loading and package/import diagnostics precede no-main, derived-path,
  duplicate-destination, implicit-default, and other output preflight; all of
  those checks precede creation. Producer failure and coordinator-owned
  interruption preserve existing directory contents and remove only
  request-created prefixes and stages. Direct external `SIGTERM` of a build
  driver is a verified-open exception: both stages preserve public and
  committed work bytes, but leave the directly spawned compiler alive and
  exactly three fixed-name `.new` staging files; the existing `.unit.new`
  makes a later persistent-work request reject. A non-directory output retains
  the single-product file/archive rule.
  If a lone
  command's synthesized default basename already names a directory, loading
  and graph validation complete and the build rejects before tools without
  changing that directory; a non-main package synthesizes no default public
  output. With no path operand, the current directory is selected as if `.` had
  been supplied. For a lone literal current-directory command and no explicit
  `-o`, `.`, `./`, and equivalent single-dot-component spellings derive the
  default executable name from the canonical selected directory's final
  component; cold adjacent scratch uses that same leaf plus `.sepwork`. The dot
  spelling itself is never an output name. A current-directory non-main package
  uses the corrected scratch presentation but still links and publishes
  nothing. This physical leaf is fallback presentation metadata only: it never
  displaces a requested contextual dotted identity or becomes package, import,
  graph, action, artifact, symbol, `.wwi`, or persistence identity.
  Output paths and directory metadata never become package, import, graph, action,
  symbol, artifact, `.wwi`, or persistence identity.

  A valid omitted single raw `*_test.ww` build has an empty selection. With no
  effective `-o`, including an assembly-only request, and with exact
  `-o /dev/null`, it succeeds silently. A non-directory effective output fails
  with `ww: no packages to build`; an output-directory effective output fails
  with `ww: no main packages to build`. These empty-selection outcomes occur
  only after the raw test source's header has loaded successfully, create no
  output path or parent, and preserve every pre-existing output and work-state
  byte unchanged.

  Every caller-visible build installation checks its destination after all
  applicable compile, assemble, archive, and link producers finish. Ordinary
  `stat` follows symlinks. An existing directory rejects as
  `ww: build output "PATH" already exists and is a directory`; an existing
  nonempty regular file rejects as `... is not an object file` unless its
  leading bytes identify a Go 1.26.5 object/output form. The recognized table
  is archive, ELF, Mach-O, PE, Plan 9, WASM, and XCOFF magic; WW additionally
  recognizes its compiler-owned `//ww:module ` interface prefix. An absent
  path, an empty regular reservation, or a non-directory non-regular path may
  be replaced. A published non-main archive and its `.wwi` sidecar are checked
  as one WW request transaction, so arbitrary caller text in either
  destination preserves both old outputs and the committed persistent
  generation. This safety check is output disposition only: it does not enter
  package/import loading, graph or action identity, artifact bytes, or
  invalidation.
  Assembly-only `-S` retains the directory form's command-action selection and
  no-main rejection, but it reaches no install action: destination length,
  duplicate publication names, implicit destination collision, and output
  parent creation are therefore inapplicable.
- A newly published `ww build` command is created with permission `0777`
  filtered by the invoking process's umask. A newly published non-command
  archive, and the adjacent WW interface required to consume it, use `0666`
  filtered by that same umask. These inode permissions are output metadata:
  they do not enter canonical package or action identity, artifact bytes,
  import binding, symbols, `.wwi` contents, or persistent invalidation. A warm
  build therefore reuses unchanged semantic actions while refreshing the
  caller-visible output with the current invocation's mode. Assembly-only
  builds publish no executable or archive.
- On the Unix target, exact `-o /dev/null` is a build-output discard request,
  not an ordinary output filename. Package loading, import validation, graph
  construction, compilation, assembly, archiving, command linking, failure,
  and persistent invalidation proceed normally; only installation of a
  caller-visible command, archive, interface, default basename, or adjacent
  scratch tree is omitted. One such request may select any number of command
  and non-command packages, and an empty recursive match is successful after
  its normal warning. `-S` likewise needs no caller workdir merely to retain
  discarded assembly. Raw-file and directory roots use the same rule. A
  non-exact spelling is an ordinary output and keeps all established fan-out,
  rejection, permission, scratch, and publication behavior. Output discard is
  request metadata; it does not change package, import, graph, action,
  artifact, symbol, `.wwi`, or persistence identity.
- Only names marked `export` (§5) are visible across module boundaries.

Import paths remain unquoted and dotted. Grouped imports, quoted import paths,
and dot imports are not implemented. `_` is reserved here for the blank form;
it is not an ordinary alias.

---

## 5. Declarations

```
TopDecl = [ "export" ] ( FnDecl | TypeDecl | LetDecl | ConstDecl
                       | DefDecl ) .
```

### 5.1 Functions

```
FnDecl = "fn" ident "(" [ Params ] ")" Result "=" Block .
       | "fn" ident "(" [ Params ] ")" Result ";" .   // bodiless: extern/FFI
Params = Param { "," Param } .
Param  = ident ":" Type | ident ":" Type "..." | "..." .
Result = Type | "void" .
```

The `=` between signature and body is required. A bodiless fn (`;`
terminator) declares an external symbol (C FFI); the bare `...` C-style
variadic is legal only on a bodiless declaration (§6.3).

At package scope, exactly `fn init() void = Block;` declares a special package
initializer. It must have a body, no parameters, no result, no `export`, and no
attribute. Multiple init declarations are permitted and retain owner-file and
source order. `init` is not inserted into ordinary package scope: it cannot be
called as `init()`, selected as `pkg.init`, exported, or used by another kind
of declaration. Package-variable initialization completes before these
functions run.

In a package whose declared name is `main`, only a function declaration may
claim the package-scope name `main`. A rejected non-function declaration is not
installed and cannot satisfy the executable entry. This is independent of
canonical import identity and physical location. The accepted function shape
continues to use WW's entry ABI, including its supported argument and result
forms.

### 5.2 `let`

```
LetDecl = "let" ident ":" Type [ "=" Expr ] ";" .
```

A mutable binding. Without an initialiser, package-level storage is
zero-backed; an uninitialized function-local binding retains the existing
uninitialized-local rule.
A `static` qualifier (`static let …`) gives function-local storage
static lifetime.

For a package-level `let` with an initializer, values representable by the
static-data emitter are installed statically. Every other otherwise valid
initializer is evaluated exactly once at runtime. Checked references through
package functions contribute variable-dependency edges; dependencies precede
dependents, and source declaration order breaks ready ties. Initialization
cycles are errors. Runtime package lets execute after imported package tasks and
before the package's init functions. `const` and `def` are not broadened by
this runtime path.

### 5.3 `const`

`const` introduces an immutable storage binding of the same declaration shape
as `let`; assignment to it is rejected. At package scope its initializer stays
within the existing static-data forms. A `const` is not entered into the
runtime package-variable schedule described above; use mutable `let` when an
otherwise valid initializer requires runtime evaluation.

### 5.4 `def`

```
DefDecl = "def" ident ":" Type "=" ConstExpr ";" .
```

A compile-time constant definition, typically at module level
(`def AF_INET: i32 = 2;`). Hare's `def`.

### 5.5 `type`

```
TypeDecl = "type" ident "=" Type ";" .
```

### 5.6 Visibility

`export` on a top-level declaration makes the name visible to importing
modules. Unmarked names are module-private.

### 5.7 Attributes

`@name` prefixes a declaration with an attribute. The defined attribute
is `@test`: it marks a function as a test (§10).

---

## 6. Functions and calls

### 6.1 Blocks and results

A function body is a `Block` (§7). The body's value is its result; an
explicit `return Expr;` returns early.

### 6.2 Calls

```
Call = Expr "(" [ Args ] ")" .
Args = Arg { "," Arg } [ "..." ] .
```

Arguments are passed by value (a `str`/`[]T`/`struct` copy is a shallow
header/field copy). Aggregates larger than a register use the
aggregate/`sret` ABI.

### 6.3 Variadic

Two distinct variadic forms:

- **Hare-style** `args: T...` — the callee receives a `[]T`. A call
  either gathers loose arguments (`fmt.println(1, "x")`) or forwards an
  existing slice with the spread `xs...`.
- **C-style** bare `...` — only on a bodiless (extern) declaration, for
  calling C variadic functions across the FFI. `f32` arguments in the
  variadic tail are promoted to `f64` per the C ABI.

---

## 7. Statements

```
Stmt = Block | LetDecl | ConstDecl | Assign | If | For | Switch
     | Match | Return | Break | Continue | Defer | Yield | ExprStmt .
Block = "{" { Stmt } "}" .
```

### 7.1 Assignment

```
Assign = Expr AssignOp Expr ";" .
AssignOp = "=" | "+=" | "-=" | "*=" | "/=" | "%="
         | "&=" | "|=" | "^=" | "<<=" | ">>=" .
```

The compound forms apply to scalar, indexed, and pointer-field targets.

### 7.2 `if`

```
If = "if" "(" Expr ")" Block [ "else" ( If | Block ) ] .
```

### 7.3 `for`

```
For = "for" "(" Expr ")" Block                          // condition
    | "for" "(" LetDecl Expr ";" Expr ")" Block          // 3-clause
    | "for" "(" "let" ident ".." Expr ")" Block .         // range
```

The 3-clause form is `for (let i: size = 0; i < n; i += 1) { … }`. The
range form iterates the elements of a slice or array
(`for (let x .. xs) { … }`). `break` and `continue` apply to the nearest
enclosing loop; `continue` runs the post-clause / advances the range.

TODO(spec): does the range form bind the *element* or an index, and is
the bound name a copy or a view? Confirm against the checker's
`N_FORRANGE` lowering; the continue-post behaviour was a fixed miscompile
(project memory #138), so the desugaring is worth stating precisely.

### 7.4 `switch`

```
Switch  = "switch" "(" Expr ")" "{" { SwCase } "}" .
SwCase  = "case" ExprList ":" { Stmt } | "case" ":" { Stmt } .
```

Value-matching on a scalar. A `case` may list comma-separated values;
`case:` is the default arm. Arms do not fall through.

### 7.5 `match`

```
Match    = "match" "(" Expr ")" "{" { MatchArm } "}" .
MatchArm = "case" [ "let" ident ":" ] Type "=>" ArmBody
         | "case" "=>" ArmBody .
ArmBody  = Stmt | Block .
```

Discriminates a tagged union (§3.7). `case let v: T =>` binds the
narrowed value to `v`; `case T =>` matches without binding; `case =>` is
the default. A `match` used as an expression produces a value via `yield`
(§7.7) from each arm.

### 7.6 `return`, `break`, `continue`, `defer`

`return [Expr];` `break;` `continue;`. `defer Stmt;` schedules a
statement to run when the enclosing block exits.

### 7.7 `yield`

`yield Expr;` produces the value of an enclosing block- or match-
expression.

---

## 8. Expressions

### 8.1 Operands

Identifiers, qualified names (`mod.name`), literals (§2.7), struct/array/
tuple literals (§8.5), and parenthesised expressions.

### 8.2 Operators and precedence

From loosest to tightest binding:

```
||
&&
==  !=  <  <=  >  >=
|   ^
&
<<  >>
+   -
*   /   %
unary:  -  !  ~  &(addr-of)  *(deref)
postfix: call()  index[]  slice[:]  field.  ?  !
```

`&e` takes the address of an addressable operand; `*p` dereferences.

TODO(spec): the precedence ladder is transcribed from the parser's
`bprec` (`parse.ww`); verify each tier against `cmd/wcc/parse.c` and
state associativity per tier. ww has no generics — no type parameters
anywhere in the grammar; call this out explicitly once confirmed.

### 8.3 Casts, `as`, `is`

```
Cast = Expr ":" Type .          // type ascription / conversion
As   = Expr "as" Type .         // tagged-union narrowing
Is   = Expr "is" Type .         // tagged-union variant test (bool)
```

`expr: T` converts/ascribes (`len(xs): size`, `t.line: i64`). An integer
cast does not silently truncate beyond the target width. `e as T`
narrows a tagged union to variant `T`; `e is T` tests membership.

### 8.4 Index, slice, field, pseudo-fields

`a[i]` indexes an array/slice/str (index operand must be an integer).
`a[lo:hi]` produces a sub-slice. `e.f` selects a struct field or a
qualified name. `.ptr`, `.len`, `.cap` read the header words of a `str`
or slice.

### 8.5 Composite literals

```
StructLit = TypeName "{" [ FieldInit { "," FieldInit } ] "}" .
FieldInit = ident ":" Expr .
ArrayLit  = "[" [ Expr { "," Expr } ] "]" .
TupleLit  = "(" Expr "," Expr { "," Expr } ")" .
```

`S{}` is the zero value of `S`.

### 8.6 Builtins

`size(T)` (type size), `len(x)` (str/slice/array length), `alloc(v)!`
(heap-allocate a value, yield `*T`; §9), `append(s, x)` (grow a slice),
`delete(…)`, `abort(msg)` (terminate; type `never`).

`alloc` takes a *value*: `alloc(T{…})!`, `alloc(T{})!`, or
`alloc(expr)!`. Bare `alloc(T)!` is invalid (it parses `T` as a value
reference) (§12). There is no `free`: ww has no GC and no manual
reclamation in compiler-side code — allocation lives until process exit
(§12). `lib/*` modules that genuinely own a heap buffer free it
explicitly via `os.free`.

---

## 9. Errors

ww has no exceptions. A fallible operation returns a tagged union whose
error variants carry the `!T` mark (§3.7). Two postfix operators consume
them:

- `expr?` — if `expr` is an error variant, return it from the current
  function (propagate); otherwise yield the success value.
- `expr!` — if `expr` is an error variant, abort; otherwise yield the
  success value.

Error variants are ordinary sentinel types in the union
(`strconv.invalid`, `strconv.overflow`, …), discriminated with `match`.
This mirrors Hare's error idiom, spelled with ww's `!` tag.

---

## 10. Tests

A function marked `@test` is a test, run by the test harness, not part of
the program. Two placements, following the Go `foo` / `foo_test` model:

- **White-box**, in-package: a colocated file `package <mod>;` with
  `@test` functions, for testing unexported internals.
- **Black-box**, external: `package <mod>_test;` with `import <mod>;`,
  exercising only the public surface.

```ww
@test fn adds() void = {
	if (1 + 1 != 2) { abort("math broke"); };
};
```

Production, production-plus-white-box-test, external black-box-test, test
support, recompiled-for-test dependencies, and generated test main are distinct
package actions. One canonical selected directory owns one test product and one
generated main, which imports every applicable same-package and external target
and produces one binary/result. The external action's import of the package
under test binds to the augmented white-box action when it exists; affected
transitive importers are copied and rewired so ordinary and augmented package
state do not coexist in the linked closure.

A non-function package-scope `main` in production or same-package test source
of a package declared `main` is a package-checker failure. Generated test-main
ownership does not hide or replace it: the product is not linked or executed,
no test accounting or package `ok` result is emitted, and ordinary build/test
failure presentation and rollback apply.

Those variants are action distinctions over exact package representatives, not
new ordinary package identities for case-fold comparison. Production,
same-package test, external test, and recompiled copies of one exact canonical
package therefore do not collide with each other. Their selected source units
remain separate, while the directory-owned filename preflight spans the
production/internal/external selections applicable to that test product.

Before a test function runs, the one generated product initializes its exact
effective graph dependency-first and once per canonical action. Imports,
runtime lets, and init declarations found only in `*_test.ww` never enter an
ordinary production build. Test-only same-package, external-package, and valid
mixed directories are accepted from their selected test files. A directory
with no selected test file validates ordinary production but creates no test
support, generated main, link, binary, captured runtime result, or process. The
coordinator reports that successful validation exactly as
`?    <package> [no test files]\n`.

An exact `package documentation` source that reaches a test selection is
suppressed by the package rule in §4 before production, same-package, or
external-test family construction. It contributes no `@test`, dependency,
initializer, support action, generated-main input, binary, process, captured
result, or retained output. In a mixed directory the test product is exactly
the product of the ordinary sources alone; a doc-only directory is not the
successful production-with-no-tests case. A direct running directory request
instead fails with `FAIL\n` and the coordinator's
`directory contains no WW package sources` diagnostic, while `-c` omits
`FAIL`. A selected named or logical raw running request likewise emits `FAIL`
and its physical parent's driver no-source diagnostic; raw `-c` and `-S` omit
the marker. Directory `-S` without the required `-o` retains
`ww test: -S needs -o`; after a valid `-o`, it retains
`ww test: -S needs a single test file`. Both precede source classification.
Recursive doc-only matches are omitted as packages: running test reports the
per-pattern no-match warning followed by `ww test: no packages to test`, while
mixed recursive selections run only ordinary groups. A documentation-header
error retains precedence over every no-source result; an explicit running test
adds `FAIL`, but compile-only and assembly-only routes do not.

Every test-bearing directory product links one request-private runnable.
The test output-option name is exactly `o`, with the accepted forms `-o VALUE`,
`--o VALUE`, `-o=VALUE`, and `--o=VALUE`. Equals forms split only at their
first `=` and preserve an empty value or any additional `=` bytes. Repeated
occurrences are last-value-wins. A final empty value means no effective
explicit output and therefore requests no running-test retention; with `-c`,
the ordinary default retained name applies. A concatenated `-oVALUE` or
`--oVALUE` is unknown. Unlike build option parsing, known test options,
including these exact output forms, are recognized before or after package
operands. Invalid output-option names reject before package loading, product
construction, execution, or publication.
`-c` retains an executable copy and suppresses its execution; a nonempty
effective `-o` retains a copy at the named destination and still executes
unless `-c` is present. With no effective explicit output, `-c` writes
`<import-leaf>.test` in the invocation directory. An output ending in `/` or
naming an existing directory receives that basename and may have missing
parent directories created. One
non-directory output may name only one package. Multiple packages whose
visible import leaves would produce the same test-binary name reject before
tools or output creation; exact `/dev/null` is the discard exception. It keeps
the ordinary private link and, unless `-c` is present, the ordinary execution,
but installs no retained copy. The raw single-file compatibility route uses
the same private-output rule and never treats `/dev/null` as an explicit
artifact or adjacent-scratch stem. Declared
package names, test variants, source filenames, physical directories, output
paths, and retained binary names remain presentation or loader metadata and do
not become canonical package or action identity.

The retained file is an executable, byte-identical copy of the private
runnable. A compile-only retained binary joins package artifacts and statuses
in the request-wide atomic publication transaction. Build, link, stage, or
install failure preserves old destinations and removes temporary stages and
invocation-created output prefixes. For a running `-o` request, the private
binary executes first. Only a successful run enters the guarded install
action; a failed, signalled, timed-out, interrupted, or unstartable run
publishes no new copy and preserves any prior destination. The post-run guard
uses the same directory/nonempty-regular/object-magic rule as `ww build`.
Successful products in a multi-package running request install independently;
their visible result order remains package order. A no-test product publishes
no binary and does not create a directory solely for one.
`-w` may persist the unchanged semantic actions for either `-c` or running
retention without changing publication identity or introducing a test-result
cache.

When `ww test` executes a directory-owned product, the child process working
directory is that product's canonical absolute physical package source
directory. Its per-run environment has exactly one effective uppercase `PWD`,
with that same value. The physical source directory is execution context, not
canonical package identity: it does not enter dotted identity, import binding,
action identity, mangled symbols, `.wwi`, artifacts, or persistence keys.
Production, internal-test, external-test, recompiled-for-test, support, and
generated-main actions in the product share the one process context while
remaining separate actions. Reachable dependency initialization consequently
observes the tested product's directory; a dependency tested as its own product
observes its own directory.

Every test binary actually started by `ww test` receives one effective uppercase
`PATH` whose first element is the canonical absolute directory of the selected
WW driver. An absent or empty caller `PATH` yields only that directory; a
nonempty effective caller value follows it after `:`. Normal duplicate `PATH=`
entries collapse to that one value, using the caller's first effective value as
the suffix. This applies to directory products, their dependency initialization,
filters and list mode, running retained tests, and the raw single-file
compatibility route. It does not apply to build tools, `ww build`, `ww run`,
compile-only or assembly-only test requests, no-test products, or later direct
execution of a retained binary.

An executed directory product otherwise receives the caller's original Unix
environment, not the build plan's tool environment. The snapshot keeps the
first occurrence of each normal case-sensitive `key=value`, omits later normal
duplicates and raw empty entries, and retains every nonempty malformed entry in
order. It then applies only the effective `PATH` above and the package `PWD`.
Consequently caller `LC_ALL`, `TMPDIR`, empty-valued variables, case-distinct
keys, and arbitrary variables remain visible to production or test-only
initialization and test bodies. The compiler, assembler, archiver, linker, and
coordinator scratch continue to use their separate build-plan locale and
temporary directory.

The same coordinator-executed product reads standard input from the null
device. Its first read observes EOF regardless of the terminal, pipe, or file
connected to the invoking command. Each parallel product owns a separate null
descriptor, and production or test-only dependency initialization, filtering,
listing, no-match execution, failure, and timeout all retain that boundary.
Standard input is runtime process metadata and contributes no package, action,
artifact, or persistence identity.

The product's standard output and standard error refer to one product-local
capture. Bytes from either descriptor retain the order in which their writes
reach that shared open output, and the coordinator emits the completed capture
on its standard output. Immediately before an existing directory-product
`ok` or run-status `FAIL` trailer, a nonempty capture whose final byte is not
newline receives exactly one newline; an empty or already newline-terminated
capture receives none. The capture itself is unchanged, and raw single-file or
later direct retained-binary execution has no coordinator trailer and no such
separator. A runtime failure or child-setup failure appends the product status
diagnostic to standard output as well. Loader, source, compiler, assembler,
linker, and other build failures retain their diagnostic standard-error
channel; build-action stdout and stderr remain separate. Parallel products own
independent captures and are still emitted in canonical product order.

List mode starts the same directory-owned product and therefore performs its
ordinary package initialization, but it does not start any selected test child.
The harness emits exactly one newline-terminated qualified name for each test
selected by the command's filters, in descriptor order. If the selected set is
empty, the harness emits no list payload, warning, or accounting and returns
success; the coordinator still emits the ordinary successful package result
without a no-tests suffix. Ordinary non-list execution is distinct: a valid
filter selecting no tests writes exactly
`testing: warning: no tests to run\n` through the harness's standard error,
preserves the discovered/selected/started/completed accounting and successful
exit, and causes a successful directory package result to end in
` [no tests to run]`. The coordinator recognizes that exact warning only at
capture byte zero or after a newline. Directory execution combines the warning
and accounting in its product-local capture; a retained binary invoked directly
keeps the warning on standard error, its accounting on standard output, and has
no coordinator package result.

Calling `test.skip(reason)` from an active test records a successful skip and
stops that test body. The empty string is a valid reason: `test.skip("")` is
not a malformed harness result. Its ordinary result line is exactly the
qualified test name, ` ... SKIP: `, and a newline, with no reason bytes after
the space. It increments skipped accounting once, increments neither failed nor
harness-error accounting, and permits later selected tests to run. The same
classification applies to raw single-file, same-package, external-package, and
honest test-only descriptors; an active-test call reached through production
package code; filtered execution; a coordinator-run retained binary; and later
direct execution of a retained binary. Production files do not acquire a test
descriptor. A nonempty reason keeps the same presentation with its bytes after
`SKIP: `. An oversized reason remains an invalid control result, and
`test.skip` outside an active test still aborts. This result rule does not
change the current per-test process boundary, list mode, filtering language,
package initialization, or package/import/action identity.

After those ordered results, an ordinary explicit `ww test` request that records
an attributable setup, build, or execution failure emits exactly one standalone
`FAIL\n` on standard output. The line is command-owned: it follows even a later
successful package result, and a single explicit directory, recursive or dotted
directory, or raw source file is sufficient. Runtime nonzero exit, signal,
timeout, or executable-start failure all set that status. Filters, list mode,
and the private execution of a retained test keep the same rule. Bare implicit
current-directory `ww test`, `-c`, `-S`, build requests, CLI usage/shape or
output preflight, publication-only failure, capture-only failure, cleanup-only
failure, and later direct execution of a retained binary do not emit it. The
marker changes no capture, diagnostic, executable, package/import/action
identity, publication decision, or persistent byte.

The coordinator does not change its own cwd or environment. Parallel products
receive independent child environments and each uses its own source directory.
Relative ordinary files, `testdata`, and writes resolve there for every
executing filter or list path. `ww build`, directory `ww test -c` (including
`-c -o`), and a no-selected-test directory execute no test child and receive no
execution-directory effect. A published test binary invoked directly, and the
raw single-file compatibility route, inherit the user's invocation cwd and
three standard descriptors; no package directory, input, or output policy is
embedded or forced by the binary. Directly invoked retained binaries inherit the
entire caller environment. Raw single-file tests preserve every caller
environment field except the test-only `PATH` transformation above.

---

## 11. Concurrency (reserved)

The headline `+CSP` surface — `chan T`, `proc`/`spawn`, channel send/
receive `<-`, and the `alt` select construct — is tokenised
(`chan`, `proc`, `<-`, `->`) but **not yet given semantics**. This
section is written when the feature lands; until then, use of these
tokens is rejected by the checker.

**Meta-ruling (normative).** CSP is *the* sanctioned departure from the
Hare-fidelity rules (CLAUDE.md rules 5 and 9) — Hare has no channels, and
the `+CSP` mandate is the project's reason to add them. The concurrency
surface therefore cites the Newsqueak → Limbo → Go lineage, **not** Hare,
and that citation is correct by construction, not a rule-9 violation. The
design of record is `.ai/csp-design-input.md` (library-first: `spawn`,
unbuffered bidirectional `chan T` via `mkchan(T)`, `<-` send/recv,
`recv → (T | closed)` error idiom, `alt` as v2). See §12 entry 9.

TODO(spec): fill in syntax + semantics (channel construction, send/recv
typing, `spawn` arg-copy ABI, `alt` arm grammar, the `closed` sentinel)
once the MVP lands and the USER meta-ruling is explicitly on record.

---

## 12. Divergences from Hare (normative)

ww follows Hare's semantics and `lib/` API shapes (CLAUDE.md rules 5, 9)
except for the deliberate, USER-blessed departures below. Each is
normative; the cited reference is the rationale of record.

1. **`int`/`uint` are a machine word (8 bytes), not Hare's 32-bit
   `int`.** All limit constants derive from `size(int)`; `size`/`uintptr`
   are 8 bytes. *Ref: project memory "int is a machine word"; USER
   2026-05-26.*

2. **Tuples use 8-byte slots, not Hare's packed layout.**
   `size((u32, u32)) == 16`. Routed through the type table only.
   *Ref: USER 2026-06-04 tuple slot ruling; parity task #60.*

3. **Nullability is the union `(*T | void)`, not a `nullable`
   qualifier.** Plain `*T` is non-null; the union fold is one flag,
   zero-cost for the non-null path. *Ref: USER 2026-05-26 nullable-kept
   ruling.*

4. **No `_unsafe` suffix convention.** ww is unmanaged (no GC, no safe
   baseline), so Hare's `_unsafe` axis does not apply. `bytes`→`str` is
   the pure reinterpret `strings.frombytes` (Hare's `fromutf8_unsafe`);
   UTF-8 validation is opt-in at the IO source via `utf8.validate`, not
   wrapped per construction. *Ref: CLAUDE.md rule 9; ref/hare/strings/
   utf8.ha.*

5. **The compiler frontend is one package `lib/ww/syntax`** (tok + lex +
   ast + sym + typ + parse), a Go-over-Hare consolidation of Hare's
   `{ast, lex, parse}` split. Its single consumer is the `wcc` backend.
   The internal data shapes still mirror `ref/hare/hare`. *Ref: CLAUDE.md
   rule 6; USER #74.*

6. **Tests use the Go `foo` / `foo_test` model** (§10): external
   black-box `package <mod>_test;` plus in-package white-box `@test`
   files. ww hard-rejects self-import. *Ref: CLAUDE.md rule 9; task #16.*

7. **No arena / no `free` in compiler-side code.** Per-node
   `alloc(value)!`; allocation is reclaimed at process exit. `alloc`
   takes a *value* (`alloc(T{…})!`), never a bare type. *Ref: project
   memory "drop amalloc", "Phase 0 closed", "alloc syntax form".*

8. **The checked AST carries a per-node `type_` stamp.** Hare's parse
   AST is untyped and harec keeps a separate checked AST in C; ww stamps
   `node.type_` in place as a checker invariant. *Ref: project memory
   "Hare AST has no per-expr result".*

9. **CSP** (§11) is the sanctioned departure from rule-5/9 Hare fidelity
   — Hare has no channels. The surface cites Newsqueak/Limbo/Go, not
   Hare. *Ref: `.ai/csp-design-input.md`; pending explicit USER
   meta-ruling.*

10. **The two compiler stages emit byte-identical asm** for the same
    input (CLAUDE.md rule 10); when inference power differs, the richer
    stage is aligned *down* to the leaner one. This is a project
    invariant, listed here because it is the contract this spec's "the
    text is the bug if stages disagree with it" rule rests on.

---

## Appendix A. Anti-rot

This spec is hand-maintained. To keep it from drifting against the
parser, every fenced ` ```ww ` example is intended to be extracted and
compiled through `w6c`, asserting it parses (or rejects, for
negative examples), wired as a `make spec-check` dependency of
`make test`. The EBNF
productions are not auto-verified; the compiling examples are the drift
alarm. *(Check not yet implemented; filed as a follow-up.)*