@amritk/nish-x86_64-linux 0.20.0 → 0.22.1

package/docs/AI.md

@@ -0,0 +1,2777 @@
+# Writing Nish: the rules card
+
+This is the **whole language, stated as rules, for a model that has to write
+Nish and get it accepted on the first try**. It is a digest, not the authority:
+[`LANGUAGE.md`](LANGUAGE.md) is normative and settles every disagreement, and
+[`IR_COOKBOOK.md`](IR_COOKBOOK.md) shows the exact IR each construct lowers to.
+This page exists because LANGUAGE.md is 2,300 lines written to be *read*, and
+what an author needs is the rules in one pass with the traps first.
+
+> Working **on the compiler** rather than **in the language**? That is a
+> different document: [`AGENTS.md`](../AGENTS.md) and [`.claude/`](../.claude/).
+
+Nish is a strictly static subset of TypeScript compiled ahead of time to LLVM
+IR. Every Nish program is legal TypeScript *syntax* — it is parsed by the
+official TypeScript parser — and with
+[`runtime/nish.d.ts`](../runtime/nish.d.ts) on the include path it type-checks
+under `tsc --strict` too. That is the trap this page exists for: **your
+TypeScript instincts produce programs that parse, that `tsc` accepts, and that
+`nish` rejects.** The subset is much smaller than it looks.
+
+Contents: [The loop](#the-loop-compile-read-the-code-fix) ·
+[A whole program](#a-whole-program) ·
+[What you must unlearn](#what-you-must-unlearn) · [Types](#types) ·
+[Failure](#failure-result-not-exceptions) · [Absence](#absence-nullable-types) ·
+[Declarations](#declarations) · [Generics](#generic-functions) ·
+[Calling C](#calling-c) · [Statements](#statements) ·
+[Expressions](#expressions) · [The builtins, in full](#the-builtins-in-full) ·
+[Memory](#memory) · [Recipes](#recipes-for-what-is-missing) ·
+[Before you say it compiles](#before-you-say-it-compiles)
+
+## The loop: compile, read the code, fix
+
+Do not reason about whether a program is legal. Ask the compiler — it is fast,
+and it is the only authority.
+
+```bash
+nish program.ts --json            # one JSON object per diagnostic, on stdout
+nish --fix program.ts             # apply every machine-applicable fix, then report what is left
+nish program.ts -o out.ll         # emit LLVM IR
+nish program.ts --link prog       # build a native binary (needs clang)
+nish run program.ts a b           # build into a cache, then run it with `a b`
+                                  # (the C runtime is cached too: ~/.cache/nish/runtime)
+nish --help                       # the full flag list, stdout, exit 0; plain text
+                                  # under an agent (NISH_AGENT=1, CLAUDECODE, GEMINI_CLI)
+```
+
+`--json` is the surface to automate against. One flat object per line on
+stdout, nothing on stderr, every field 1-based with `endLine`/`endColumn`
+exclusive:
+
+```json
+{"file":"p.ts","line":3,"column":17,"endLine":3,"endColumn":20,"severity":"error","code":"NL2249","message":"Unknown method `map` on i32[] (supported: push, pop, indexOf, join, set, fill)"}
+```
+
+- **Key on `code`, never on `message`.** A code is a promise: `NL2249` means
+  the same rule next release. The prose may improve; the code may not.
+- **`severity`** is `"error"`, `"performance"`, `"portability"` or
+  `"deprecation"`. A warning of any kind never changes the exit code — it is
+  advice, not a rejection. Portability warnings, the sites where the program's
+  TypeScript reading answers differently, print only under
+  `--warn-portability`; a deprecation warning names a call a later release
+  takes away and what to write instead, and always prints.
+- **Bands**: `NL1xxx` the Phase 0 forbidden-syntax sweep, `NL2xxx` the checker,
+  `NL3xxx` the driver and modules, `NL4xxx` the interop sidecars, `NL7xxx`
+  deprecation, `NL8xxx` portability, `NL9xxx` performance, `NL0001` syntax, `NL0002` toolchain, `NL0003` internal,
+  `NL0000` a diagnostic with no rule yet.
+- **Exit codes**: `0` ok, `1` the program was rejected, `2` usage, `3` the C
+  toolchain is unusable, `70` an internal compiler error — that last one is a
+  bug in `nish`, not in your program, and is worth reporting. `nish run`
+  answers the same codes until the program starts, and the program's own
+  status after that.
+- Every failure is a `--json` object, toolchain and internal errors included,
+  so you never have to parse stderr to find out why a run failed.
+
+Some diagnostics carry a **`fix`**: the edits that make the line compile,
+when the rewrite is mechanical and keeps the program's meaning. It comes last,
+and each edit is placed exactly as the diagnostic is — `text` replaces the span,
+and a span whose start equals its end is an insertion:
+
+```json
+{"file":"p.ts","line":2,"column":10,"endLine":2,"endColumn":16,"severity":"error","code":"NL1047","message":"Loose equality is forbidden; use === / !==","fix":[{"line":2,"column":12,"endLine":2,"endColumn":14,"text":"==="}]}
+```
+
+A diagnostic with no safe rewrite has no `fix` key at all. `nish --fix
+program.ts` applies every fix to the files named on its command line (never to
+an import from `std/` or `node_modules`), recompiles, and repeats until nothing
+changes or five rounds pass; then it reports what is left exactly as a plain
+run would, `--json` included, and exits with that run's code. It writes no IR,
+so it refuses `-o` and `--link`. It rewrites your files in place, with no
+backup, so run it on a committed or backed-up tree. Run it first, then read
+what remains. A warning can carry a fix too, and `--fix` applies it only when the program
+compiles and the warning would be printed: `NL9007`'s inserts the guard that
+proves an index in range (not under `--no-warn-performance`), and `NL7002`'s
+migrates a site off `--unchecked-indexing` (below).
+
+When it compiles, **check the native build against the program's TypeScript
+reading**. Run the project's tests natively; where it has none, write the
+program back out and run both:
+
+```bash
+nish program.ts --emit-ts out/    # the program as TypeScript, plus out/entry.ts
+node out/entry.ts                 # Node 22.18 or newer; compare with the binary
+```
+
+The two must print the same and exit the same, a panic included: `--emit-ts`
+keeps the overflow and bounds checks the native build makes, but not a ranged
+integer's range (`integer<0, 255>` is a plain `number`). Where they differ,
+the difference is a row of [the user guide's table](guide/using-nish/to-typescript.md),
+or a bug in `nish` worth reporting. A program on `nish:net`, the signal
+descriptor or a C declaration (NL4010, NL4011), a compound assignment whose
+index would run twice (NL4012) or a generic whose element type decides its
+code (NL4013, NL4014) is refused and has no TypeScript to run.
+
+Two more surfaces worth knowing: `nish --emit-ast f.ts` prints what was parsed
+and `nish --emit-checked f.ts` prints the side tables the emitter reads. Both
+are one node per line, which is to say diffable.
+
+## A whole program
+
+```ts nish:ok
+const gcd = (a: i32, b: i32): i32 => {
+  let x = a;
+  let y = b;
+  while (y !== 0) {
+    const t = y;
+    y = x % y;
+    x = t;
+  }
+  return x;
+};
+
+export const main = (): i32 => {
+  console.log(`gcd = ${gcd(1071, 462)}`);
+  return 0;
+};
+```
+
+That is the shape: top-level `const` arrows, an exported `main`, explicit types
+everywhere, a template literal instead of `String(n)`.
+
+- A module is one `.ts` file. At the top level it may hold **only**
+  declarations: `const` arrows (functions), `class`, `interface`, module
+  `const`s, `type` aliases, numeric `enum`s, and `import`s. There is no
+  top-level code, so there is no initialisation order to think about.
+- `export const main` lives in the entry module only, takes no parameters, and
+  returns `void` or an `i32`-lowered `number` — the process exit code. Under
+  `--number-mode f64`, declare it `main(): i32`.
+- `number` is `i32` by default and `f64` under `--number-mode f64`. Write the
+  explicit width (`i32`, `f64`) when you mean one; it reads the same in both
+  modes.
+
+## What you must unlearn
+
+Every row is something a TypeScript-trained model writes by reflex and Nish
+rejects. This table is the highest-value part of the page.
+
+| Your reflex | What happens | Write instead |
+| --- | --- | --- |
+| `if (xs.length)`, `!xs.length`, `if (s.length && ok)` | `Condition must be boolean … (Nish has no truthiness)` / `` Unsupported unary operator `!` on i32 `` / `` Operator `&&` requires boolean operands, got i32 and boolean `` | `if (xs.length !== 0)`, `xs.length === 0`, `if (s.length !== 0 && ok)`; `nish --fix` writes each where it is the test `tsc` reads (an operand of `&&` or `\|\|` only where the whole is a condition or under `!`) |
+| `x == y` | `Loose equality is forbidden` | `x === y` |
+| `throw new Error(m)` | `` `throw` is forbidden `` | `return Err(m)`, or `panic(m)` to end the process |
+| `try { … } catch { … }` | `` `try`/`catch`/`finally` is forbidden `` | `Result<T, E>` and `isErr()` |
+| `xs.map(f)`, `.filter`, `.reduce`, `.forEach`, `.slice`, `.sort`, `.shift` | `` Unknown method `map` on i32[] (supported: push, pop, indexOf, join, set, fill) `` | a `for` loop, or a top-level `map(xs, f)` with a [function parameter](#function-parameters) |
+| `s.toUpperCase()`, `s.split()`, `s.trim()`, `s.replace()` | `` Unknown method … on string `` | index bytes with `charCodeAt` / `substring` |
+| `a?.b`, `a ?? b` | `?.` only in a chain that ends in `??`; `??` only on a `T \| null`, a chain or `m.get(k)` | `a?.b ?? d`, `a ?? d`, or `if (a !== null)` first |
+| `x as T`, `<T>x`, `x satisfies T` | `Unsupported expression in Phase 1: AsExpression` (to `any` or `unknown`: `` Type assertion to `any` is forbidden ``); `x!` is a syntax error | there are no casts; `implements` is the only widening |
+| `typeof x`, `x instanceof C`, `"k" in o`, `delete o.k`, `void 0`, `a, b` | each refused by name (`` `typeof` is forbidden ``, …) | there is no runtime type information: a value's type is its declared one |
+| `a ** b`, `[...xs]`, `[1, , 2]` | `` Unsupported binary operator `**` `` / `Spread in array literals is not supported` / `Holes in array literals are not supported` | `Math.pow` on `f64`, a loop, every element written out |
+| `any`, `unknown` | forbidden | name the real type |
+| `undefined` | forbidden, except `x === undefined` on a `Map.get` result | `null`, with a `T \| null` type |
+| `let total = 0` at the top level | `` Top-level `let` is not supported `` | a module `const`, or a local |
+| `for (const k in o)` | `` `for...in` is forbidden `` | `for (const x of xs)` over an array, or `for (const k of m.keys())` over a `Map` |
+| a callback stored or returned: `const cb = (n: i32) => n`, a field `cb: (n: i32) => i32` | `An arrow may only be written as the argument for a function-typed parameter` / `` … is a function type, which may only annotate a parameter of a top-level function `` | there are **no function values**; a callback the call names is a [function parameter](#function-parameters) |
+| `type Pair<T>` (a generic alias) | `Generic type parameters are forbidden on a type alias` | a generic **function**, **class**, **interface** and **method** all work — see below; an alias renames a type that already exists, so it has nothing to specialise |
+| `constructor<T>(x: T)` | a syntax error: `a constructor cannot have type parameters` | put the parameter on the class (`class Box<T>`), or on a method |
+| `h.get<i32>(7)` (type argument at a method call) | `Type arguments are not written at a call site in Nish` | `h.get(7)` — a generic method infers like a generic function |
+| `<T>(p: T) => p.x` (a member of a type parameter) | `` Cannot read `x` of `T`: an unconstrained type parameter has no members `` | `<T extends Point>(p: T) => p.x`, where `Point` is a class or interface that declares `x` |
+| `identity<i32>(7)` (type argument at a call) | `Type arguments are not written at a call site in Nish` | `identity(7)` — `T` is inferred from the arguments |
+| `async` / `await` / `Promise` | forbidden (no event loop) | the I/O builtins are synchronous |
+| `namespace N { }`, `declare global { }`, `@decorator` | forbidden | one module per file; a plain function in place of a decorator |
+| `keyof T`, `<T = i32>` (a default type argument) | `` Unsupported type `keyof T` (Phase 1 supports …) `` / `a default type argument … is not supported` | name the type; a type argument is always inferred |
+| `class B extends A` | `` `extends` is not supported: Nish has no inheritance `` | repeat the fields and `implements` an interface |
+| `static` members, `get x()` / `set x(v)` | `` … `static` members are not supported `` / `` Getters and setters are not supported in class `C` (use a method) `` | module `const`s and plain methods |
+| `const [a, b] = xs`, `({ x }: Point) =>`, `(n = 1)`, `(n?: i32)`, `(...ns: i32[])` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional/default parameters are not supported` / `Rest parameters are not supported` | one name per binding, every parameter passed; an array for a variable count |
+| `function f(): void;` (an overload), `export default function ()` | `Functions must have a body` / `Functions must be named` | one named function, with its body |
+| a method in an `interface` | `` Interface `I` cannot declare methods (interfaces describe layout only) `` | fields only; a top-level function over the interface |
+| `abstract class`, `declare class`, `constructor(public x: i32)`, `interface B extends A`, `[k: string]: T` | `Abstract classes are not supported` / `` `declare class` is not supported `` / `Parameter properties … are not supported; declare the field and assign it` / ``Interface inheritance (`extends`) is not supported; list every field`` / `Index signatures are not supported …` | a plain class with its fields declared and assigned in the constructor; every field listed; a `Map` for a keyed table |
+| `{ m() { … } }`, `{ "a": 1 }`, `const C = class { }` | ``Unsupported object literal member: MethodDeclaration (only `key: value`)`` / `Object literal keys must be plain identifiers` / `Classes must be named` | fields with identifier keys, a top-level function over the interface, a named top-level class |
+| `{ ...base, x: 1 }`, `{ [k]: v }`, `[k]: i32` in a class or interface | `Object spread is forbidden in Nish (set each field by name)` / `Computed property names are forbidden in Nish (member names are fixed at compile time)` | every field written by name (`{ x: 1, y: base.y }`); a `Map` for a keyed table |
+| `type Pair = { a: i32 }` (inline object type) | `` Unsupported type `{ a: i32 }` `` | declare an `interface` |
+| `A \| B` unions of anything but tagged classes and interfaces | `` Union types other than `T \| null` are forbidden `` | a [discriminated union](#discriminated-unions): a tag field first in each variant |
+| `String(n)`, `n.toString()` | `` Unknown function `String` `` / `` Unknown method `toString` on i32 `` | `` `${n}` `` |
+| `xs.length = 0` | `` Cannot assign to `length` of i32[] (array length is read-only; use `push`) `` | build a new array |
+| `import { readFileSync } from "fs"` | `` Cannot find package `fs` `` — a bare specifier is a **package name**, so it is looked for in `node_modules`; one that is installed but has no `nish` condition is `` Package `fs` has no Nish entry point `` | `readFileSync` is a global; no import needed (or `import { readFileSync } from "nish:fs"`) |
+| `export default f` | `` `export default` / `export =` are not supported; use a named `export function` `` | `export const f = …` |
+| `export { f }`, `export * from "./m"`, `export default function f` | `` `export { ... }` / `export * from` are not supported; put `export` on the function declaration itself `` / `` `export default` is not supported; use a named `export function` `` | `export` on the declaration itself |
+| `import d from "./m"`, `import * as m from "./m"`, `import "./m"`, `import type { T } from "./m"` | `` Default imports are not supported; use `import { d } from "./m"` `` / `` Namespace imports (`import * as m`) are not supported; import functions by name `` / `` Side-effect imports (`import "./m"`) are not supported; modules have no top-level code `` / `Type-only imports are not supported` | `import { d, T } from "./m"`, naming what you use |
+| `total += xs[i]` in a loop, with `i` from somewhere the compiler cannot bound | it compiles, with an `NL9007` performance warning: `` `i` is not proven to be in range for `xs` here, so this access keeps its bounds check `` | a guard before the statement, `if (!(i >= 0 && i < toI32(xs.length))) { panic("index out of range") }`, which proves both ends in either number mode; `nish --fix` inserts it where it changes nothing the program does |
+| `new Date()` | `` `new Date()` is refused: Nish has no `Date` object; the one `Date` member is `Date.now()`, the wall clock in milliseconds `` | `Date.now()` for the wall clock, `monotonicNanos()` for elapsed time; there is no calendar |
+| `JSON.parse`, `RegExp`, `/re/` literals, `Promise` | unknown / forbidden | none of these are built in: `regexCompile(pattern, flags)` from `nish/regex` for a pattern, `jsonDecode` from `nish/json-typed` for JSON; restructure around `Promise` |
+| `for (const [k, v] of m)`, `m.forEach(...)`, `new Map(entries)` | each refused by name | `Map` and `Set` exist, with `size`, `get`, `set` / `add`, `has`, `delete`, `clear`, and `keys()` / `values()` in a `for...of` — see [Map and Set](#map-and-set) |
+| `let v = m.get(k)`, `f(m.get(k))`, `m.get(k) + 1` | `` `m.get(k)` is `i32 \| undefined` and cannot be held in a `let` `` (and one message per place) | `m.get(k) ?? 0`, or `const v = m.get(k); if (v !== undefined) { … }` |
+| `let x = 5; x = "s"` | `Cannot initialize …` | types never change and never convert implicitly |
+
+A worked pair. This is the single most common rejection:
+
+```ts nish:err-body NL2188
+const xs = [1, 2, 3];
+if (xs.length) {
+  console.log("non-empty");
+}
+```
+
+```ts nish:ok-body
+const xs = [1, 2, 3];
+if (xs.length !== 0) {
+  console.log("non-empty");
+}
+```
+
+## Types
+
+Every type is exactly one LLVM first-class type. No boxing, no runtime tag, no
+structural subtyping, **no implicit conversion of any kind**: two values are
+compatible only when their types are identical.
+
+| Type | Is | Notes |
+| --- | --- | --- |
+| `number` | `i32`, or `f64` under `--number-mode f64` | the mode's default width |
+| `i32`, `i64` | signed integers | overflow **panics** (exit 1) unless proven to fit; `wrappingAdd`/`wrappingSub`/`wrappingMul` from `nish:unsafe` wrap |
+| `u8`, `u16`, `u32`, `u64` | unsigned integers | arithmetic **always** wraps; `>>` is logical |
+| `f32`, `f64` | IEEE-754 | `f32` is never the lowering of `number` |
+| `boolean` | `i1` | no truthiness anywhere |
+| `string` | immutable UTF-8 bytes | `length` is the **byte** length |
+| `T[]`, `Array<T>` | one element type, bounds-checked | `readonly T[]` refuses every write |
+| `Int32Array`, `Float32Array`, `Float64Array`, `BigInt64Array` | aliases of `i32[]`, `f32[]`, `f64[]`, `i64[]` | not distinct types; fixed length, so no `push` or `pop` (NL2415): declare `f64[]` to grow one |
+| `class C`, `interface I` | a struct, fields in declaration order | no header, no vtable |
+| `enum K` | a **distinct** type represented as `i32` | never interchangeable with `i32` |
+| `K.M` | an enum member type: the one member `K.M`, as `i32` | holds only that member; a read is a `K` |
+| `T \| null` | `T` a class, interface, array, or string | a scalar can never be nullable |
+| `A \| B` of tagged variants | a pointer to the variant; its first field is the tag | [Discriminated unions](#discriminated-unions); only the tag is read until a test of it narrows |
+| `Result<T, E>` | the only way to report failure | `E` may not be `void` |
+| `void` | return type only | |
+
+**An unchecked index and a defined wrap are `nish:unsafe` imports**, written at
+the site: `uncheckedGet(xs, i)` and `uncheckedSet(xs, i, v)` on an array of
+numbers with an `i32` index (out of range is undefined behaviour), and
+`wrappingAdd` / `wrappingSub` / `wrappingMul` on two `i32`s or two `i64`s.
+The sixth export, `readCString`, copies a C string out of a `CPtr`
+([Calling C](#calling-c)). Calling one without the import is NL2456. `--unchecked-indexing` and
+`--wrapping` are deprecated (NL9014, NL9015) and reach only your own package,
+never a dependency or `nish/`. To migrate off `--unchecked-indexing`, run
+`nish --unchecked-indexing --fix` on your files: each index the flag leaves
+unchecked is a `deprecation` warning of its own (NL7002), and where the site
+is a number array with an `i32` index its `fix` rewrites it to `uncheckedGet`
+or `uncheckedSet` and adds the import. A site with no rewrite keeps its
+warning; dropping the flag gives it back its bounds check.
+
+```ts nish:ok
+import { uncheckedGet, wrappingAdd, wrappingMul } from "nish:unsafe";
+
+export const hash = (bytes: u8[]): i32 => {
+  let h: i32 = 17;
+  for (let i: i32 = 0; i < toI32(bytes.length); i++) {
+    h = wrappingAdd(wrappingMul(h, 31), toI32(uncheckedGet(bytes, i)));
+  }
+  return h;
+};
+```
+
+**Mixing widths is an error, always.** `f32 + f64`, `i64 + number`, even
+`u32 + i32` (same LLVM type, different signedness) are rejected. Convert
+explicitly: `toI32` `toI64` `toU8` `toU16` `toU32` `toU64` `toF32` `toF64`.
+
+**Signed overflow panics.** `+ - *`, unary `-`, `++`, `--` and `op=` on an
+`i32` or `i64` stop the program with `attempt to add with overflow` (or
+`subtract`, `multiply`, `negate`) and exit 1 when the result leaves the type;
+it is never a silent wrap and never undefined. The compiler drops the check
+where it can prove the result fits — a loop counter under `i < n`, a byte
+widened with `toI32`, an `integer<Lo, Hi>`, a value masked with `& c`. Arithmetic
+that is *meant* to wrap — a hash, a PRNG, a checksum — goes in `u32` or `u64`,
+which always wrap and are never checked; convert back with `toI32` (free), or
+call `wrappingAdd` / `wrappingSub` / `wrappingMul` at the site. The deprecated
+`--wrapping` makes every signed operation of your own package wrap instead.
+
+```ts nish:ok
+// FNV-1a: the multiply overflows on purpose, so the state is a `u32`.
+export const fnv1a = (bytes: u8[]): u32 => {
+  let h: u32 = 2166136261;
+  for (const b of bytes) {
+    h = (h ^ toU32(b)) * 16777619;
+  }
+  return h;
+};
+```
+
+```ts nish:err NL2231
+const bad = (a: i32, b: i64): i64 => {
+  return a + b;
+};
+```
+
+```ts nish:ok
+const good = (a: i32, b: i64): i64 => {
+  return toI64(a) + b;
+};
+```
+
+**`integer<Lo, Hi>` is an `i32` that stays in `[Lo, Hi]`.** The bounds are two
+integer literals (a sign allowed) inside `i32`, and it is an `i32` everywhere
+the machine can see. Putting a value *into* one is checked: an `i32` or
+another range is compared once and the program panics (exit 1) outside the
+range, a literal outside it is a compile error, and a literal inside it or a
+narrower range costs nothing. So does a value a loop condition or a guard
+already bounds (`b` below), and `toI32` of a `u8`; a check left inside a loop
+is a performance warning (NL9013) naming the guard that removes it. A range
+bounds an index too: `integer<0, 255>`, like `u8`, needs only a length guard of
+256. Taking one *out* is free: every operator reads
+it as `i32`, a `const` keeps the range and a `let` widens to `i32`. A `u8` is
+not an `integer<0, 255>` (convert with `toI32`), and a `declare function` may
+not mention a range. Put the range on the value you use, not on a loop
+counter, which has to leave the range to end the loop.
+
+```ts nish:ok
+const getByte = (buf: u8[], i: integer<0, 255>): u8 => buf[i];
+
+const sumAll = (buf: u8[]): i32 => {
+  let sum = 0;
+  for (let i = 0; i < 256 && i < buf.length; i++) {
+    const b: integer<0, 255> = i;
+    sum = sum + toI32(getByte(buf, b));
+  }
+  return sum;
+};
+```
+
+```ts nish:err-body NL2384
+const digit: integer<0, 9> = 12;
+```
+
+Declaring a type alias, enum, class, interface or function named `integer` is
+refused, because the name is the type. A value named `integer` (a local or a
+module constant) is fine.
+
+```ts nish:err NL2332
+class integer {
+  value: i32 = 0;
+}
+```
+
+### Numeric literals take their type from the immediate context
+
+A literal is the mode's default (`i32`, or `f64` in f64 mode) **unless its
+immediate context demands another numeric type**, and the contexts that do are
+a closed list: an annotated initializer, a `return`, an argument to a user
+*function* or to a constructor, the other operand of a binary operator whose
+type is already known, `Math.min` / `Math.max`, the f64-only `Math.*` and
+`toF64` / `toF32`, `process.exit`, `Number`, an element of an array literal
+that itself has a `T[]` context, a class field's literal initializer, a field
+or element assignment target, a ternary arm taking the conditional's own
+context, and `push` / `indexOf` through a receiver that is a **plain name**.
+
+Everything else leaves the literal at the default, however obvious the intent.
+The three that catch you out: an **object-literal property**, a `Result`
+payload, and a **method's** argument.
+
+```ts nish:err NL2269
+interface Pixel { r: u8; g: u8; b: u8; }
+
+export const main = (): i32 => {
+  const p: Pixel = { r: 255, g: 0, b: 0 };
+  console.log(`${p.r}`);
+  return 0;
+};
+```
+
+```ts nish:ok
+interface Pixel { r: u8; g: u8; b: u8; }
+
+export const main = (): i32 => {
+  const p: Pixel = { r: toU8(255), g: toU8(0), b: toU8(0) };
+  console.log(`${p.r}`);
+  return 0;
+};
+```
+
+The same rule refuses `const b: u8 = 1 + 2` — that is a sum of two `i32`
+literals, not a literal in a `u8` context. Name the value first, or convert.
+
+## Failure: `Result`, not exceptions
+
+There is no `throw`, no `try`, and no unwinding anywhere in the language. A
+function that can fail says so in its return type.
+
+```ts nish:ok
+const half = (n: i32): Result<i32, string> => {
+  if (n % 2 !== 0) {
+    return Err("odd");
+  }
+  return Ok(n / 2);
+};
+
+const quarter = (n: i32): Result<i32, string> => {
+  const h = half(n).orReturn();   // Rust's `?`: propagates the error
+  return half(h);
+};
+
+export const main = (): i32 => {
+  const outcome = quarter(8);
+  if (outcome.isErr()) {
+    console.error(outcome.error);
+    return 1;
+  }
+  console.log(`${outcome.value}`);
+  return 0;
+};
+```
+
+The surface: `Ok(v)` / `Ok()`, `Err(e)`, `r.isOk()`, `r.isErr()`, `r.ok`,
+`r.value`, `r.error`, `r.orReturn()`, `r.unwrapOr(d)`, `r.expect(msg)`. There
+is deliberately no `unwrap()` — `expect` insists on a reason — and no
+`map`/`andThen`, which would need function values.
+
+**Three rules, and they are the ones that catch you out:**
+
+1. **A `Result` cannot be dropped.** A call answering one may not stand as an
+   expression statement, and a local holding one must be read at least once.
+   Passing it on — as an argument, as a `return` — counts as reading it.
+2. **The error arm comes first.** `r.value` is legal only where the checker
+   proved `isOk()`; `r.error` only where it proved `isErr()`. There is no
+   spelling that reaches the success payload without deciding what happens to
+   the failure.
+3. **Propagation is contagious.** `r.orReturn()` is legal only inside a
+   function that itself returns a `Result` whose error arm accepts `E`. There
+   is no implicit error conversion — convert by hand with
+   `if (r.isErr()) { return Err(…); }`.
+
+```ts nish:err NL2044
+const half = (n: i32): Result<i32, string> => {
+  return Ok(n / 2);
+};
+
+export const main = (): i32 => {
+  const r = half(8);
+  console.log(`${r.value}`);
+  return 0;
+};
+```
+
+Narrowing follows the same engine as `T | null` below: it applies to a
+**variable**, never a property path; it ends at any assignment to that
+variable; and it is dropped before a loop that assigns it. `if (r.isOk()) A
+else B` narrows in `A`, and after the `if` when `B` cannot fall through.
+The proof stays with `r`: `const y = r`, `c ? r : q` and `[r]` are plain
+`Result`s, so test `y` itself before `y.value`.
+
+`panic(message)` is the other ending: message to stderr, exit 1. It is for an
+invariant that cannot hold, not for a failure a caller should handle. It
+terminates control flow, so a non-`void` function may end with it.
+
+## Absence: nullable types
+
+`T | null` is available for `T` a class, interface, array, or string — never a
+scalar, which has no null value. It is the same pointer with `null` as one more
+value, so nothing is boxed.
+
+```ts nish:ok
+class Node {
+  value: i32;
+  next: Node | null = null;
+  constructor(value: i32) {
+    this.value = value;
+  }
+}
+
+const total = (head: Node | null): i32 => {
+  let sum = 0;
+  let cur = head;
+  while (cur !== null) {
+    sum = sum + cur.value;
+    cur = cur.next;
+  }
+  return sum;
+};
+
+export const main = (): i32 => {
+  const a = new Node(1);
+  a.next = new Node(2);
+  console.log(`${total(a)}`);
+  return 0;
+};
+```
+
+- Reading anything off an un-narrowed nullable is an error: narrow with
+  `!== null` first, or read it through a `?.` chain that ends in `??`.
+- `a ?? d` defaults a nullable: it is `a` where that is not `null`, `d` where
+  it is, and its type is `T` when `d` is a `T`, so it needs no narrowing. It
+  reads `a` once, so a property path works: `cur = cur.next ?? cur`. `d` that
+  may be `null` keeps the `T | null`. An element read (`xs[i] ?? d`) is
+  refused, because Node answers `d` past the end where Nish panics. `??` also
+  defaults a `Map.get` result (see [Map and Set](#map-and-set)).
+
+```ts nish:ok
+class Node {
+  value: i32;
+  next: Node | null = null;
+  constructor(value: i32) {
+    this.value = value;
+  }
+}
+
+const label = (name: string | null): string => name ?? "anonymous";
+
+export const main = (): i32 => {
+  const a = new Node(1);
+  const after = a.next ?? a;     // `Node`, no narrowing needed
+  console.log(`${label(null)} ${after.value}`);   // anonymous 1
+  return 0;
+};
+```
+
+```ts nish:err-body NL2489
+const names = new Array<string | null>(2);
+console.log(names[2] ?? "none");
+```
+
+- `a?.b?.c ?? d` reads each link only where the receiver before its `?.` is
+  not `null`, and is `d` where one is. A `?.` is allowed **only in a chain
+  that is the left operand of `??`** (NL1062): `const x = a?.b`, `f(a?.b)` and
+  `` `${a?.b}` `` are refused, because on its own a chain answers
+  `undefined`. The last link may be any type, a number included
+  (`o?.next?.id ?? -1` is an `i32`), and a method call is a link
+  (`c?.greeting() ?? ""`). Only a `?.` skips: `a?.next.v` with a nullable
+  `next` needs `a?.next?.v`. `?.` on something that cannot be `null` is
+  NL2490; `?.[i]` and `f?.()` are refused.
+
+```ts nish:ok
+class Order {
+  id: i32;
+  next: Order | null = null;
+  constructor(id: i32) {
+    this.id = id;
+  }
+}
+
+const nextId = (o: Order | null): i32 => o?.next?.id ?? -1;
+
+export const main = (): i32 => {
+  const a = new Order(1);
+  a.next = new Order(2);
+  console.log(`${nextId(a)} ${nextId(null)}`);   // 2 -1
+  return 0;
+};
+```
+
+```ts nish:err-body NL1062
+const s: string | null = "x";
+const n = s?.length;
+```
+- Narrowing applies to a **local or parameter**, never a property path. `if
+  (n.next !== null) n.next.v` is rejected — copy into a local first.
+- A narrowing ends at any assignment to the variable, including one in an
+  earlier operand of the same `&&` / `||` chain, and is dropped before a loop
+  whose body, condition or update assigns it.
+- Two nullables cannot be compared with each other; compare each with `null`.
+- `new Array<T | null>(n)` is allowed: the zero fill *is* `null`.
+
+## Declarations
+
+### Functions
+
+```ts nish:ok
+const add = (a: i32, b: i32): i32 => {
+  return a + b;
+};
+
+const double = (n: i32): i32 => n * 2;   // a concise body is that one `return`
+```
+
+- A function is a **module-level `const` bound to an arrow**. `let` is
+  rejected; annotating the `const` is rejected (the annotation would be a
+  function type, which only a parameter may have). The `function` keyword is
+  accepted as the legacy spelling and compiles to identical IR.
+- **Every parameter and the return type must be annotated.**
+- **A function is not a value.** `const alias = double` is
+  `` Unknown identifier `double` ``. A function may be *passed* only for a
+  function-typed parameter, where it is resolved at compile time — see
+  [Function parameters](#function-parameters) — and never stored, returned or
+  held in a field, a local or an array.
+- **Parameters are immutable**: `p = 1`, `p++`, `p += 1` are all rejected. Copy
+  into a `let` first.
+- A non-`void` function must return on every path.
+- Rejected: generators, `async`, destructured / rest / optional / default
+  parameters, overloads, nested function declarations. Type parameters *are*
+  allowed — see [Generic functions](#generic-functions).
+
+### Generic functions
+
+A function may declare type parameters, and **each instantiation is compiled to
+its own specialised function** — no boxing, no dictionary, no runtime type
+information. The IR is what somebody would have written by hand at that type.
+
+```ts nish:ok
+const identity = <T>(x: T): T => x;
+
+export const main = (): i32 => {
+  console.log(identity(7));
+  console.log(identity("hi"));
+  return 0;
+};
+```
+
+- **The type argument is inferred from the arguments and is never written at a
+  call site.** `identity<i32>(7)` is
+  `Type arguments are not written at a call site in Nish`. Inference matches the
+  shape of each declared parameter against its argument — `T` against `i32`,
+  `T[]` against `i32[]`, `Result<T, string>` against `Result<i32, string>` —
+  left to right, first binding wins.
+- **A type parameter that appears in no parameter is an error at the
+  declaration**, because it could never be inferred.
+- **Every other rule still applies inside.** A type parameter is not a hole to
+  smuggle something through: each instantiation is checked with `T` bound to a
+  concrete type.
+- **A template may be exported and instantiated from another module.** Each
+  instantiation is defined once, in the module that declares the template, and
+  `declare`d everywhere else — so one imported name becomes one symbol per
+  distinct type-argument tuple, and two modules asking for the same tuple share
+  the one definition. A type argument may be a class the declaring module has
+  never heard of. A template that is not exported cannot be imported, and an
+  imported one may be renamed (`import { identity as id }`) without moving the
+  symbol. A type-argument list on an imported name that is *not* a template is
+  `` `Point` in `./lib` takes no type arguments ``.
+- **A type parameter has no members unless it is constrained.** Passing a `T`
+  on, returning it, storing it and comparing it are fine; `p.x`, `p.x = 1` and
+  `p.m()` through a `T` are `` Cannot read `x` of `T`: an unconstrained type
+  parameter has no members ``, even when every call passes a type with an `x`.
+  It is where the value came from that counts — a local copied from a `T`, an
+  element of a `T[]` and a narrowed `T | null` are all a `T` — never its type.
+
+```ts nish:err NL2329
+interface Point { x: i32; y: i32; }
+
+const getX = <T>(p: T): i32 => p.x;
+
+export const main = (): i32 => {
+  const p: Point = { x: 1, y: 2 };
+  return getX(p);
+};
+```
+
+- **`<T extends Shape>` gives `T` exactly `Shape`'s members**: its fields, and
+  its methods when `Shape` is a class. A constraint is a declared class or
+  interface (or `Container<i32>`, with its arguments written out) — never a
+  scalar, `string`, an array or another type parameter. Each instantiation still
+  reads its own struct directly, with no vtable.
+- **A type argument must satisfy the constraint**: be `Shape` itself, or a
+  class that declares `implements Shape`. Matching field names are not enough.
+  A class constraint is satisfied by that class alone. The refusal is at the
+  call: `` `T` of `areaOf` requires `T extends Shape`, and `i32` does not
+  implement it ``.
+- **A constraint is a declaration, not a name.** A `Shape` your module declares
+  is not the `Shape` another module's `<T extends Shape>` names, even with the
+  same fields, so implementing your own is refused the same way; import the
+  template's `Shape` instead.
+
+```ts nish:ok
+interface Shape { area: i32; }
+
+class Circle implements Shape {
+  area: i32;
+  radius: i32;
+  constructor(r: i32) { this.area = 3 * r * r; this.radius = r; }
+}
+
+const areaOf = <T extends Shape>(s: T): i32 => s.area;   // s.radius would be refused
+
+export const main = (): i32 => areaOf(new Circle(2)) - 12;
+```
+
+- **Each type parameter is named once**: `<T, T>` is
+  `` Duplicate type parameter `T` ``, on a function, method, class or
+  interface, and in a template nothing calls too.
+- **Not supported yet**: a default type argument (`<T = string>`) and type
+  parameters on a **constructor**, each with its own message, and a generic
+  **type alias**, which is only the syntax error `` expected `=`, found `<` ``.
+  A generic `main` is refused. There are no multiple bounds (`T extends A & B`)
+  and no bound that mentions another parameter.
+- **`$` may not appear in a function, class or interface name** — it is what
+  separates a generic's name from its type arguments in the emitted symbol.
+- **Read `identity<i32>` in a message, `identity$i32` in the IR.** Diagnostics,
+  `--emit-checked` and the `-g` debug names spell an instantiation as written
+  (`identity<Box<i32>>`, `Box<i32>.get`); symbols and `%struct` names are
+  mangled (`@identity$$Box$i32`, `%struct.Box$i32`).
+- **A host calls an exported instantiation as `nish_gen_…`**: `identity<i32>`
+  is `nish_gen_identity_i32` in the C header, the `.d.ts`, the wasm loader and
+  the N-API addon, and `identity<i32[]>` is `nish_gen_identity_arr_i32`. There
+  is no `identity` to call — only the instantiations the program makes.
+- **With a sidecar flag, an exported generic must be instantiated.** Nothing
+  instantiated means no symbol, so `--emit-header`, `--emit-dts` and
+  `--emit-napi` refuse it (NL4007) rather than leave it out; call it somewhere,
+  or do not export it. The same flags refuse two names that are one C
+  identifier, such as a method `Point.shifted` and a function `Point_shifted`
+  (NL4008).
+
+```ts nish:err NL4007 --emit-dts build/docs-ai/nl4007.d.ts
+export const identity = <T>(x: T): T => x;   // exported, never called
+
+export const main = (): i32 => 0;
+```
+
+### Generic classes and interfaces
+
+A `class` or an `interface` may take type parameters too, and an instantiation
+is **an ordinary struct**: `Box<i32>` is `%struct.Box$i32` with `Box`'s fields
+at `T = i32`, and everything the language does to a struct works on it.
+
+```ts nish:ok
+class Box<T> {
+  value: T;
+  constructor(v: T) { this.value = v; }
+  get(): T { return this.value; }
+}
+
+interface Pair<A, B> { first: A; second: B; }
+
+export const main = (): i32 => {
+  const b = new Box<i32>(7);
+  const p: Pair<i32, string> = { first: 1, second: "hi" };
+  console.log(p.second);
+  return b.get();
+};
+```
+
+- **Write the type arguments out.** `Box` on its own is not a type — there is
+  no layout until `T` is bound — so it is `` `Box` is generic: it must be
+  written with its type arguments ``. The two positions that take them are an
+  annotation (`const b: Box<i32>`) and `new` (`new Box<i32>(7)`); a *call*
+  infers instead. A class that is not generic takes none.
+- **A type argument may be anything a type may be**, including another
+  instantiation: `Box<Point>`, `Box<Box<i32>>`, `Box<i32[]>`,
+  `Box<Result<i32, string>>`.
+- **`implements` may name an instantiation**: `class Box<T> implements
+  Container<T>` is checked per instantiation by the usual field-prefix rule.
+- **A field may not grow its own type argument.** `class Nest<T> { inner:
+  Nest<T[]> | null }` is `` Monomorphising `Nest` would not terminate ``;
+  `Nest<T>` and a type that mentions no parameter are both fine.
+- **A type parameter takes no type arguments of its own.** `T` is whatever the
+  instantiation bound it to, so `const y: T<i32>` is
+  `` Unsupported type reference `T<i32>` ``.
+- **A template obeys every rule a declared class obeys**: `declare class
+  Box<T>`, `export default class Box<T>`, `abstract class Box<T>` and
+  `interface Box<T> extends Base` are refused in the words their non-generic
+  spellings are refused in.
+- **A template claims its name.** `class Box<T>` is a declaration of `Box`, so
+  a function, constant, alias, enum or second class of that name is refused
+  whichever was written first: `` `Box` is already declared in this module ``,
+  or `` Duplicate declaration of `Box` `` for a second class.
+- **Two modules may not both declare a generic class of one name** once both
+  instantiate it: `%struct.Box$i32` is program-wide, so
+  `` Generic class `Holder` is also declared in helper.ts ``.
+- **A generic class or interface may be imported**, and the rule is a generic
+  function's: `%struct.Box$i32` and every `@Box$i32.*` symbol are defined once,
+  by the module that declares `Box<T>`, and `declare`d by every module that
+  holds one. Unlike a declared class it may be renamed on import, because the
+  name that crosses the ABI is the template's. Named without its type arguments
+  it is `` `Crate` is generic: it must be written with its type arguments ``.
+- **A class or interface may constrain its parameters** — `class Holder<T
+  extends Shape>` — by the rules a function's follow: its methods may read
+  `this.item.area` through a field of type `T`, and `new Holder<Point>` or an
+  annotation `Holder<Point>` is refused unless `Point` satisfies `Shape`.
+
+### Generic methods
+
+A method — of a generic class or not — may declare its own type parameters.
+They are inferred from the arguments like a generic function's, and each
+(receiver, method type arguments) pair is its own `define`:
+`@Chooser.pick$i32`, `@Box$i32.keep$str`.
+
+```ts nish:ok
+class Chooser {
+  flip: boolean = false;
+  pick<T>(a: T, b: T): T { return this.flip ? b : a; }
+}
+
+class Box<T> {
+  value: T;
+  constructor(v: T) { this.value = v; }
+  keep<U>(other: U): T { return this.value; }
+}
+
+export const main = (): i32 => {
+  const c = new Chooser();
+  const word: string = c.pick("left", "right");
+  console.log(word);
+  return c.pick(0, 1) + new Box<i32>(7).keep("seven") - 7;
+};
+```
+
+- **Never write the type arguments at the call**: `c.pick<i32>(1, 2)` is
+  `` Type arguments are not written at a call site ``. A method type parameter
+  that no parameter mentions is `` Cannot infer `U` for `Holder.make` ``.
+- **Do not reuse a class parameter's name**: `class Box<T> { map<T>(…) }` is
+  `` Type parameter `T` of `Box.map` shadows `Box`'s own `T` `` (NL2331) —
+  call the method's `U`.
+- **Constrain it like a function's** — `apply<U extends Shape>(u: U)` reads
+  `u.area` — but the constraint may not mention a type parameter, the class's
+  included.
+- **A constructor takes none**; its class's are written after `new`.
+
+```ts nish:err NL2331
+class Box<T> {
+  value: T;
+  constructor(v: T) { this.value = v; }
+  map<T>(other: T): T { return other; }   // shadows Box's T: call it U
+}
+
+export const main = (): i32 => new Box<i32>(1).value;
+```
+
+### Function parameters
+
+A parameter of a top-level function may have a **function type**. Its argument
+is a top-level function named at the call, or an arrow written right there, and
+each one is compiled into its **own copy** of the function, with a direct call
+where the parameter is called — there is no function pointer at run time.
+
+```ts nish:ok
+const map = <T, U>(xs: T[], f: (x: T) => U): U[] => {
+  const out: U[] = [];
+  for (const x of xs) {
+    out.push(f(x));
+  }
+  return out;
+};
+
+const fold = <T>(xs: T[], f: (acc: T, x: T) => T, identity: T): T => {
+  let acc = identity;
+  for (const x of xs) {
+    acc = f(acc, x);
+  }
+  return acc;
+};
+
+const add = (a: i32, b: i32): i32 => a + b;
+
+export const main = (): i32 => {
+  const doubled = map([1, 2, 3], (n) => n * 2);   // U is bound from the body
+  return fold(doubled, add, 0) - 12;              // 0
+};
+```
+
+- **Call it, or pass it on to another function parameter. Nothing else**:
+  `const g = f`, `return f` and `[f]` are
+  `` `f` is a function parameter and can only be called or passed on as a function argument ``.
+- **An arrow captures nothing.** It sees its own parameters and top-level
+  names; reading a local of the function around it is
+  `` The arrow reads `k`, which belongs to the function it is written in ``.
+  Pass the value in as another argument of the template instead.
+- **The argument's type must match exactly**: `(x: i32) => i64` for a
+  `(x: i32) => i32` parameter is refused. A generic function cannot be passed
+  by name — write `(x) => identity(x)`.
+- **Annotate what cannot be inferred**: an arrow parameter whose type no value
+  argument binds, and the return type of a block-bodied arrow whose result is a
+  type parameter.
+- **Only a top-level function** may have one: not a method, a constructor, a
+  field, a local, a return type or an alias.
+
+```ts nish:err NL2335
+const apply = (f: (x: i32) => i32, x: i32): i32 => f(x);
+
+export const main = (): i32 => {
+  const k = 3;
+  return apply((x) => x + k, 1);   // captures `k`: pass it to `apply` instead
+};
+```
+
+### Data parallelism: `nish/threads`
+
+`parallelMapInto(src, dst, f)` writes `f(src[i])` into `dst[i]`, and
+`parallelReduce(src, f, identity)` folds `src` with `f` — each on as many
+threads as the array is long enough for. `f` is a [function parameter](#function-parameters).
+Importing the module compiles the program with `--threads`; there is nothing
+else to switch on and no thread count to choose. `parallelMap(src, f)` and
+`parallelFrom(n, f)` answer a new array instead (`f(src[i])`, `f(i)`), under
+the same rules for `f`.
+
+```ts nish:ok
+import { parallelMapInto, parallelReduce } from "nish/threads";
+
+const square = (x: f64): f64 => x * x;
+
+export const main = (): i32 => {
+  const src: f64[] = [1.0, 2.0, 3.0];
+  const dst: f64[] = [0.0, 0.0, 0.0];                        // at least src.length, or it panics
+  parallelMapInto(src, dst, square);
+  const total = parallelReduce(dst, (a, b) => a + b, 0.0);   // 14, the same bits on any core count
+  return toI32(total);
+};
+```
+
+```ts nish:ok
+import { parallelFrom, parallelMap } from "nish/threads";
+
+export const main = (): i32 => {
+  const names = parallelFrom(3, (i) => `w${i}`);    // each string copied out at the join
+  const lens = parallelMap(names, (n) => n.length); // 2 2 2
+  console.log(`${names[2]} ${lens[0]}`);            // w2 2
+  return 0;
+};
+```
+
+- **`f` writes nothing its caller can see.** No field or element store
+  through its argument and no `console.log` — each is refused at the call,
+  naming the write (NL2345): answer the value and write after the call. An
+  arrow may read the `const` locals and parameters around it, never write
+  them (NL2503: answer the value from the body instead, and fold the answers with `parallelReduce`,
+  `const sumTotal = parallelReduce(xs, (a, b) => a + b, 0)`, or read them from the array the call
+  gives back, `const kValues = parallelMap(xs, (x): i32 => x)`)
+  and never read a `let` (NL2500: snapshot it first, `const kNow = k`). Reading is fine; so are a bounds check, an integer
+  division and `panic`.
+- **What `f` allocates is freed after every element.** A string, array or
+  object built on the way to the result compiles, with performance warning
+  NL9012: each element pays for building it and for the release. Storing an
+  allocation into another object (NL2352) and touching `Arena` (NL2351) are
+  refused, because either would make that release unsound.
+- **A map's result is a number, a `boolean`, an enum, a `string` or an array
+  of numbers, booleans or enums**: a string or a scalar array is copied out of
+  the worker's arena at the join. An array of strings, a nested array, a class,
+  a `Map` or a `Set` is refused (NL2348): answer a string or a number per
+  element and build the structure after the call. **A reduce's `T` stays a number, a
+  `boolean` or an enum**: map strings to numbers first.
+- **`dst` may not be reachable from an element of `src`**: mapping `Row[]` into
+  `f64[]` is refused when `Row` holds an `f64[]`, because it could be `dst`.
+- **A reduce's `f` is associative and `identity` is its identity** — `0` for
+  `+`, `1` for `*`. The array is folded in fixed blocks and the blocks combined
+  in order, so `-` or a wrong identity is refused when `f` is an arrow of one
+  operator; a named function is trusted.
+- A short array runs on the calling thread at the cost of the loop, so there
+  is no reason to guard a call by size. How short is sized from what `f`
+  costs: a body estimated at 3, such as `(x) => x + 1`, is divided only past
+  about 700,000 elements, a cheaper one later, one with a loop far sooner.
+
+```ts nish:err NL2350
+import { parallelReduce } from "nish/threads";
+
+export const main = (): i32 => parallelReduce([1, 2, 3], (a, b) => a + b, 1);   // `+` folds from 0
+```
+
+### Scoped tasks: `using s = scope()`
+
+Different functions at once, one thread each: open a scope with `using`, give
+it tasks with `spawn(entry, arg, dst, at)`, and every task has run and stored
+`entry(arg)` into `dst[at]` when the block ends.
+
+```ts nish:ok
+import { scope } from "nish/threads";
+
+const sumOf = (xs: f64[]): f64 => xs[0] + xs[1];
+const square = (n: i32): i32 => n * n;
+
+export const main = (): i32 => {
+  const xs: f64[] = [1.5, 2.5];
+  const sums: f64[] = [0.0];
+  const squares: i32[] = [0];
+  {
+    using s = scope();
+    s.spawn(sumOf, xs, sums, 0);
+    s.spawn(square, 12, squares, 0);
+  }                                          // joined here, on every exit
+  console.log(`${sums[0]} ${squares[0]}`);   // 4 144
+  return 0;
+};
+```
+
+- **The tasks run when the block ends**, together, and each answer is stored
+  after the last one finishes. So read a destination after the block. A
+  destination is a `const` bound to a fresh array (`[0, 0]`, `new Array`) that
+  you only index; never pass it on. Between the first `spawn` and the block's
+  end, don't read a destination, and don't write memory a task could read (a
+  store into an argument, a call that writes through its argument).
+- **`using` takes only `scope()`**, a `Mutex`'s `lock()` (below), or `arena()`
+  (under [Memory](#memory)), and `scope()` only comes from `using`
+  (NL2388): `using s = scope()`.
+  The scope is only ever the receiver of a `spawn` statement: never pass it,
+  store it or return it.
+- **The task is a top-level function named in the `spawn`, or an arrow written
+  there.** `s.spawn(entry, arg)` with no destination runs an entry that
+  answers `void`; `s.spawn(() => work(a, b))` runs an arrow that reads the
+  `const` locals and parameters around it (never a `let` or `this` (NL2506):
+  bind a `const` first, `const kNow = k`) and answers `void`. An entry that
+  answers a value has a destination (NL2511): `const answer = new Array<i32>(1)`
+  above the scope and `s.spawn(entry, arg, answer, 0)`. Either follows the
+  data-parallel rules: it writes nothing anybody else can see but what it
+  writes through a `Mutex`'s guard or sends on a `Channel` (below), answers a number,
+  a `boolean`, an enum, a `string` or an array of numbers, booleans or enums
+  (copied out of its arena at the join), and leaves `Arena` alone. A task cannot open a scope
+  of its own or call `parallelMapInto`.
+- **Any argument will do** — an array, an object — because nothing writes
+  memory while the tasks run. There is no thread count: one task, one thread.
+
+```ts nish:err NL2388
+import { scope } from "nish/threads";
+
+const one = (n: i32): i32 => n + 1;
+
+export const main = (): i32 => {
+  const out: i32[] = [0];
+  const s = scope();   // a scope must be introduced by `using`
+  s.spawn(one, 1, out, 0);
+  return out[0];
+};
+```
+
+### Sharing a value between tasks: `Mutex<T>`
+
+When tasks must update one value, put it in a `Mutex` and reach it only through
+`using g = m.lock()`: the lock is held until that block ends, on every exit.
+
+```ts nish:ok
+import { Mutex, scope } from "nish/threads";
+
+class Tally {
+  bins: i32[];
+  constructor() {
+    this.bins = [0, 0, 0, 0];
+  }
+}
+
+class Shard {
+  xs: i32[];
+  tally: Mutex<Tally>;
+  constructor(xs: i32[], tally: Mutex<Tally>) {
+    this.xs = xs;
+    this.tally = tally;
+  }
+}
+
+const binAll = (s: Shard): i32 => {
+  for (const x of s.xs) {
+    const bin: i32 = x & 3;
+    using g = s.tally.lock();                  // held to the end of this pass
+    g.value.bins[bin] = g.value.bins[bin] + 1;
+  }
+  return 0;
+};
+
+export const main = (): i32 => {
+  const tally = new Mutex<Tally>(new Tally()); // a fresh value: `new` or a literal
+  const done: i32[] = [0, 0];
+  {
+    using s = scope();
+    s.spawn(binAll, new Shard([1, 2, 3], tally), done, 0);
+    s.spawn(binAll, new Shard([4, 5, 6], tally), done, 1);
+  }
+  using g = tally.lock();                      // after the join: lock freely
+  console.log(`${g.value.bins[1]}`);           // 2
+  return 0;
+};
+```
+
+- **Only `g.value`, and only as the base of a field or element access.** Read
+  a number, a `boolean`, an enum or a `string` through it, or store one into a
+  field or an element that already exists (a string is copied each way) (for a `Mutex<i32>`, `g.value = g.value + 1`).
+  Don't bind, store, return or walk `g` itself (NL2466), nor bind, store, return
+  or walk `g.value` or an array it holds (NL2467); store only a scalar or a
+  `string` into it (NL2468), never `null` (NL2537), and call no method
+  through it (no `push`).
+- **A guard goes only to a helper**: a top-level function named at the call,
+  whose parameter is `MutexGuard<T>`, once per call — `note(g, x)` with
+  `const note = (g: MutexGuard<Stats>, x: i32): void => { … }`. The helper is
+  held to the block's rules. A method, a constructor or a generic is refused
+  (NL2536): `this` or `T` would be a way to keep the guard.
+- **Make the data fresh all the way down**: `new Mutex<Hist>(new Hist())`, not
+  `new Hist(bins)` with a `bins` you still hold.
+- **`lock()` only as `using g = m.lock()`** (NL2465), one lock per `using`. The lock is
+  released at every exit of the block, and at a `return` after the returned
+  value is computed, so `return g.value.n` reads under the lock.
+- **One lock at a time, and no waiting while it is held**: inside the guard's
+  block, directly or through any call or `new`, no second `lock()`, no
+  `scope()` or `spawn`, no `parallelMapInto` or `parallelReduce`. So a program
+  cannot deadlock.
+- **Only a scope's tasks and the thread that opened it lock**: the function
+  given to `parallelMapInto` or `parallelReduce` takes no lock, even through a
+  call (NL2474).
+- **A `Mutex` reaches a task as its argument or a field of its argument's
+  class** — not in an array. From the statement holding a scope's first
+  `spawn` to its block's end the parent doesn't lock what the tasks share,
+  even through a call; before and after, it may.
+- **Make the updates commute exactly** (an integer sum or count, a histogram;
+  not an `f64` sum): the critical sections run in the scheduler's order
+  natively and in spawn order under Node.
+
+```ts nish:err NL2467
+import { Mutex } from "nish/threads";
+
+class Counter {
+  n: i32 = 0;
+}
+
+export const main = (): i32 => {
+  const m = new Mutex<Counter>(new Counter());
+  using g = m.lock();
+  const c = g.value;   // what the guard reaches would outlive the lock
+  return c.n;
+};
+```
+
+```ts nish:ok
+import { Mutex, MutexGuard } from "nish/threads";
+
+class Stats {
+  count: i32 = 0;
+}
+
+const bump = (g: MutexGuard<Stats>): void => {
+  g.value.count = g.value.count + 1;   // a helper: the block's rules, the block's lock
+};
+
+export const main = (): i32 => {
+  const m = new Mutex<Stats>(new Stats());
+  using g = m.lock();
+  bump(g);
+  return g.value.count - 1;            // 0
+};
+```
+
+### Counters without a lock: `AtomicI32` and `AtomicI64`
+
+A shared counter, minimum, maximum or flag is an atomic: `new AtomicI32(0)`,
+`new AtomicI64(toI64(0))`, updated from any task or parallel `f` by one
+indivisible method call.
+
+```ts nish:ok
+import { AtomicI32, parallelMapInto } from "nish/threads";
+
+export const main = (): i32 => {
+  const hits = new AtomicI32(0);
+  const top = new AtomicI32(0);
+  const xs: i32[] = [3, 9, 4];
+  const ys: i32[] = [0, 0, 0];
+  parallelMapInto(xs, ys, (x) => hits.add(1) + top.max(x)); // each answers the old value
+  console.log(`${hits.load()} ${top.load()}`);              // 3 9
+  return 0;
+};
+```
+
+- **Only its methods**: `load`, `store`, `add`, `sub`, `min`, `max`,
+  `exchange`, `compareExchange(expected, desired)`; each update answers the
+  value held just before it. No field to read.
+- **Not inside a scope's block after the first `spawn`** (NL2513): read it
+  before, or after the block. Two scopes of one `using` share no atomic
+  (NL2516): give each scope a block of its own, `{ using s = scope(); … }`
+  then `{ using t = scope(); … }`.
+- **Make the updates commute** — `add`, `sub`, `min`, `max` — or native and
+  Node differ.
+- **Add once per batch**: count into a local array, then one `add` per bin.
+  One `add` per value makes the cores wait on each other.
+- **`AtomicI64` takes `i64` values**, exact under Node within ±2^53.
+
+```ts nish:err NL2513
+import { AtomicI32, scope } from "nish/threads";
+
+const bump = (a: AtomicI32): i32 => a.add(1);
+
+export const main = (): i32 => {
+  const a = new AtomicI32(0);
+  const done: i32[] = [0];
+  let seen: i32 = 0;
+  {
+    using s = scope();
+    s.spawn(bump, a, done, 0);
+    seen = a.load();   // the task may not have run yet
+  }
+  return seen;
+};
+```
+
+### Passing values between tasks: `Channel<T>`
+
+When one task produces values and another consumes them, give both a
+`Channel`: the producers `send`, and the consumer walks the channel with
+`for...of`, which waits for values and ends once every producer has returned.
+Nobody closes a channel.
+
+```ts nish:ok
+import { Channel, scope } from "nish/threads";
+
+class Pipe {
+  ch: Channel<i32>;
+  n: i32;
+  constructor(ch: Channel<i32>, n: i32) {
+    this.ch = ch;
+    this.n = n;
+  }
+}
+
+const produce = (p: Pipe): i32 => {
+  for (let i: i32 = 1; i <= p.n; i++) {
+    p.ch.send(i);                                 // never waits
+  }
+  return p.n;
+};
+
+const consume = (p: Pipe): i32 => {
+  let sum: i32 = 0;
+  for (const x of p.ch) {                         // ends once every sender has returned
+    sum = sum + x;
+  }
+  return sum;
+};
+
+export const main = (): i32 => {
+  const sent: i32[] = [0, 0];
+  const sums: i32[] = [0];
+  const ch = new Channel<i32>();                  // a `const`, right before its scope
+  {
+    using s = scope();
+    s.spawn(produce, new Pipe(ch, 10), sent, 0);  // every sender first
+    s.spawn(produce, new Pipe(ch, 20), sent, 1);
+    s.spawn(consume, new Pipe(ch, 0), sums, 0);   // then the one receiver
+  }
+  console.log(`${sums[0]}`);                      // 265
+  return 0;
+};
+```
+
+- **It carries a number, a `boolean`, an enum or a `string`** (copied in by
+  `send`, out by the receive), never an array or an object.
+- **Declare it as a `const` right before its scope** — in the block that holds
+  `using s = scope()`, or in the block around the scope's block — and hand it
+  to tasks only as the task's argument or a field of the object you build for
+  it in the `spawn` (`new Pipe(ch, 10)`). Don't bind it to another name, store
+  it, return it, or name any member but `send`. Passing it to a function
+  whose parameter is declared `Channel<T>` is fine; pushing it onto an array,
+  putting it in a `Map`, or passing it as a generic's `T` is not. A `spawn`
+  hands a task only a channel the function itself declared, never one the
+  function was handed, and no task gets one channel in two fields. Hold it
+  only as `Channel<T>` (no `| null`, no `Channel<T>[]`, no `Map` of them), and
+  use it only in a top-level function's body, never inside an arrow
+  (NL2484): write the task as a module function,
+  `const sendAll = (ch: Channel<i32>): void => { … }`, and spawn that.
+  `new Channel<i32>()` takes no capacity: it is unbounded.
+- **One scope, one receiver.** Only one scope's tasks use a channel. Its one
+  receiver is either a single task spawned outside any loop, or the parent
+  after the scope's block; never both, never two. The parent sends only before
+  the scope's block, and receives nothing inside it.
+- **Senders before the receiver.** Spawn every task that may send before the
+  task that receives (NL2481: `s.spawn(produce, …)` above
+  `s.spawn(consume, …)`), and never let one task both send and receive on the
+  same channel. So channels cannot deadlock.
+- **No receive while a lock is held**, even through a call. A `send` under a
+  guard is fine.
+- **Print what the interleaving cannot change**: two senders' values arrive in
+  the scheduler's order natively and in spawn order under Node, so a count or an
+  integer sum prints the same both ways.
+
+```ts nish:err NL2481
+import { Channel, scope } from "nish/threads";
+
+const one = (ch: Channel<i32>): i32 => {
+  ch.send(1);
+  return 1;
+};
+
+const drain = (ch: Channel<i32>): i32 => {
+  let sum: i32 = 0;
+  for (const x of ch) {
+    sum = sum + x;
+  }
+  return sum;
+};
+
+export const main = (): i32 => {
+  const out: i32[] = [0, 0];
+  const ch = new Channel<i32>();
+  {
+    using s = scope();
+    s.spawn(drain, ch, out, 0);   // the receiver first: under Node it finds nothing
+    s.spawn(one, ch, out, 1);
+  }
+  return out[0];
+};
+```
+
+### What crosses between threads, and `nish --fix`
+
+- **Crosses, by copy:** a number, a `boolean`, an enum, a `string`, an array
+  of numbers, booleans or enums — a task's answer, a `parallelMap` element, a
+  `Channel<string>` value, a string stored through a guard. Each thread moves
+  the `parallelMap` elements it answers into blocks of its own, and the caller
+  takes the blocks whole at the join; a task's answer under 64 KB is copied in
+  by the joining thread. On one thread every element still pays the move, so
+  cheap work that answers strings can be slower there than sequential.
+- **Doesn't cross:** a class value, a nested array, a `string[]`, a `Map`, a
+  `Set`. Answer what it is built from, and build it after the join.
+- **`nish --fix` writes the usual repair**: `const` to `using` for a scope or a
+  guard (NL2388, NL2465), a destination for a number or `boolean` answer
+  (NL2511), a `const kNow = k` snapshot of a `let` an arrow reads (NL2506,
+  NL2500), and a channel arrow hoisted to a top-level `const` (NL2484). It
+  leaves to you a `spawn` in a loop, a `let` another argument names or a `for`
+  header declares, and a channel arrow that captures or leaves a parameter's or
+  its result's type out.
+- **Every thread refusal ends with the code to write**, in your names where
+  the compiler has them; the guide's
+  [refusal table](guide/using-nish/threads.md#refused-and-what-to-write-instead)
+  pairs each code with an example that compiles.
+
+```ts nish:err NL2506
+import { scope } from "nish/threads";
+
+export const main = (): i32 => {
+  let k: i32 = 3;
+  const out: i32[] = [0];
+  {
+    using s = scope();
+    s.spawn((n: i32): i32 => n + k, 1, out, 0);   // --fix: `const kNow = k;` above, the arrow reads `kNow`
+  }
+  return out[0];
+};
+```
+
+### Calling C
+
+`declare function name(params): T;` declares a C function this program calls but
+does not define. The symbol is the identifier, unmangled, in any package
+(a package's own functions are prefixed, its declarations are not), and the
+call is an ordinary call. Two declarations of one name must have the same
+types.
+
+```ts nish:ok
+declare function abs(n: i32): i32;
+
+export const main = (): i32 => {
+  console.log(`${abs(-5)}`);
+  return 0;
+};
+```
+
+- **A parameter is a scalar, a `CPtr`, a borrowed `string` or a `u8[]` buffer
+  with its count; a return is a scalar, a `CPtr` or a copied `string`.** The
+  scalars are the integer and float widths, `boolean` and `void`. Any other
+  array, a class or an interface is rejected, in either position.
+- **A run of `u8[]` / `readonly u8[]` parameters is followed by exactly one
+  `u64`**, the byte count C may touch in each (`memcpy(dst: u8[], src:
+  readonly u8[], n: u64)`). `readonly` is C's `const`. A run without its count
+  is NL2549, a count that is not `u64` NL2550, `i32[]` NL2551, `u8[] | null`
+  NL2552. Declare `fwrite` as `(buf: readonly u8[], n: u64, one: u64, f: CPtr)`
+  and pass `1` for `one`. A call passes the data pointer and first checks the
+  count against every buffer of the run: a larger count is an `ffi-length`
+  panic, and only `toU64(buf.length)` of the buffer itself is proved. C
+  borrows the bytes for the call and may write a `u8[]`; a spawned task may
+  not make the call.
+
+```ts nish:err NL2549
+declare function SHA256(d: readonly u8[], n: u64, md: u8[]): CPtr;
+
+export const main = (): i32 => {
+  return 0;
+};
+```
+
+- **A `string` parameter is lent for the call.** C gets a NUL-terminated
+  `const char *` that it may read until it returns, and may neither keep nor
+  write; a C function that does either is declared to take a `CPtr` instead.
+  `string | null` passes `NULL` for `null`. A string with a NUL byte in it
+  panics (`ffi-nul`) before the call, because C would read only up to it; a
+  literal with no NUL is not checked.
+
+```ts nish:ok
+declare function puts(s: string): i32;
+
+export const main = (): i32 => {
+  puts("hello");
+  return 0;
+};
+```
+
+- **A `string` result is copied out of C's `const char *`** into the arena at
+  the call, so it lives like any other string and C may reuse its buffer.
+  `string | null` maps `NULL` to `null`; a `string` result that comes back
+  `NULL` panics (`ffi-null`). The copy never frees: a result the caller must
+  `free` (`strdup`) is declared `CPtr | null` instead.
+
+```ts nish:ok
+declare function strerror(errnum: i32): string;
+declare function getenv(name: string): string | null;
+
+export const main = (): i32 => {
+  console.log(strerror(2));
+  const home = getenv("HOME");
+  console.log(home === null ? "unset" : "set");
+  return 0;
+};
+```
+
+- **A buffer C allocated is read with `readCString` from `nish:unsafe`, then
+  freed.** `readCString(p: CPtr): string` copies the NUL-terminated bytes at
+  `p` into a new string; a dangling or unterminated `p` is undefined
+  behaviour, which is why it needs the import. It takes a `CPtr`, so narrow a
+  `CPtr | null` with `!== null` first.
+- **A `CPtr | null` parameter takes the literal `null` or a narrowed pointer.**
+  `realpath(path, null)` passes `NULL`; a nullable pointer held in a variable
+  is NL2539, so C is never handed a `NULL` by accident.
+
+```ts nish:ok
+import { readCString } from "nish:unsafe";
+
+declare function realpath(path: string, resolved: CPtr | null): CPtr | null;
+declare function free(p: CPtr): void;
+
+export const main = (): i32 => {
+  const p = realpath(".", null);
+  if (p === null) {
+    return 1;
+  }
+  const dir = readCString(p);
+  free(p);
+  console.log(dir.startsWith("/") ? "absolute" : "relative");
+  return 0;
+};
+```
+
+- **No body, and it cannot be `export`ed.**
+- **A class with a `CPtr` field is a handle class: open one with `using`.**
+  `using f = new File(p)` closes `f` once at every exit of its block (falling
+  off the end, `return`, `break`, `continue`, `orReturn()`), so never call the
+  close yourself. The class is checked: one `readonly` `CPtr` or
+  `CPtr | null` field written once by the constructor's foreign call, read only
+  as `this.f` in its own methods, and a `[Symbol.dispose]` that is exactly the
+  close. A handle is never copied, stored, returned or captured: it is called
+  or lent to a parameter of its type, and `new` of one appears only as a
+  `using` initialiser. A panic or `process.exit` does not close it, so
+  `fflush` a written `FILE *` before code that may panic. The rules:
+  `LANGUAGE.md` → "A handle class".
+- **It costs the caller its attributes.** Nothing about a body the compiler
+  cannot see is provable, so a function that calls C loses `readnone` and
+  `willreturn`, and so does everything above it in the call graph. A program
+  that calls C is no longer one the compiler can reason about end to end — that
+  trade *is* the feature.
+
+### Module constants
+
+```ts nish:ok
+const TOKEN_NAME: i32 = 1;
+const TOKEN_END: i32 = TOKEN_NAME + 1;
+export const PROMPT: string = "> ";
+```
+
+A top-level `const` names a value the compiler already knows. **No symbol is
+emitted and no initialiser runs** — every use lowers to the value itself.
+
+- The **type annotation is required**, and so is an initialiser.
+- The type must be `i32`, `i64`, `f64`, `number`, `boolean`, or `string`. An
+  array, class or interface constant would need an allocation, and there is no
+  code to run it.
+- The initialiser is literals, other constants (declared anywhere, or
+  imported), and arithmetic over them. A call, a `new`, a local — anything else
+  — is rejected.
+- Folding uses the language's own arithmetic, so an overflowing fold is an
+  error rather than a wrap, and `1 / 0` in a constant is refused at compile
+  time.
+
+### Classes and interfaces
+
+```ts nish:ok
+interface Shape { width: i32; height: i32; }
+
+class Rect implements Shape {
+  width: i32;
+  height: i32;
+  label: string = "r";
+
+  constructor(width: i32, height: i32) {
+    this.width = width;
+    this.height = height;
+  }
+
+  area(): i32 {
+    return this.width * this.height;
+  }
+}
+
+const describe = (s: Shape): i32 => s.width + s.height;
+
+export const main = (): i32 => {
+  const r = new Rect(3, 4);
+  console.log(`${r.area()} ${describe(r)}`);
+  return 0;
+};
+```
+
+- Fields need annotations; an initializer must be a **literal** of the field's
+  type. Layout is declaration order, exactly as clang lays out the same C
+  struct.
+- At most one constructor, no parameter properties, no overloads. **Definite
+  assignment** is checked syntactically: after the constructor returns every
+  field holds a value, and reading `this.f` before every field is assigned is
+  an error.
+- Methods need a body and an explicit return type. `readonly` fields may be
+  assigned only as `this.f = v` in their own class's constructor.
+- `===` / `!==` on two values of one class is pointer identity; `<` and friends
+  are rejected.
+- **No inheritance.** `extends` and `super` are rejected in every spelling.
+- An **interface** is a struct with fields only — no methods, no `extends`, no
+  `new`.
+- **`class C implements I` requires `I`'s fields to be `C`'s first fields**, in
+  order, with identical types; `C` may declare more after them. A `C` then
+  converts to an `I` wherever one is expected. **This is the only widening in
+  the language**, and nothing converts back — no downcast, no `instanceof`.
+
+### An array of records is one contiguous block
+
+`Point[]` where `Point` is a class or interface stores the records themselves,
+back to back — not an array of pointers. So `ps[i]` is an *interior* pointer,
+and `push` may move the whole block to grow it. **Holding an element across a
+`push` on the same array is therefore refused**, because the write would land
+in the old storage:
+
+```ts nish:err NL2290
+interface Point { x: i32; }
+
+export const main = (): i32 => {
+  const ps: Point[] = [{ x: 1 }];
+  const p = ps[0];
+  ps.push({ x: 2 });
+  p.x = 3;
+  return 0;
+};
+```
+
+Index again after the `push` instead of holding the element across it:
+
+```ts nish:ok
+interface Point { x: i32; }
+
+export const main = (): i32 => {
+  const ps: Point[] = [{ x: 1 }];
+  ps.push({ x: 2 });
+  ps[0].x = 3;
+  console.log(`${ps[0].x}`);
+  return 0;
+};
+```
+
+### Object literals
+
+An object literal takes its type from context — a variable annotation, the
+enclosing function's return type, the parameter it is passed to, the field it
+is assigned to, or a field of an enclosing literal. It must set every field
+exactly once, with plain identifier keys.
+
+```ts nish:ok
+interface Pair { first: i32; second: i32; }
+
+const swap = (p: Pair): Pair => ({ first: p.second, second: p.first });
+
+export const main = (): i32 => {
+  const p: Pair = { first: 1, second: 2 };
+  console.log(`${swap(p).first}`);
+  return 0;
+};
+```
+
+The context reaches a nested literal and a `null`, and stops there: a numeric
+literal in a property keeps the mode's default type (above), and `[]` has no
+element type at all in that position.
+
+A class with methods is made only by `new`: a literal typed as one would be a
+plain object under Node, without the methods (NL2556). A class with fields
+alone, and an interface, still take a literal.
+
+```ts nish:err NL2556
+class Counter {
+  n: i32;
+  constructor(n: i32) {
+    this.n = n;
+  }
+  get(): i32 {
+    return this.n;
+  }
+}
+
+export const main = (): i32 => {
+  const c: Counter = { n: 5 }; // write `new Counter(5)`
+  return c.get();
+};
+```
+
+### Type aliases and enums
+
+```ts nish:ok
+type Byte = u8;
+type Bytes = Byte[];
+
+enum Kind {
+  If = 1,
+  While = 2,
+}
+
+const name = (k: Kind): string => {
+  switch (k) {
+    case Kind.If:
+      return "if";
+    default:
+      return "while";
+  }
+};
+
+export const main = (): i32 => {
+  console.log(name(Kind.If));
+  return 0;
+};
+```
+
+- A `type` alias is a second name for an existing type, **not a type of its
+  own** — the same program with and without its aliases emits byte-identical
+  IR. A generic *alias* is still forbidden even though a generic function,
+  class and interface are not; built-in names may not be aliased.
+- A numeric `enum` is a **distinct type** represented as `i32`, and that is the
+  point: `Kind` and `i32` never convert in either direction. Members must be
+  numeric literals. `===` and `!==` are the **only** operators — no arithmetic,
+  no bitwise, so **bit flags stay `i32` module constants**.
+- **A member is also a type.** `Kind.While` as an annotation is a slot that
+  holds exactly that member — the shape of a tag field that says which case
+  its object is. Only the member's own constant (or a value already of that
+  member type) enters it; any other member, or a `Kind` value, is NL2519. A
+  member type converts to its enum, and a read of one *is* the enum, so it
+  compares, switches and passes as a `Kind`. The IR is the enum's `i32`. A
+  generic call takes the member's constant where the member type is wanted
+  (`fold(xs, Kind.Array)` with `xs: Kind.Array[]`), parenthesised or not.
+  It binds a type parameter only from the arguments, so `id(Kind.Array)`
+  into a `Kind.Array` slot, and `apply(take, Kind.Array)` with
+  `take: (x: Kind.Array) => Kind.Array`, bind `T` to `Kind` and are refused:
+  pass a value already of the member type instead. An unannotated `let`
+  keeps the member type of a value already of it, and widens the member's
+  constant to `Kind`, as `tsc` does; so do a ternary, an array literal, `??`
+  and an arrow's result (`[a]` is a `Kind.Array[]`, and so is
+  `map([a], (k) => k)`; `(k) => Kind.Array` answers `Kind`). Arms or elements
+  that differ where one is a member type or an array of one (`c ? a : b`,
+  `c ? a : k`, `[a, Kind.Array]`, `[[a], [Kind.Array]]`) are refused:
+  annotate the variable.
+  `new Array<Kind.Array>(n)` zero-fills, so it is NL2520 unless the member is
+  0; build such an array with `[]` and `push`. A `parallelMap`,
+  `parallelFrom` or `parallelReduce` body answering one is NL2521: answer
+  `Kind` instead.
+
+```ts nish:ok
+enum Kind {
+  Scalar,
+  Array,
+}
+
+class ArrayNode {
+  readonly kind: Kind.Array = Kind.Array;
+  size: i32 = 0;
+}
+
+const isArray = (k: Kind): boolean => k === Kind.Array;
+
+export const main = (): i32 => {
+  const n = new ArrayNode();
+  return isArray(n.kind) ? 0 : 1;
+};
+```
+
+```ts nish:err NL2519
+enum Kind {
+  Scalar,
+  Array,
+}
+
+const pick = (k: Kind): Kind.Array => k; // a `Kind` could be any member
+
+export const main = (): i32 => (pick(Kind.Array) === Kind.Array ? 0 : 1);
+```
+
+- **Both can be exported.** `export enum Kind` is imported like a function,
+  `import { Kind } from "./kinds"` (renamed with `as` if you like), and in the
+  importer it *is* the exporter's `Kind`: the members fold to the exporter's
+  integers and a `Kind` value crosses a call as itself. A `Kind` a second
+  module declares for itself is a different type, however alike the two are.
+  `export type Conn = Socket | null` is imported the same way and is, in the
+  importer, the type it names; its right-hand side is resolved in the module
+  that wrote it, so the importer need not import `Socket`. A module does not
+  re-export an enum or alias it imported.
+- Both are top-level only.
+
+### Discriminated unions
+
+```ts nish:ok
+enum Kind {
+  Circle,
+  Square,
+}
+
+class Circle {
+  readonly kind: Kind.Circle = Kind.Circle;
+  r: i32 = 3;
+}
+
+class Square {
+  readonly kind: Kind.Square = Kind.Square;
+  side: i32 = 4;
+}
+
+type Shape = Circle | Square;
+
+const pick = (round: boolean): Shape => (round ? new Circle() : new Square());
+
+export const main = (): i32 => {
+  const shapes: Shape[] = [pick(true), new Square()];
+  let circles = 0;
+  let area = 0;
+  for (const s of shapes) {
+    if (s.kind === Kind.Circle) {
+      circles = circles + 1; // `s` is a `Circle` here
+      area = area + 3 * s.r * s.r;
+    } else {
+      area = area + s.side * s.side; // and a `Square` here
+    }
+  }
+  return circles === 1 && area === 43 ? 0 : 1;
+};
+```
+
+- A **variant** is a class or interface, not generic, whose **first field is
+  its tag**, of one enum member type: `readonly kind: Kind.Circle =
+  Kind.Circle`. All variants of a union take their tags from one enum, under
+  one field name, with different members; a union names at least two. Each
+  broken rule has its code (NL2522–NL2527); a tag that is not `readonly` is
+  NL2535, one typed as the whole enum (`readonly kind: Kind`) NL2559. Any
+  other union is still NL1053.
+- A union is a local, parameter, field, return, array element, or nullable
+  (`Shape | null`). An alias may name another union, which is flattened. A
+  variant, or a smaller union, converts into it wherever the union is
+  expected — argument, `return`, `push`, an annotated array literal, a
+  ternary arm or `??` default whose other side is the union. A class that
+  implements an interface variant converts to that interface first. A union
+  crosses modules but not a sidecar (NL4009).
+- **Test the tag to read a variant.** Before a test, the tag is the only
+  member (NL2528 for anything else, even a field every variant has). A test of
+  a local's or parameter's tag narrows it as `tsc` does: `if`/`else`, a
+  ternary, `&&`, `||`, `!==`, an early `return`/`break`/`continue`, each
+  `case` of a `switch (s.kind)`, and composed with `s !== null &&`. Two or
+  more variants left still give only the tag; an assignment drops the
+  narrowing. Where `a || b` held (or `a && b` failed), the variable is what
+  either side proved, `Circle | Square` after two tag tests. A test reads
+  through an assignment: `(t = next()).kind === Kind.Square` narrows `t`. Past an `if`, the
+  variable is what the arms that fall through left it (an `else if` chain
+  that returns leaves the variant no test named), including what a test nested
+  in each arm proved: two arms that each return when `s.kind === Kind.A` leave
+  `s` not a `VA`; a `switch`'s exits join the same way. A path does not narrow the
+  union (`h.s.kind` then `h.s.r` is NL2558): copy it into a local and test
+  that. The tag read through a path (`h.k`, `this.k`, `h.s.kind`,
+  `xs[0].kind`, `xs[i].kind`) does stay narrowed for later comparisons, until a store to
+  the path, a prefix of it or its root. An index `i` is part of the path when
+  it holds one value: a parameter, a `const` (`const i = 0` makes `xs[i]` the
+  path `xs[0]`, and so does `const j = i` after it), a module constant
+  (`const IDX: i32 = 0` makes `xs[IDX]` the path `xs[0]`), or a `let` nothing
+  assigns; through a `let` that is assigned
+  or stepped, `xs[i]` is not narrowed, and `xs[j] = t` drops nothing. A read where every variant was excluded is
+  NL2557.
+- The tag reads as the enum: `const k: Kind = s.kind` — annotate it,
+  `const k = s.kind` is NL2530. `k` holds only the variants' members. A
+  union is read-only, even for a field every variant has (NL2529). Comparing
+  the tag (or such a `k`) with a member it cannot hold — one no variant has,
+  or one a test already excluded — is NL2531, a `case` for one NL2532.
+- A `switch` whose subject reads a variant's tag field (`s.kind`,
+  `h.shape.kind`, `xs[i].kind`, the receiver typed as the union) and whose
+  labels name every variant, with no `default`, is complete: if every
+  clause returns, it ends a function that returns a value, and its unmatched
+  case is `unreachable` in the IR. A statement after it is unreachable code
+  when every clause returns; a clause's `break` reaches it.
+  With a variant unnamed it is the missing-return error, as TS2366. A
+  `switch (k)` on an enum variable (a parameter, or `const k: Kind = s.kind`,
+  `let` or `const`), or on an enum field assigned from a tag
+  (`b.k = s.kind`), is never complete, whatever its labels
+  (C may pass an enum any `i32`): give it a `default` or return after it.
+  A path's tag a test narrowed (`h.s.kind` after
+  `if (h.s.kind === Kind.A) return`) needs every tag of the whole union; a
+  narrowed union local is complete with the variants left to it.
+- An enum variable, a parameter `k: Kind` as much as such a tag local, narrows
+  on `k === Kind.A` / `!==` in the same forms as a union, `switch (k)`
+  included: after `if (k === Kind.A) return`, `k === Kind.A` is NL2531.
+  Narrowed to one member, `let j = k` is a `Kind.A`; to several,
+  `const j = k` is NL2530 (annotate it `Kind`). `s.kind === k` narrows `s`
+  to the variants of `k`'s members where they are equal. An enum local an
+  `if`, ternary, loop or `switch` stores into holds, after it, what it held
+  or any member stored; after a `switch`, what its exits left (each `break`,
+  the last clause's end, and the unmatched case when there is no `default`);
+  after a loop, what its condition leaves false at the head, joined until it
+  no longer changes, and each `break`, as `tsc` reads it — a variable the
+  loop only tests included, and an `if` or `switch` inside the loop narrowing
+  as it does outside; a `for` update is read after the body. A loop holding
+  a path (`h.k`), a store inside an expression (an argument, an initializer,
+  a chain's inner `=`), a store of a field or method call read through an
+  element, a call or a receiver the loop declares (`gs[0].b`,
+  `makeG().b`), of a `let` the loop declares or of a `const` it declares
+  from a tracked variable (a swap's `const t: Kind = a`), a ternary arm
+  reading the stored variable where it holds no member
+  (`k = k === Kind.A ? Kind.B : k`), or a type of more than 29 members
+  falls back to every member the body stored
+  anywhere or the whole type, which accepts a few comparisons `tsc` refuses
+  (TS2367; LANGUAGE.md, "Accepted here, refused by `tsc`").
+- **Refused by design:** union type arguments (`Box<Shape>`,
+  `Map<K, Shape>`, `Result<Shape, E>`, a generic call binding `T` to a
+  union: NL2533), unions as `Map`/`Set` keys, covariant arrays (`Circle[]`
+  is not `Shape[]`), and inferred unions (an unannotated ternary or array of
+  two variants).
+- **Declare what you store.** A store of a value that is only some of the
+  variants into a union slot is NL2534, because `tsc` would narrow the slot
+  from there on. Declare the slot as the variant, or store a value of the
+  whole union (a call returning `Shape`):
+
+```ts nish:err NL2534
+enum Kind {
+  Circle,
+  Square,
+}
+
+class Circle {
+  readonly kind: Kind.Circle = Kind.Circle;
+}
+
+class Square {
+  readonly kind: Kind.Square = Kind.Square;
+}
+
+type Shape = Circle | Square;
+
+export const main = (): i32 => {
+  const s: Shape = new Circle(); // tsc treats `s` as a Circle from here
+  return s.kind === Kind.Circle ? 0 : 1;
+};
+```
+
+### Modules
+
+- `export` goes on `const` (function or constant), `class`, `interface`,
+  `enum` and `type` declarations. No `export default`, no `export { … }`, no
+  `export *`, no `export =`: each is refused by its own rule, once.
+- The only import form is a **named import**:
+  `import { square, cube as pow3 } from "./math"`. `.ts` is optional. Default
+  imports, namespace imports, side-effect imports, type-only imports,
+  `import x = require(…)`, import attributes (`with { … }`) and
+  `import defer` are all rejected, each by its own rule and before anything
+  is loaded. `type`, `as` and `from` are still names: `import { type } from`
+  imports a function called `type`.
+- A specifier is a relative path (`./x`, `../x`), a builtin module (`nish:fs`),
+  a standard-library module (`nish/text`, `nish/pair`), or a **package name** (`hash`,
+  `@scope/hash`, with a subpath after it if you want one).
+- **A package is resolved through `node_modules` and compiled from source.**
+  The package's `package.json` must offer the file under the `nish` export
+  condition — `{"exports": {".": {"nish": "./src/index.ts"}}}` — and the mode
+  gets a spelling of its own, `nish-i32` / `nish-f64`, for source that is only
+  correct under one `--number-mode`. The mode-qualified condition wins wherever
+  the package declares it, so a manifest carrying both never compiles the wrong
+  one of the two. A package without that condition is
+  `` Package `lodash` has no Nish entry point ``, which is what an ordinary npm
+  package gets: there is nothing to compile in a `.js` file. One that offers
+  only the other mode is `` supports Nish in f64 mode only ``, one whose
+  `"engines": {"nish": ">=X.Y.Z"}` is above this compiler `` needs a newer
+  compiler ``, and a `package.json` that is not JSON names its line and
+  column — each with its own `--json` code (`NL3017`–`NL3021`).
+- Functions and enums may be renamed on import; classes and interfaces may
+  not — the type name is part of the ABI.
+- Import cycles are allowed; a shared dependency is compiled once.
+- **A function name is unique across the whole program**, exported or not.
+- An `export`ed function is an external C-ABI symbol; every other function gets
+  `internal` linkage so LLVM may inline or drop it.
+- **So an exported function is not named after a C library function**
+  (`write`, `read`, `free`, `exit`, `strlen`, `sin`, …, the list in
+  `src/c-symbols.ts`) and does not begin with `_`, `napi_` or `node_api_`: its symbol would
+  replace the C one in the linked program, in a native, a wasm or an N-API
+  build alike. `` `write` is the C library's `write`: an exported function of the program's own package keeps its name as its symbol, so the references the C library and the runtime make to that name would reach this function instead; rename it ``
+  (NL3037). Name it `writeLine`, or leave it private: a private function with
+  such a name gets a symbol ending in `$`.
+- **Nor, in a wasm build, `memory`**: a wasm `--target`, `--profile wasi` or
+  `--emit-dts` refuses it, because the `--profile wasm` module exports its
+  linear memory under that name; wasi reserves it too, so a program that
+  builds for wasi also builds as a freestanding wasm module. `` `memory` is the name a wasm module exports its linear memory under: an exported function of the program's own package keeps its name as its symbol, so the module would export two things named `memory` and no host could load it; rename it ``
+  (NL3038). A native build keeps it.
+
+## Statements
+
+- **Conditions must be `boolean`.** There is no truthiness, in `if`, `while`,
+  `for`, the ternary, `&&` or `||`.
+- `let` / `const` need an initializer and take their type from it; an
+  annotation must match **exactly**. `const` freezes the binding, not the
+  contents: `xs[0] = 1` and `xs.push(1)` on a `const xs` are fine.
+- `var` is forbidden. Destructuring is not supported.
+- **Semicolons are optional**, where TypeScript would insert one: at a line
+  break, before `}` and at the end of the file. It is TypeScript's rule, so a
+  line starting with `(` or `[` continues the one before it, and `return`
+  followed by a line break returns nothing. Here, the value left on the next
+  line is an unreachable-code error rather than a silent bug.
+- `for (init; cond; update)` with every clause optional, and
+  `for (const x of xs)` over an **array** only — `x` gets the element type and
+  must not be annotated. The array's `length` is re-read each iteration, so a
+  `push` inside the body extends the loop. `for...in`, `for await` and
+  `for (x of xs)` over an existing `x` are each refused by name.
+- `switch` takes an **integer or enum** discriminant; every `case` label is an
+  integer constant expression of that type. **There is no implicit
+  fallthrough** — a clause with statements ends in `break`, `return`,
+  `continue` or `process.exit`, unless it is the last. An *empty* clause does
+  fall through, which is how `case 1: case 2:` shares a body. A clause cannot
+  declare a variable directly; wrap its body in a block.
+- `break` / `continue` are unlabelled only; labeled statements are forbidden.
+- `process.exit(code)` and `panic(msg)` **terminate control flow**, so a
+  non-`void` function may end with either.
+- **Unreachable code is an error**, not a warning: anything after a `return`,
+  `break`, `continue`, `process.exit`, an `if` whose branches all return, or an
+  infinite loop.
+
+```ts nish:err NL2166
+const classify = (n: i32): string => {
+  switch (n) {
+    case 0:
+      console.log("zero");   // no `break`: a clause with statements must end in one
+    case 1:
+      return "one";
+    default:
+      return "many";
+  }
+};
+
+export const main = (): i32 => {
+  console.log(classify(0));
+  return 0;
+};
+```
+
+## Expressions
+
+- Arithmetic `+ - * / %` takes **two numbers of one type**. `+` on two strings
+  concatenates; `string + number` is rejected (use a template literal).
+- **Integer division is checked**, Rust-style: a zero divisor, or `MIN / -1`,
+  prints to stderr and exits 1. Float division is never checked.
+- Bitwise `& | ^ ~` and shifts `<< >> >>>` take **integers of one type**.
+  `>>` is arithmetic on a signed type and logical on an unsigned one; the shift
+  count is masked to the operand width.
+- `=== !==` on any two values of the same type: integers and booleans by value,
+  `f64` by `fcmp` (so `x !== x` is true for `NaN`), **strings by content**,
+  arrays and objects by **identity**.
+- `< <= > >=` on two numbers of one type and nothing else — not booleans, not
+  strings, not structs.
+- `++` / `--` work on **numeric mutable locals only**, not fields or elements.
+- Compound assignment `+= -= *= /= %=` requires a numeric target (so `+=` never
+  concatenates strings); the bitwise forms need an integer target.
+- **Forbidden**: `,` `in` `instanceof` `typeof` `delete` `void expr` `==`
+  `!=` `**` unary `+`, `?.[i]` and `f?.()`, `?.` outside a chain that ends in
+  `??`, and `??` on anything but a `T | null`, a `?.` chain or a `Map.get`
+  result.
+- Element access `a[i]` needs an array and a numeric index, and is
+  bounds-checked (negative indices fail too). String-keyed access is forbidden.
+  The check comes off where the compiler proves the index in range — a loop
+  condition `i < xs.length`, or `i < h.xs.length` on a field path — as long as
+  nothing between the test and the access calls a function, stores to a field
+  the path names, or reassigns its root.
+- Array literals need one element type; `[]` needs a contextual `T[]`. Holes
+  and spread are not supported.
+- Template literals accept holes of type `string`, `number`, `i64`, `f64` or
+  `boolean` — this is how you convert a number to a string.
+
+## The builtins, in full
+
+No import is needed; these are resolved by name, and a user function of the
+same bare name shadows the builtin. **This list is exhaustive** — anything not
+on it does not exist, and inventing a method is the most common way to write a
+program that does not compile.
+
+**Output.** `console.log(x)` and `console.error(x)` take exactly one argument
+of `string | number | i64 | f64 | boolean` and are **statement position only**.
+`write(s)` / `writeError(s)` take a `string` and add no newline.
+`panic(message)` writes to stderr and exits 1.
+
+**`Math`.** `sqrt` `floor` `ceil` `trunc` `sin` `cos` `exp` `log` (all `f64`
+argument, `f64` result), `pow(x, y)`, `round(x)`, `abs(x)` (any numeric type),
+`min(a, b)` / `max(a, b)` (exactly two, one type), `clz32(x)` (an `i32` or `u32` in,
+the leading zero bits out, 0 to 32), `random()`, and the
+constants `Math.PI` / `Math.E`. The f64-only ones reject an `i32`: write
+`Math.sqrt(toF64(n))`.
+
+**Conversions.** `toI32` `toI64` `toU8` `toU16` `toU32` `toU64` `toF32`
+`toF64`; `f64ToBits(x)` / `bitsToF64(b)` reinterpret rather than convert;
+`Number(x)`, `parseInt(s)` (base 10, `i32`, no `NaN` — no digits give `0`),
+`parseFloat(s)`.
+
+**Constant time.** `ctSelect(mask, a, b)` is `(a & mask) | (b & ~mask)` and
+`ctEq(a, b)` is all-ones when equal and zero otherwise, both over `u32` or
+`u64` only, every operand one type. The mask sits behind an optimisation
+barrier, so neither ever becomes a branch; select and compare on a secret with
+these, never with `if`, `?:`, `===` or `table[secret]`, which they cannot fix.
+`secureZero(bytes)` sets every byte of a `u8[]` to zero in stores the optimiser
+may not drop, as a statement: how a key in a plain array is cleared once used.
+
+**Secrets.** Hold a key as a `Secret<T>` from `nish:secret` (`T` an integer
+array or a record of integer fields). It is opaque: no printing, interpolating,
+comparing with a value, branching, indexing, `.value`, array element or
+`Result` payload, a field other than a holder's `readonly` one (below), and no
+builtin takes one. Read it only with `expose(s, f)` or
+`exposeWith(s, arg, f)`, where `f` is a top-level function or an arrow that
+declares its return type, reaches no I/O and no C, keeps nothing of the value
+and returns no `Secret` — that return is what leaves. A `Secret` your function
+makes must be `wipe`d or returned **on every path** (each `return`, `break`,
+`orReturn()`), is moved by `const j = k`, and is never read after `wipe`;
+`secret(local)` moves the local too. `secret(v)` takes only a value nothing
+else holds (NL2512): a literal, a `new`, a call that makes one, or a local that
+is the only name for its value. A second name made before the move — `const
+alias = raw`, a field or element store, `push`, `Ok(raw)`, a ternary arm, a
+function that keeps its parameter, a data-parallel arrow that captures it — is
+refused with where it was made; pass a fresh value, or a copy
+(`const copy: u8[] = new Array<u8>(raw.length); copy.set(raw)`, then
+`secret(copy)`). `std/crypto`'s `p256`, `x25519` and
+`x509ParseP256PrivateKey` take and give keys this way.
+
+```ts nish:ok
+import { Secret, expose, secret, wipe } from "nish:secret";
+
+const key = (): u8[] => [7, 1, 9];
+const width = (k: u8[]): i32 => toI32(k.length);
+
+export const main = (): i32 => {
+  const k: Secret<u8[]> = secret(key());
+  const n: i32 = expose(k, width);
+  wipe(k);
+  return n === 3 ? 0 : 1;
+};
+```
+
+```ts nish:err NL2440
+import { Secret, expose, secret } from "nish:secret";
+
+const key = (): u8[] => [7, 1, 9];
+const width = (k: u8[]): i32 => toI32(k.length);
+
+export const main = (): i32 => {
+  const k: Secret<u8[]> = secret(key());
+  return expose(k, width); // NL2440: `k` leaves unwiped
+};
+```
+
+```ts nish:err NL2512
+import { Secret, secret, wipe } from "nish:secret";
+
+export const main = (): i32 => {
+  const raw: u8[] = [7, 1, 9];
+  const alias = raw; // a second name for the bytes
+  const k: Secret<u8[]> = secret(raw); // NL2512: `raw` has a second reference
+  wipe(k);
+  return toI32(alias[0]);
+};
+```
+
+**A key kept in an object.** A class keeps a key as long as it lives in a
+`readonly` field of exactly `Secret<T>` (the class not generic). Set it once,
+in the constructor, with `this.k = secret(fresh)`; rewrite it only in place
+through `exposeWith`; read `this.k` only as a call or `new` argument (`expose`,
+`exposeWith`, a function taking a `Secret`; `wipe` only in the holder's own `wipe()`) or a `===`/`!==` operand —
+never bind, return or store it. The class declares `wipe(): void`, no
+parameters, calling `wipe(this.k)` itself for every such field on every path
+(NL2540, NL2541); a field is wiped nowhere else (NL2547). A function taking a
+`Secret` borrows it: it neither returns it (NL2546) nor wipes it (NL2548). Nothing checks that `wipe()` is called: call it when the
+holder is done.
+
+```ts nish:ok
+import { Secret, expose, secret, wipe } from "nish:secret";
+
+const width = (k: u8[]): i32 => toI32(k.length);
+
+class Session {
+  readonly key: Secret<u8[]>;
+  constructor() {
+    this.key = secret(new Array<u8>(32));
+  }
+  size(): i32 {
+    return expose(this.key, width);
+  }
+  wipe(): void {
+    wipe(this.key);
+  }
+}
+
+export const main = (): i32 => {
+  const s = new Session();
+  const n: i32 = s.size();
+  s.wipe();
+  return n === 32 ? 0 : 1;
+};
+```
+
+```ts nish:err NL2544
+import { Secret, secret, wipe } from "nish:secret";
+
+class Session {
+  readonly key: Secret<u8[]>;
+  constructor() {
+    this.key = secret(new Array<u8>(32));
+  }
+  wipe(): void {
+    wipe(this.key);
+  }
+}
+
+export const main = (): i32 => {
+  const s = new Session();
+  const k = s.key; // NL2544: a second owner of the key
+  s.wipe();
+  return 0;
+};
+```
+
+**Arrays.** `a.length` (read-only), `a.push(v)`, `a.pop()` (panics when empty —
+there is no `undefined` to return), `a.indexOf(v)`, `a.join(sep)` — **`join` is
+`string[]` only** — and, on an array of numbers only, `dst.set(src[, offset])`
+(one `memmove`; a range past the end panics) and `a.fill(v[, start[, end]])`
+(ends clamped and counted back from the end when negative, as in JavaScript;
+never panics). Both are statements. That is every array method there is. A
+window into a buffer is `(buf, offset, length)`; there is no view type.
+
+**Strings.** `s.length` (**bytes**), `s.charCodeAt(i)` (the byte, bounds-checked),
+`s.substring(start[, end])`, `s.slice(start[, end])`, `s.indexOf(sub)`,
+`s.startsWith(sub)`, `s.endsWith(sub)`, `String.fromCharCode(c)`, and
+`String.fromBytes(bytes, start, end)` (a `u8[]` range as one string, one
+allocation; the range panics outside `0 <= start <= end <= bytes.length`; build
+text from bytes with it, never a `fromCharCode` per byte). That is every string
+method there is. `substring` **clamps** an out-of-range offset the
+way JavaScript does; `slice` instead **panics** unless
+`0 <= start <= end <= s.length`, and is the faster of the two when you have
+already established the range. Every offset is a **byte** offset, so cutting a multi-byte character
+in half is possible. To count characters rather than bytes, `codePointLength(s)`
+from `nish/text` counts code points natively and, for text written in the
+source, under Node alike; under Node a string built from bytes (`String.fromBytes`,
+a `\u` escape `nish/json` decodes) is one unit per byte, and counts its bytes.
+
+**Process.** `process.exit(code)`, `process.argv` (a read-only `string[]`;
+`argv[0]` is the program path, one index earlier than Node),
+`process.platform`, `process.arch`.
+
+**Files and the system.** `readFileSync(path)` (exits 1 on failure),
+`readFileSyncOrNull(path)` (`string | null`), `readFileBytesSync(path)`
+(`u8[] | null`, the bytes as they are on disk), `writeFileSync(path, data)`,
+`appendFileSync(path, data)`, `mkdirSync(path)` (one level, `boolean`),
+`isDirectorySync(path)`, `readdirSync(path)` (`string[] | null`, sorted by
+bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
+`getenv(name)` (`string | null` — unset and empty are different answers),
+`realpathSync(path)` (`string | null`; symbolic links resolved, absolute, and
+`null` when it does not resolve),
+`monotonicNanos()` (`i64`; elapsed time only), and, for checking a path before
+trusting it, `lstatOwnerModeSync(path)` (an `i64`: the owner's uid in the high
+32 bits, `st_mode` in the low 32, `-1` when it does not resolve; a symbolic
+link answers for itself), `geteuid()` (`i64`) and `isExecutableSync(path)`
+(`boolean`).
+
+**The host.** `Date.now()` (an `f64` of whole milliseconds, the wall clock —
+**the only `Date` there is**: `new Date()`, `Date.parse` and the rest are
+refused), `crypto.getRandomValues(bytes)` (a statement over a `u8[]` only, at
+most 65,536 bytes a call, from the kernel's CSPRNG; more panics),
+`statMtimeSync(path)` (an `f64` of milliseconds, **NaN** — not `null` — when the
+path cannot be stat'd, so test `m !== m`), and `signalFd()` / `readSignal(fd)`:
+call `signalFd()` once at the top of `main`, then `readSignal(fd)` blocks until
+SIGTERM or SIGINT and answers 15 or 2. None of them exists on a wasm target.
+
+**Children and the machine.** `spawn(argv)` starts a child like `spawnSync` but
+answers its pid (`i32`) at once, without waiting; `kill(pid, sig)` sends 0, 2,
+9 or 15 and answers 0 (any other signal is `-22`); `waitPid(pid, flags)` answers
+`[pid, status]` as an `i32[]` — pid `-1` is any child, flag `1` does not block,
+`[0, 0]` means none has exited yet, and the status is the exit code or 128 plus
+the signal. Each answers a **negative errno** on failure (`[-10, 0]`: no child
+left), so test `pid > 0` before passing a pid on: `-1` (EPERM) handed to
+`waitPid` means any child. After `signalFd()` a blocking `waitPid` restarts
+through SIGTERM, so a supervisor reaps with flag `1` on a `pollWait` tick that
+also watches the signal fd. None of `spawn`, `kill`, `waitPid` may be called in
+a task or a parallel body; the two host facts may. `availableParallelism()` (`i32`, at least 1, no `--threads` needed) and
+`totalMemory()` (`i64` bytes, or `-1`) size a program to the machine. None of
+the five exists on a wasm target, and `spawn` and `waitPid` throw under Node.
+
+**Sockets** (`nish:net`, or the same names as globals). `tcpListen(host, port,
+backlog)`, `tcpAccept(fd, peer)`, `netRead(fd, buf, off, len)`,
+`netWrite(fd, buf, off, len)`, `netShutdown(fd, how)`, `netClose(fd)`,
+`netLocalPort(fd)` and `netAddress(out, host, port)`. Every one answers an
+`i32`: **a negative number is a failure, not an exception** — `-11` means "would
+block, call again", `-32` a peer that has gone (never SIGPIPE), `-98` the port
+is in use, `-111` refused, `-22` a bad argument. Every socket is non-blocking,
+and there is no `async` and no callback: your `main` is the loop. A client calls
+`tcpConnect(addr)`, which answers the descriptor while it is still connecting;
+wait for it to be writable, then `connectResult(fd)` is 0 or the failure. Buffers
+are `u8[]` only; an address is 18 bytes of one (IPv4 as `::ffff:a.b.c.d`, then
+the port big-endian); hosts are numeric literals, because there is no DNS.
+`netRead` / `netWrite` panic on a range outside the buffer.
+`tcpListenFlags(host, port, backlog, flags)` is `tcpListen` with flag 1
+`SO_REUSEPORT`, so several listeners, in one process or many, share a port (Linux
+spreads the connections), and flag 2 `TCP_NODELAY` on every socket `tcpAccept`
+takes from it; flags add, and any other bit is `-22`. UDP is
+`udpBind(host, port, flags)` (flag 1 `SO_REUSEPORT`, flag 2 GRO),
+`udpSendTo(fd, buf, off, len, to, segment, ecn)` and
+`udpRecvFrom(fd, buf, off, len, from, meta)`: a `segment` above 0 sends one
+buffer as many datagrams of that size, `meta` is an `i32[]` of at least 2 that
+receives the GRO segment size (0 when nothing was coalesced) and the ECN bits,
+and an empty datagram answers 0. GSO, GRO and ECN are Linux's: on Darwin they
+answer `-95`. To wait for whichever descriptor is ready, `pollCreate()` makes a
+loop, `pollAdd(loop, fd, events, token)` / `pollModify(...)` watch `fd` for
+`events` (1 readable, 2 writable) under a `token` you choose, and
+`pollRemove(loop, fd)` stops. `pollWait(loop, ready, timeoutMs)` waits (forever
+for `-1`), fills `ready: i32[]` with pairs — `ready[2k]` a token,
+`ready[2k + 1]` its events, 4 added for a hang-up or error — and answers how
+many, **0 on a timeout or a signal**. It is level-triggered, so what you leave
+unread is reported again. Add `signalFd()` to the loop to wake on SIGTERM. None
+exists on a wasm target, and under Node each throws.
+
+**Arena.** `Arena.mark()`, `Arena.used()` and `using a = arena()` — see below.
+`Arena.release(m)` and `Arena.reset()` are deprecated (NL7001).
+
+### Map and Set
+
+`Map<K, V>` and `Set<T>` are global, as in JavaScript: no import, insertion
+order, SameValueZero keys (`-0` is `+0`, `NaN` finds `NaN`). What they have is
+exactly `size` (a read-only `number`), `get(k)`, `set(k, v)` / `add(x)` (both
+answer the receiver, so they chain), `has(k)`, `delete(k)` (answers whether it
+was there) and `clear()`, and `keys()` / `values()` as the iterable of a
+`for...of` and nowhere else. `entries` and `forEach` are refused by name.
+
+```ts nish:ok-body
+const seen = new Set<string>();
+const counts: Map<string, i32> = new Map();
+seen.add("a").add("b").add("a");
+counts.set("a", 1).set("b", 2);
+counts.delete("b");
+console.log(`${seen.size} ${counts.size} ${seen.has("b")}`);
+```
+
+- Write the type arguments on `new`, or annotate the declaration and write
+  `new Map()`. `new Map(entries)` and `new Set(array)` are refused: start empty
+  and `set` / `add` in a loop.
+- A key is a string, any number type, a `boolean`, an enum or a class instance
+  (by identity). An interface, an array, a nullable type or a `Result` is not a
+  key; a value is anything but `void` or an interface.
+- A module that declares its own `Map` or `Set` keeps it, but then no other
+  module of the program may name the global one.
+
+`m.get(k)` is `V | undefined`, as under `tsc`, and it is read in exactly one of
+three ways: a default with `??`, a `const` tested with `!== undefined` (or
+`=== undefined` and an early `return`), or a bare test. Each is one probe.
+
+```ts nish:ok-body
+const counts = new Map<string, i32>();
+for (const w of ["a", "b", "a"]) {
+  counts.set(w, (counts.get(w) ?? 0) + 1);
+}
+const a = counts.get("a");
+if (a !== undefined) {
+  console.log(`${a} ${counts.get("z") === undefined}`);   // 2 true
+}
+```
+
+- Anywhere else — a `let`, an argument, a `return`, a field or element, a
+  template hole, an arithmetic operand, the default of another `??`, a `const`
+  annotated `i32` — the maybe is refused with a message naming the place.
+  Default it with `??` first: `m.get(a) ?? (m.get(b) ?? 0)`.
+- The only spelling of the type is `const a: i32 | undefined = m.get(k)`.
+- `??` does not mix with `||` or `&&` without parentheses, and its default must
+  be the value type. For a `Map<K, Node | null>` it replaces a stored `null`
+  too, but the result is still `Node | null`.
+
+```ts nish:err-body NL2361
+const m = new Map<string, i32>();
+let v = m.get("a");
+```
+
+Walk a map with `for (const k of m.keys())` or `for (const v of m.values())`,
+and a set with `for (const x of s)`: insertion order, deleted keys skipped. You
+may `set`, `delete` or `clear` the table inside the walk and get exactly what
+JavaScript gives (a new key is visited later in the same walk; a key deleted
+before it is reached is not).
+
+```ts nish:ok-body
+const ages = new Map<string, i32>();
+ages.set("ada", 36).set("alan", 41);
+ages.delete("alan");
+ages.set("grace", 85);
+let total = 0;
+for (const name of ages.keys()) {
+  console.log(name);                     // ada, then grace
+}
+for (const age of ages.values()) {
+  total += age;
+}
+console.log(`${total}`);                 // 121
+```
+
+- An iterator is not a value: `keys()` / `values()` stored, passed, returned or
+  spread are refused. Pass the map itself and walk it where it is used.
+- `for (const e of m)` over a `Map` itself is refused, because it would need
+  `[key, value]` destructuring: walk `m.keys()` and call `m.get(k)`.
+
+```ts nish:err-body NL2375
+const m = new Map<string, i32>();
+for (const e of m) {
+}
+```
+
+Asking about one key twice costs one probe when the second call writes
+through the first: `m.set(k, E)` whose `E` reads `m.get(k)` or `m.has(k)`
+once, and `if (m.has(k)) { m.set(k, E); … }`, `if (!m.has(k)) { m.set(k, E); … }`
+or `if (!s.has(x)) { s.add(x); … }` with the write first in the branch. The
+receiver and key must be a local, a parameter or a `this.<field>` path (the key
+may be a literal), spelled the same in both calls, and nothing in between may
+call anything, allocate (`new`, a literal array or object, a template, a
+string `+`) or assign. Anything else still compiles, as one probe per call.
+`nish/map` adds `getOrInsert(m, k, v)` — the value of `k`, or `v` after
+inserting it — and `reserve(m, n)`, which sizes the table for `n` entries; both
+are one module with the program and run unchanged under Node.
+
+```ts nish:ok
+import { getOrInsert, reserve } from "nish/map";
+
+export const main = (): i32 => {
+  const words = ["to", "be", "or", "not", "to", "be"];
+  const counts = new Map<string, i32>();
+  reserve(counts, words.length);
+  for (const w of words) {
+    counts.set(w, (counts.get(w) ?? 0) + 1);   // one probe per word
+  }
+  const first = new Map<string, i32>();
+  for (let i = 0; i < words.length; i++) {
+    getOrInsert(first, words[i], i);           // one probe; inserts only the first time
+  }
+  console.log(`${counts.get("to") ?? 0} ${first.get("be") ?? -1}`);   // 2 1
+  return 0;
+};
+```
+
+### Typed JSON: `nish/json-typed`
+
+`jsonDecode(d, out)` reads one JSON object into a class and `jsonEncode(w,
+value)` writes one; the compiler writes the code at each call from the class's
+fields. A field is `i32`, `u32`, `i64`, `u64`, `f64`, `boolean`, `string`, a
+numeric enum, a class, an array of one of those, a `Map<string, V>` of any of
+those, or a `string`, class, array or map `| null`; anything else is refused at
+the call (NL2485), a `Map` with non-`string` keys and a `Set` included, and so
+is a value that is not a class (NL2486). Decoding is strict: every field
+required, each key once, an unknown key an error unless `d.ignoreUnknown`, and
+every outcome a sticky negative code in `d.failed`, never a panic. An enum is
+its number, and a number that is no member's value is `JSON_DECODE_TYPE`; a
+`u64` is exact to 2^64 - 1, and negative is `JSON_DECODE_RANGE`; a map is
+emptied and filled in the input's key order, a repeated key an error, and
+more keys over all the maps of one decode than `d.maxMapKeys` (4,096 unless
+set) `JSON_DECODE_MAP_LIMIT`. A class
+the decoder makes (an array's element, a `| null` field's object, a map's
+value) has a constructor with no parameters (NL2488). A class's options are
+one `static readonly json = { rename: { field: "key" }, optional: ["field"] }`
+literal, the only `static` a class may have: `rename` gives a field its key on
+the wire, and a missing `optional` key sets its field to the initializer, so
+an optional field has one (NL2498). Each misuse is its own code where the class
+is declared: not `static readonly` or on a generic class (NL2492), not a
+literal (NL2493), an unknown option (NL2494), a name that is no field (NL2495),
+a rename to a non-string (NL2496) or to a key that is not valid UTF-8
+(NL2499), two fields with one key (NL2497). A
+`JsonNumber` field keeps a number's text byte for byte (`text`, `i64`, `u64`,
+`f64`, `setText`).
+
+```ts nish:ok
+import { JsonWriter } from "nish/json";
+import { JsonLimits } from "nish/json-tokenizer";
+import { JsonDecoder, jsonDecode, jsonEncode } from "nish/json-typed";
+
+class Point {
+  x: i32 = 0;
+  y: i32 = 0;
+}
+
+export const main = (): i32 => {
+  const text = `{"x":3,"y":4}`;
+  const body = new Array<u8>(toI32(text.length));
+  for (let i: i32 = 0; i < toI32(body.length) && i < toI32(text.length); i += 1) {
+    body[i] = toU8(text.charCodeAt(i));
+  }
+  const p = new Point();
+  const code = jsonDecode(new JsonDecoder(body, 0, toI32(body.length), new JsonLimits()), p);
+  const w = new JsonWriter(new Array<u8>(64), 0);
+  jsonEncode(w, p);                     // {"x":3,"y":4}
+  return code;                          // 0, or a JSON_DECODE_* / JSON_TOK_ERR_* code
+};
+```
+
+```ts nish:err NL2485
+import { JsonWriter } from "nish/json";
+import { jsonEncode } from "nish/json-typed";
+
+class Reading {
+  value: f32 = 0;                       // no JSON reading: use f64
+}
+
+export const main = (): i32 => {
+  const w = new JsonWriter(new Array<u8>(16), 0);
+  jsonEncode(w, new Reading());
+  return w.failed;
+};
+```
+
+```ts nish:ok
+import { JsonWriter } from "nish/json";
+import { JsonDecoder, JsonNumber, jsonDecode, jsonEncode } from "nish/json-typed";
+
+class Order {
+  static readonly json = { rename: { orderId: "order_id" }, optional: ["note"] };
+  orderId: i32 = 0;
+  note: string = "";                    // missing key: back to ""
+  total: JsonNumber;                    // any number, kept as written
+  constructor() {
+    this.total = new JsonNumber();
+  }
+}
+
+export const readOrder = (d: JsonDecoder, o: Order): i32 => jsonDecode(d, o);
+
+export const writeOrder = (w: JsonWriter, o: Order): void => {
+  jsonEncode(w, o);                     // {"order_id":..,"note":..,"total":..}
+};
+```
+
+```ts nish:err NL2495
+import { JsonWriter } from "nish/json";
+import { jsonEncode } from "nish/json-typed";
+
+class Order {
+  static readonly json = { optional: ["notes"] };   // no field `notes`
+  note: string = "";
+}
+
+export const main = (): i32 => {
+  const w = new JsonWriter(new Array<u8>(16), 0);
+  jsonEncode(w, new Order());
+  return w.failed;
+};
+```
+
+```ts nish:err NL2485
+import { JsonWriter } from "nish/json";
+import { jsonEncode } from "nish/json-typed";
+
+class Index {
+  byId: Map<i32, string>;               // a JSON object's keys are strings
+  constructor() {
+    this.byId = new Map<i32, string>();
+  }
+}
+
+export const main = (): i32 => {
+  const w = new JsonWriter(new Array<u8>(16), 0);
+  jsonEncode(w, new Index());
+  return w.failed;
+};
+```
+
+## Memory
+
+There is **no garbage collector and no `free`**, and nothing about this changes
+what a program computes — only where memory lives. You do not have to manage
+it, and mostly you should not try:
+
+1. **Stack allocation** for a `new`, object literal, array literal or
+   `new Array<T>(literal)` whose value provably does not outlive its function.
+2. **Automatic arena scopes** for a function whose temporaries all die with it:
+   a mark on entry, a release before every `ret`.
+3. **A reclaim at the call site** for a function that returns a string.
+4. **Explicit control** with `using a = arena()`, for code that manages
+   batches itself.
+
+**To free a batch, wrap it in a block with `using a = arena()`**: everything
+the block allocates after that line is released when the block ends, on every
+exit, and the compiler refuses the block if anything allocated in it could
+outlive it — so allocate what must outlive the block before it, and let only
+numbers, booleans and enums out. `arena()` is only ever a `using` initialiser,
+and `a` is never read.
+
+```ts nish:ok-body
+const rows: string[] = ["a", "bb"];
+let total = 0;
+for (const row of rows) {
+  using a = arena();
+  const line = `${row}: ${row.length}`;
+  total = total + line.length;
+}
+```
+
+**Do not hand an outer local a new allocation on every pass.**
+`let last = ""` above a loop whose body runs ``last = `item ${i}` `` keeps
+every pass's string, because nothing frees a value a later pass replaced:
+10,000,000 passes peaked at 392 MB. The compiler warns (NL9016). Declare the
+value with `const` inside the loop when only the pass reads it, or keep
+numbers across passes and build the value once after the loop. A server, or
+anything that runs for a long time, should compile with `--deny-retention`,
+which makes this warning and the three like it errors.
+
+Everything else is bumped from the arena, which is released when `main`
+returns. **Do not write `Arena.release` or `Arena.reset`**: releasing while
+anything allocated after the mark is still referenced is undefined behaviour
+the compiler does not check, so both are deprecated, and each call compiles
+with a `deprecation` warning (NL7001) pointing to `using a = arena()`.
+
+## Recipes for what is missing
+
+**Iterate and transform** — there is no `map`, and no function to pass it:
+
+```ts nish:ok-body
+const xs: i32[] = [1, 2, 3];
+const doubled: i32[] = [];
+for (const x of xs) {
+  doubled.push(x * 2);
+}
+console.log(`${doubled.length}`);
+```
+
+**Convert a number to a string** — there is no `toString` and no `String()`:
+
+```ts nish:ok-body
+const n = 42;
+const s = `${n}`;
+console.log(s);
+```
+
+**Return two values** — there are no tuples: declare an interface.
+
+```ts nish:ok
+interface Split { head: string; rest: string; }
+
+const cut = (s: string, at: i32): Split => ({
+  head: s.substring(0, at),
+  rest: s.substring(at),
+});
+
+export const main = (): i32 => {
+  console.log(cut("hello", 2).rest);
+  return 0;
+};
+```
+
+When the two values need no names of their own, `import { Pair } from "nish/pair"`
+and return `Pair<A, B>`: an object literal `{ first, second }` at the return,
+exactly as above. It is for returning two values, not storing them — a struct
+kept in an array or a field wants named fields.
+
+**A map or a set** — the global `Map` and `Set` ([Map and Set](#map-and-set)).
+Read a value with `m.get(k) ?? d`, and keep the keys in an array beside it when
+you need to walk them, since there is no iteration yet.
+
+**Find the next byte of a few** — `indexOfAny(text, bytes, from)` from
+`nish/text` answers the first index at or after `from` whose byte is one of
+`bytes`, or -1: the scan for the next `"` or `\\` in a JSON string, the next
+delimiter in a line. `bytes` holds 1 to 16 ASCII bytes and anything else
+panics; `from` is clamped to `[0, text.length]`. Natively it reads 16 or 32
+bytes at a time, so prefer it to a `charCodeAt` loop over a long text — and
+never call it on secret data, because its time says where the match is.
+(No block: a program importing `nish/text` writes two `.ll` files;
+`tests/link/std_text_index_of_any` is its program.)
+
+**Match a pattern** — there is no `RegExp` and no `/re/` literal:
+`regexCompile(pattern, flags)` from `nish/regex` answers a
+`Result<Regex, string>`, the error text naming the byte. The syntax is
+JavaScript's with the `u` flag's strictness (a stray `{` or `]` is an
+error), the flags are `i`, `m` and `s`, and backreferences and lookaround are
+refused, because matching never backtracks: time is linear in the input for
+every pattern. `test`, `exec(text, from, m)` into a reused `RegexMatch`,
+`find`, `findAll`, `count`, `replace`, `replaceAll` (`$&`, `$1`,
+`$<name>`) and `split`; offsets are UTF-8 bytes and `\w`, `\d`, `\b` and `i`
+are ASCII. A `Regex` keeps its scratch memory, so compile once outside the
+loop and use it from one thread. (No block, as for `nish/text`;
+`tests/link/std_regex` is its program, and the user guide's [standard-library
+page](guide/using-nish/standard-library.md#nishregex) its walk-through.)
+
+**Decode a URL or read a query** — there is no `decodeURIComponent` and no
+`URLSearchParams`: `nish/net/url` has both readings. `urlDecode(s, flags)` and
+`urlQueryGet(target, name)` answer a `string | null`; the byte API
+(`percentDecode`, `UrlPathSegments`, `UrlQuery`, `urlQueryFind`) reads a
+window of a `u8[]` and allocates nothing. Decoding is strict by default — a
+malformed escape or `%00` is refused, `+` is kept — and `URL_DECODE_FORM`,
+`URL_DECODE_LENIENT` and `URL_DECODE_ALLOW_NUL` add `URLSearchParams`'s
+repairs, short of its U+FFFD for invalid UTF-8. `percentDecode` answers the
+length or a negative `URL_DECODE_ERR_*` code — test it before reading `out`,
+since a peer's `%zz` makes it negative and `urlQueryStart` answers -1 for no
+`?` — and `percentDecodeErrorAt` the offset an error is at; a query yields at
+most 100 pairs. (No block, as for `nish/text`; `tests/link/std_url` is its
+program, and the user guide's [standard-library
+page](guide/using-nish/standard-library.md#nishneturl) its walk-through.)
+
+**Draw to the whole terminal** (a game, a dashboard) — there is no curses and
+no `process.stdout.on("resize")`: `runTerminal(options, state, update, render)`
+from `nish/term-io` opens the terminal, probes what it can draw, steps
+`update(state, input)` at `options.stepsPerSecond` and calls
+`render(state, frame)` only when the link to the terminal has room, then
+leaves the terminal as it was, even on a panic. Draw cells on `frame.screen`
+or pixels on `frame.framebuffer` (sized by `options.framebufferWidth` and
+`framebufferHeight`) and never pick a backend: kitty graphics, Sixel, half
+blocks or ASCII is chosen from the probe and the measured link. It answers
+`Err` with one sentence on a pipe, so test the `Result`; it reaches `tty`.
+`NISH_TERM_GRAPHICS` and `NISH_TERM_FPS` override what it picked. (No block,
+as for `nish/text`; `examples/term-probe.ts` is its program, and the user
+guide's [terminal page](guide/using-nish/terminal.md) its walk-through.)
+
+**Shared behaviour over several shapes** — there is no inheritance and no
+dispatch. Give each class the interface's fields **first**, `implements` it,
+and write a free function over the interface:
+
+```ts nish:ok
+interface Sized { width: i32; height: i32; }
+
+class Photo implements Sized {
+  width: i32;
+  height: i32;
+  path: string = "";
+  constructor(width: i32, height: i32) {
+    this.width = width;
+    this.height = height;
+  }
+}
+
+const area = (s: Sized): i32 => s.width * s.height;
+
+export const main = (): i32 => {
+  console.log(`${area(new Photo(3, 4))}`);
+  return 0;
+};
+```
+
+**Optional parameters** — there are none. Write two functions with different
+names, or take the value and document the sentinel.
+
+**A calendar, regex, JSON, threads of your own** — not in the language (the
+wall clock is `Date.now()`, and that is all of `Date`). Say so rather than
+emitting code that cannot compile.
+
+### Proving it cannot panic
+
+Under `--deny-panics`, or for a module the root `package.json` lists in
+`"nish": { "noPanic": [...] }`, every place the program could stop with a panic
+is an error (NL2457) until a proof removes it; out of memory is the one kind
+allowed. Each error names its fix, and there are five:
+
+- **Guard** what the checker cannot prove: `if (i >= 0 && i < xs.length)` before
+  `xs[i]` (`if (toU32(i) < toU32(xs.length))` for a `u8`, `u16` or `u32` index,
+  whose type is the lower end; `toI32(xs.length)` for the bound under
+  `--number-mode f64`; an `i64`, `u64` or float index — `number` under
+  `--number-mode f64` — has no guard, so index with an `i32` or a `u32`),
+  `if (d !== 0 && d !== -1)` before `a / d` (a
+  constant divisor needs nothing), `if (xs.length > 0)` before `xs.pop()`,
+  `if (n >= 0 && n <= 9)` before `n` enters `integer<0, 9>`.
+- **Bound a signed `+ - *`, or say it wraps**: an `i32`/`i64` operation the
+  checker cannot prove fits is an `overflow` site; bound its operands (a loop
+  below a length, a guard on the value), compute in `u32`/`u64`, or write
+  `wrappingAdd`, `wrappingSub` or `wrappingMul` from `nish:unsafe`.
+- **Swap `expect` for `orReturn` or `unwrapOr`**, which hand the error on or
+  supply a value instead of stopping.
+- **Swap `readFileSync` for `readFileSyncOrNull`**, which answers `null` where
+  the other exits.
+- **Read the list**: `nish file.ts --emit-panics panics.json` writes every site
+  per function, proven or not, and the `"panics"` of `--emit-capabilities` the
+  same.
+
+```ts nish:ok --deny-panics
+const at = (xs: i32[], i: i32): i32 => {
+  if (i >= 0 && i < xs.length) {
+    return xs[i];
+  }
+  return 0;
+};
+
+const byte = (xs: i32[], i: u8): i32 => {
+  if (toU32(i) < toU32(xs.length)) {
+    return xs[i];
+  }
+  return 0;
+};
+
+const ratio = (a: i32, d: i32): i32 => {
+  if (d !== 0 && d !== -1) {
+    return a / d;
+  }
+  return a / 2;
+};
+
+const size = (path: string): i32 => {
+  const text = readFileSyncOrNull(path);
+  return text === null ? -1 : text.length;
+};
+
+export const main = (): i32 => {
+  console.log(`${at([4, 5], 1)} ${byte([4, 5], 0)} ${ratio(9, 3)} ${size("missing.txt")}`);
+  return 0;
+};
+```
+
+The same function without its guard is refused, and the error names the guard:
+
+```ts nish:err NL2457 --deny-panics
+export const at = (xs: i32[], i: i32): i32 => xs[i];
+```
+
+A call into the standard library or a dependency that may panic is refused at
+the call (NL2458), because only its own author can prove it: call a function
+that cannot panic, or make the call from a module outside the scope.
+`--unchecked-indexing` is not a proof, and an index it leaves unchecked is
+still refused. `uncheckedGet` and `uncheckedSet` are not proofs either, but
+they cannot panic, and their `nish:unsafe` import is the module's visible
+opt-in to an index out of range being undefined behaviour, so the scope allows
+them (as `"allowed": true` sites) and a call into them is never refused:
+
+```ts nish:ok --deny-panics
+import { uncheckedGet } from "nish:unsafe";
+
+export const first = (xs: i32[]): i32 => uncheckedGet(xs, 0);
+```
+
+Without the import the call is refused (NL2456), scope or not:
+
+```ts nish:err NL2456 --deny-panics
+export const first = (xs: i32[]): i32 => uncheckedGet(xs, 0);
+```
+
+### Holding it to its capabilities
+
+A package that must not touch the network says so in `package.json`,
+`"nish": { "capabilities": { "deny": ["net"] } }`, and `--deny net` or an
+allowlist such as `--allow fs.read,exit` says the same on the command line.
+The `"nish"` field holds `noPanic` and `capabilities` and nothing else, each
+written once; anything more is refused (NL3036) rather than skipped. A
+program whose `main` — or, in a library or a header build, any export —
+reaches more is refused (NL2459), spanned at the first call and naming the
+whole chain to the builtin; nothing changes in a program
+that keeps to it ([LANGUAGE.md](LANGUAGE.md#the-capability-policy)). Under an
+allowlist `exit` is a capability like the others, and `unsafe` can be denied
+but never allowed: importing `nish:unsafe` is the opt-in.
+
+```ts nish:err NL2459 --deny fs.read
+const settings = (): string => readFileSync("settings.txt");
+
+export const main = (): i32 => settings().length;
+```
+
+## Before you say it compiles
+
+Run it. `nish file.ts --json` is one command and it is the only proof.
+
+1. Did you **run the compiler**? Nothing else counts.
+2. Are all conditions `boolean` — no `if (x)` on a number, string or array?
+3. Did you invent a method? Check it against
+   [the builtins list](#the-builtins-in-full).
+4. Is every parameter, return type, field and module constant annotated?
+5. Does every numeric type match exactly — no `i32` meeting `i64`, no literal
+   in an object-literal property or a method argument expecting a width?
+6. Is every `Result` read, and is every `.value` behind an `isOk()`?
+7. Is every nullable narrowed with `!== null` before it is touched?
+8. Did you use `throw`, `try`, `any`, `undefined` or `??` (outside a `T | null`, a chain or `Map.get`), `?.` without a `??`, a cast, a
+   stored or returned callback, a generic *alias*, or `extends`?
+9. Does it reach only what you meant it to? `nish file.ts --emit-capabilities
+   caps.json` lists every capability each function can reach — files, processes,
+   the network, the environment, the clock, entropy, signals, `exit`, C calls —
+   with the call chain that reaches it, and `nish run --capabilities file.ts`
+   prints the one-line summary ([LANGUAGE.md](LANGUAGE.md#capabilities)).
+   A package that must not touch the network says so in `package.json`
+   ([Holding it to its capabilities](#holding-it-to-its-capabilities)).
+10. Must it never panic? Compile with `--deny-panics` (or list the module in
+   `package.json`'s `"nish": { "noPanic": [...] }`): every index, division,
+   signed `+ - *`, `pop`, range entry, `expect` and exiting call it cannot
+   prove is an error
+   naming the guard ([Proving it cannot panic](#proving-it-cannot-panic)); an
+   `uncheckedGet` or `uncheckedSet` behind its `nish:unsafe` import is allowed.
+11. If you are adding to this repository: `npm run check` and the touched
+   `node tests/run.js` sections green locally, every CI `test` shard green
+   ([CLAUDE.md](../CLAUDE.md#definition-of-done)), and a new construct ships a
+   golden `.ll`, an `llvm-as` pass, a native round trip, a negative test, its
+   `LANGUAGE.md` rule and cookbook entry, and a conventional commit message,
+   which is its changelog entry.
+
+Every `ts nish:ok` and `ts nish:err` block on this page is compiled by
+`npm test`, so an example that has gone stale is a failing test rather than a
+program that no longer works.