@amritk/nish 0.10.0 → 0.11.0

package/README.md

@@ -49,22 +49,19 @@ Requirements: Node.js 22.18+ and, to produce binaries, clang (LLVM 18) + lld;
 per-OS install commands are in [docs/INSTALL.md](docs/INSTALL.md).
 
 ```bash
-# Once this is published, the whole install is either of:
-#   npm install -g @amritk/nish
-#   curl -fsSL https://raw.githubusercontent.com/amritk/nish/main/install.sh | sh
+npm install -g @amritk/nish            # or per project: npm i -D @amritk/nish
+npx @amritk/nish --version             # or run it without installing
+# or, with no Node at all:
+curl -fsSL https://raw.githubusercontent.com/amritk/nish/main/install.sh | sh
 # `nish` on the registry is an unrelated package from 2014, so this one is
-# scoped; the command it installs is still `nish`. Nothing is published yet,
-# so take it from a release -- the npm tarball, plus the prebuilt native
-# compiler for your machine, which is what the scoped install would fetch.
-base=https://github.com/amritk/nish/releases/download/v0.4.0
-curl -LO $base/amritk-nish-0.4.0.tgz
-curl -LO $base/amritk-nish-x86_64-linux-0.4.0.tgz    # or the row for your machine
-npm install -g ./amritk-nish-0.4.0.tgz ./amritk-nish-x86_64-linux-0.4.0.tgz
+# scoped; the command it installs is still `nish`. npm fetches the prebuilt
+# native compiler for your machine alongside it.
 ```
 
 > [!NOTE]
-> **Install the pair.** The main package is a launcher and carries no compiler:
-> installed on its own it has nothing to hand over to and says so, exiting 3.
+> **From a release tarball rather than the registry, install the pair.** The
+> main package is a launcher and carries no compiler: installed on its own it
+> has nothing to hand over to and says so, exiting 3.
 > The same is true on a platform this project publishes no binary for — musl,
 > FreeBSD, 32-bit anything — which since 0.6.0 gets a diagnostic naming the four
 > that do rather than the TypeScript compiler under Node that used to ship
@@ -550,4 +547,5 @@ coding agents are in [AGENTS.md](AGENTS.md) and [`.claude/`](.claude/).
 
 ## License
 
-MIT, see [LICENSE](LICENSE).
+MIT, see [LICENSE](LICENSE). Third-party code in the repository keeps its own
+licence; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/docs/AI.md

@@ -111,14 +111,14 @@ rejects. This table is the highest-value part of the page.
 | `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) `` | a `for` loop; there are no function values to pass |
+| `xs.map(f)`, `.filter`, `.reduce`, `.forEach`, `.slice`, `.sort`, `.shift` | `` Unknown method `map` on i32[] (supported: push, pop, indexOf, join) `` | 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` | forbidden | `if (a !== null)` first |
+| `a?.b`, `a ?? b` | forbidden, except `m.get(k) ?? d` | `if (a !== null)` first |
 | `x as T`, `<T>x`, `x!` | `Unsupported expression in Phase 1: AsExpression` | there are no casts; `implements` is the only widening |
 | `any`, `unknown` | forbidden | name the real type |
-| `undefined` | forbidden | `null`, with a `T \| null` 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 |
-| a callback: `xs.forEach(f)`, `(cb: (n: i32) => i32)` | `` Unsupported type `(n: i32) => i32` `` | there are **no function values**; inline the body or write a loop |
+| 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) | `` expected `=`, found `<` `` (a syntax error) | 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 |
@@ -136,7 +136,9 @@ rejects. This table is the highest-value part of the page.
 | `export default f` | `` `export default` / `export =` are not supported `` | `export const f = …` |
 | `export type T = …`, `export enum K` | cannot be exported | declare the alias/enum in each module that needs it |
 | `new Date()`, `Date.now()` | `` Unknown builtin `Date.now` `` | `monotonicNanos()` for elapsed time; there is no wall clock and no calendar |
-| `JSON.parse`, `RegExp`, `Map`, `Set`, `Promise` | unknown / forbidden | none of these exist; write them or restructure |
+| `JSON.parse`, `RegExp`, `Promise` | unknown / forbidden | none of these exist; write them or restructure |
+| `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:
@@ -351,7 +353,8 @@ export const main = (): i32 => {
 ```
 
 - Reading anything off an un-narrowed nullable is an error: narrow with
-  `!== null` first. `?.` and `??` are forbidden outright.
+  `!== null` first. `?.` is forbidden outright, and so is `??`, except after
+  `Map.get` (see [Map and Set](#map-and-set)).
 - 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, and is dropped before a
@@ -373,11 +376,14 @@ 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, and those are forbidden). The `function` keyword is accepted
-  as the legacy spelling and compiles to identical IR.
+  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` ``. No callbacks, no function types, ever.
+  `` 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.
@@ -605,6 +611,115 @@ class Box<T> {
 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. (A plain block: a program
+importing a `nish/` module writes two `.ll` files, so this one is compiled by
+`tests/link/par_map` and `tests/link/par_reduce` instead.)
+
+```ts
+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);
+};
+```
+
+- **`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. 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.
+- **The result is a number, a `boolean` or an enum.** A string or an object
+  made on another thread would be freed with it.
+- **`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 cheap body is divided only past about a million elements, 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
+```
+
 ### Calling C
 
 `declare function name(params): T;` declares a C function this program calls but
@@ -889,8 +1004,8 @@ export const main = (): i32 => {
 - `++` / `--` 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 `+`.
+- **Forbidden**: `,` `?.` `in` `instanceof` `typeof` `delete` `void expr`
+  `==` `!=` `**` unary `+`, and `??` on anything but 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
@@ -956,6 +1071,94 @@ bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
 **Arena.** `Arena.mark()`, `Arena.release(m)`, `Arena.reset()`, `Arena.used()`
 — see below.
 
+### 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) {
+}
+```
+
 ## Memory
 
 There is **no garbage collector and no `free`**, and nothing about this changes
@@ -1017,8 +1220,9 @@ 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** — neither exists. Use parallel arrays with a linear scan, or
-an array indexed by a small integer key, and write the lookup out.
+**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.
 
 **Shared behaviour over several shapes** — there is no inheritance and no
 dispatch. Give each class the interface's fields **first**, `implements` it,
@@ -1064,8 +1268,8 @@ Run it. `nish file.ts --json` is one command and it is the only proof.
    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`, `?.`, `??`, a cast, a
-   callback, a generic *alias*, or `extends`?
+8. Did you use `throw`, `try`, `any`, `undefined` or `??` (outside `Map.get`), `?.`, a cast, a
+   stored or returned callback, a generic *alias*, or `extends`?
 9. If you are adding to this repository: `npm run check` and `npm test` green,
    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

package/docs/INSTALL.md

@@ -234,12 +234,13 @@ routes are
 If you need one of these to be a first-class install, that is the conversation
 to have on the issue tracker rather than a workaround to discover here.
 
-**Nothing is published to the registry yet.** The installer is built and
-tested, and what is left is a person publishing a release under it, which
-[docs/wp12-release.md](wp12-release.md#release-procedure) step 4 is about.
-Until that happens, install from a release.
+**On the registry from 0.10.0.** Every release publishes the main package and
+its platform packages to npm from `release.yml`, by trusted publishing
+([docs/wp12-release.md](wp12-release.md#release-procedure) step 4), so
+`npm install -g @amritk/nish` is the whole install. The rest of this section is
+for a machine that cannot reach the registry, or a release before 0.10.0.
 
-From a release tarball on GitHub — the same package `npm publish` would upload,
+From a release tarball on GitHub — the same package `npm publish` uploads,
 carried by the release instead of the registry. The `Release` workflow attaches
 the npm tarball to the release it builds for a `v*` tag. `npm pack` names it
 after `package.json#name`, so it is `amritk-nish-<version>.tgz` from 0.4.0 on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Nish: an ahead-of-time compiler from a static subset of TypeScript to LLVM IR",
   "license": "MIT",
   "type": "module",
@@ -74,10 +74,10 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@amritk/nish-x86_64-linux": "0.10.0",
-    "@amritk/nish-aarch64-linux": "0.10.0",
-    "@amritk/nish-aarch64-darwin": "0.10.0",
-    "@amritk/nish-x86_64-darwin": "0.10.0"
+    "@amritk/nish-x86_64-linux": "0.11.0",
+    "@amritk/nish-aarch64-linux": "0.11.0",
+    "@amritk/nish-aarch64-darwin": "0.11.0",
+    "@amritk/nish-x86_64-darwin": "0.11.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",

package/runtime/LICENSE-ryu

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/runtime/nish.d.ts

@@ -25,6 +25,15 @@
  * So a program that `tsc` accepts may still be rejected by `nish`; the
  * reverse should never happen, and a case where it does is a bug in this file.
  * `docs/LANGUAGE.md` is the normative description.
+ *
+ * **`Map` and `Set` are not declared here**, although `nish` has them as
+ * globals: the `"lib": ["ES2022"]` a program is checked against already
+ * declares JavaScript's, and a second declaration would clash with it.
+ * `nish`'s are that surface less what it defers — no `entries`, no `forEach`,
+ * no `for...of` over a `Map` itself — with `keys()` and `values()` admitted
+ * only as the iterable of a `for...of`, and `get`'s `V | undefined` only as a
+ * `const`'s initialiser, the left of `??` or an operand of `=== undefined`,
+ * none of which `tsc` can know (docs/LANGUAGE.md -> `Map` and `Set`).
  */
 
 // ---- Numeric widths (docs/LANGUAGE.md -> Types) ------------------------------

package/runtime/nish.h

@@ -179,7 +179,15 @@ void nish_append_file(const nish_str *path, const nish_str *data);
  * `push` that grows it copies the elements into the arena and leaves your
  * buffer behind; the callee must not retain the pointer beyond the call.
  * A returned array lives in the arena (valid until the next reset/release):
- * copy `len` elements out of `data` before recycling. */
+ * copy `len` elements out of `data` before recycling.
+ *
+ * An array field stored inside its object (`self/inline_arrays.ts`) is this
+ * header followed by its `K` slots, `struct { nish_array h; T slots[K]; }`
+ * with `h.data == (char *)slots` and `h.cap == K`; `self/runtime.ts`'s
+ * `ARRAY_TYPE` and `self/structs.ts`'s `INLINE_HEADER_BYTES` are the same 24
+ * bytes, and `tests/layout/inline_array.c` holds the three to it. It only
+ * happens where no header, `.d.ts` or N-API shim describes the class, so a
+ * host that includes a generated header never meets one. */
 typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array;
 /* A fresh arena array of `len` uninitialised elements (`len == cap`), for a
  * host that wants the runtime to own the storage (the wasm loader does).

package/runtime/runtime.c

@@ -277,6 +277,13 @@ nish_str *nish_str_from_u64(uint64_t v) { return str_from_digits(v, 0); }
 
 /* ---- Shortest round-trip digits (Ryu)
 
+   Adapted from Ryu (https://github.com/ulfjack/ryu), ryu/d2s.c and
+   ryu/common.h. Copyright 2018 Ulf Adams. Used under the Boost Software
+   License, Version 1.0; see runtime/LICENSE-ryu. The code from here to the end
+   of `nish_shortest_digits` follows upstream's `d2d()` and its helpers, which
+   is why it keeps their names, constants and comments; the two tables are
+   regenerated by scripts/gen-pow5-tables.py rather than copied.
+
    `String(x)` in JavaScript prints the *fewest* digits that read back as the
    same double, and the language promises that spelling. Reaching it by asking
    snprintf for k digits and strtod whether they round-trip -- which is what
@@ -1079,7 +1086,9 @@ nish_str *nish_str_from_f64(double v) {
   return nish_str_new(out, o - out);
 }
 
-/* ---- Math.random: xorshift64*, seeded lazily from time and pid.
+/* ---- Math.random: xorshift64*, seeded lazily from time and pid. The shifts
+   and the multiplier are Marsaglia's and Vigna's published constants, which
+   are public domain.
    Thread-local under -DNISH_THREADS (WP20 T0 §3.2): a shared seed word is a
    race, and a per-thread one also makes each worker's stream its own rather
    than an interleaving of everyone's. Two threads that start in the same

package/scripts/gen-pow5-tables.py

@@ -8,6 +8,11 @@ Prints the C to stdout; paste it over the `NISH_POW5_INV_SPLIT` and
 the ~10 KB of constants in the runtime are *derived*, with exact integer
 arithmetic, rather than transcribed from somewhere -- so a reader can check
 them rather than trust them. See docs/wp15-performance.md section 7a.
+
+The code that reads the tables is adapted from Ryu (ryu/d2s.c and
+ryu/common.h, Copyright 2018 Ulf Adams) under the Boost Software License,
+Version 1.0; runtime/LICENSE-ryu has the text and THIRD_PARTY_NOTICES.md the
+entry.
 """
 INV_BITCOUNT = 125
 BITCOUNT = 125

package/std/README.md

@@ -1,10 +1,10 @@
 # `std/` — the standard library
 
 Nish modules written in Nish, for Nish programs to import. There is no magic
-here and nothing the compiler knows about: a module in this directory is an
-ordinary Nish source file, compiled as part of whatever program imports it,
-and subject to the same rules as `examples/` or `self/`
-([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
+here and — with two exceptions, `threads.ts` and `collections.ts` — nothing
+the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
+whatever program imports it, and subject to the same rules as `examples/` or
+`self/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
 
 | Module | What it is |
 | --- | --- |
@@ -12,6 +12,8 @@ and subject to the same rules as `examples/` or `self/`
 | [`text.ts`](./text.ts) | the string operations a program would otherwise write inline: `splitLines`, `splitWhitespace`, `trim` and its halves, `contains`, `replaceAll`, and `firstDifference` over two arrays of lines |
 | [`json.ts`](./json.ts) | `jsonField(object, name)`: the value of one field of one flat JSON object, which is the shape the compiler's own `--json` diagnostics have. A reader and not a parser — it answers text, answers `null` for a field that is not there, and does not validate |
 | [`pair.ts`](./pair.ts) | `Pair<A, B>`: an interface with `first` and `second`, for a function that answers two values from one call. A type and nothing else — the caller writes an object literal at the return — and for returning two values rather than storing them side by side |
+| [`collections.ts`](./collections.ts) | the global `Map<K, V>` and `Set<T>`: insertion-ordered tables whose buckets carry a hash fingerprint beside the entry index and whose entries keep their full hash, so every `get`, `set`, `add`, `has` and `delete` is one probe. `get` is not a method here: its `V | undefined` never crosses a call, so the compiler lowers it to `probe` and, where the key was found, `valueAt`. Nor are `keys()` and `values()`: an iterator is not a value, so a `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or `valueAt`, and `walkClose`, and a count of live walks defers compaction until no loop is walking the table. A program never imports it: naming `Map` or `Set` loads it, and the compiler emits what a module uses of it into that module ([`docs/wp32-map.md`](../docs/wp32-map.md), [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)). Its `hashKey` and `sameKey` are lowered by the compiler per key type |
+| [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
 ## How a program imports it
 

package/std/collections.ts

@@ -0,0 +1,548 @@
+/**
+ * `std/collections` — the global `Map` and `Set` (docs/wp32-map.md).
+ *
+ * A program does not import this module. Naming `Map` or `Set` is what loads
+ * it, unless the module declares or imports a `Map` or `Set` of its own, and
+ * the compiler emits every instance used, and every function here that it
+ * reaches, into the module that uses it as `internal` functions. So this file
+ * writes no `.ll` of its own, and a one-file program that names `Map` is still
+ * one module (§4.1). Under Node, and under `tsc`, `Map` and `Set` are the
+ * platform's, so nothing here runs there.
+ *
+ * **The layout is §2's.** Entries sit in insertion order in parallel arrays,
+ * `entryKeys`, `entryValues` and `entryHashes`, and `entryHashes` holds the
+ * full 32-bit hash of each. The bucket table `slots` is open addressing with
+ * linear probing, and a bucket is one `u32`:
+ *
+ *     bits 31..24   the top eight bits of the key's hash (the fingerprint)
+ *     bits 23..0    the entry's index plus one
+ *
+ * An empty bucket is 0. A deleted entry's bucket is `0x01000000` (16777216),
+ * fingerprint 1 and index field 0, which no live entry has; its stored hash is
+ * set to 0, which is why a computed hash of 0 is moved to 1. A probe reads the
+ * entry arrays only when a bucket's fingerprint matches, and compares the
+ * stored hash before the key, so a miss almost never touches a key, and a hit
+ * compares one. Growth and compaction re-file the buckets from the stored
+ * hashes and never hash a key again.
+ *
+ * **Every operation is one probe.** `probe` answers a packed `i64`: the entry
+ * it found and the bucket that points at it, or the empty bucket it stopped at
+ * and the key's hash. `set` and `add` insert through that result, and nothing
+ * here asks `has` and then `set`. `probe`, `valueAt`, `setValueAt` and
+ * `insertAt` are the pieces a fused lookup writes through, and they write
+ * nothing but what their names say: `probe` writes no memory at all.
+ *
+ * A program sees only the JavaScript members (§7), `size`, `get`, `set`/`add`,
+ * `has`, `delete` and `clear`, and `keys()` and `values()` as the iterable of
+ * a `for...of`. Neither `get` nor the iterators has a method here: `get`'s
+ * `V | undefined` never crosses a call, so the compiler lowers it to `probe`
+ * and, where found, `valueAt` (§3.2), and an iterator is not a value, so a
+ * `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or
+ * `valueAt`, and `walkClose` (§6.2). The rest of this file is refused by name
+ * outside it.
+ */
+
+/**
+ * The most entries a table holds, dead ones included until a rebuild: 2^24 - 1,
+ * what the 24-bit index field holds as an index plus one. Node's own `Map` and
+ * `Set` hold one more, 2^24, and throw on the next insert.
+ */
+const INDEX_CAP: i32 = 16777215;
+
+/** The first bucket count. A power of two, as every bucket count is. */
+const INITIAL_SLOTS: i32 = 8;
+
+/**
+ * The key's hash, never 0: FNV-1a over a string's bytes, murmur3's `fmix32`
+ * for an integer of 32 bits or fewer, `fmix64` folded to 32 bits for a 64-bit
+ * integer, a float (normalised first, so that -0 and +0, and every NaN, hash
+ * alike) and a class instance's address (§5.2). FNV, MurmurHash3 and their
+ * constants are public domain.
+ *
+ * The body is never emitted. Every call is lowered in place, per key type, by
+ * `self/emit_map.ts`; the constant is what the checker and the whole-program
+ * facts see, and the facts of the function that calls it are what decide its
+ * attributes, because every call is inside a probe that reads the table.
+ */
+const hashKey = <K>(key: K): u32 => 1;
+
+/**
+ * JavaScript's key equality, SameValueZero: `===`, except that NaN equals NaN.
+ * Lowered in place per key type as well: `nish_str_eq` for a string, one
+ * `icmp` for an integer, a boolean, an enum and a class instance, and for a
+ * float `a == b` or both unordered.
+ */
+const sameKey = <K>(a: K, b: K): boolean => a === b;
+
+/** The first bucket for `h`: its low bits, folded with the high half. */
+const homeBucket = (h: u32, mask: i32): i32 => toI32(h ^ (h >>> 16)) & mask;
+
+/** The bucket word for entry `index` of hash `h`. */
+const slotWord = (h: u32, index: i32): u32 => ((h >>> 24) << 24) | toU32(index + 1);
+
+/** A probe that found entry `index`, pointed at by `bucket`. Never negative. */
+const foundAt = (bucket: i32, index: i32): i64 => (toI64(bucket) << 32) | toI64(index);
+
+/** A probe that stopped at the empty `bucket` for hash `h`. Always negative. */
+const absentAt = (bucket: i32, h: u32): i64 => toI64(-1) - ((toI64(bucket) << 32) | toI64(h));
+
+/**
+ * The one probe, for both classes: linear probing from `h`'s home bucket to
+ * the bucket pointing at `key`, or to the first empty one. A tombstone is
+ * walked past — its index field is 0, so its entry index is -1 and the range
+ * test turns it away — and the load bound keeps a quarter of the buckets
+ * empty, so the walk ends.
+ */
+const probeTable = <K>(slots: u32[], mask: i32, hashes: u32[], keys: K[], key: K): i64 => {
+  const h = hashKey(key);
+  const fingerprint = h >>> 24;
+  let bucket = homeBucket(h, mask);
+  // The length is read in the condition rather than once: the key compare is
+  // a call, and a call ends every length fact the bounds proof holds.
+  while (bucket >= 0 && bucket < toI32(slots.length)) {
+    const word = slots[bucket];
+    if (word === 0) {
+      return absentAt(bucket, h);
+    }
+    if (word >>> 24 === fingerprint) {
+      const at = toI32(word & 16777215) - 1;
+      if (at >= 0 && at < toI32(hashes.length) && hashes[at] === h && at < toI32(keys.length) && sameKey(keys[at], key)) {
+        return foundAt(bucket, at);
+      }
+    }
+    bucket = (bucket + 1) & mask;
+  }
+  panic("collections: a probe ran out of buckets");
+};
+
+/**
+ * Point the first empty bucket from `h`'s home at entry `index`. A rebuild's
+ * re-filing: every key is already known to be distinct, so no key is
+ * compared, and the stored hash is all it needs.
+ */
+const fileEntry = (slots: u32[], mask: i32, h: u32, index: i32): void => {
+  const word = slotWord(h, index);
+  let bucket = homeBucket(h, mask);
+  while (bucket >= 0 && bucket < toI32(slots.length)) {
+    if (slots[bucket] === 0) {
+      slots[bucket] = word;
+      return;
+    }
+    bucket = (bucket + 1) & mask;
+  }
+};
+
+/** Slide the live entries of `items` down over the dead ones, in order, and drop the tail. */
+const compactEntries = <T>(items: T[], hashes: u32[]): void => {
+  const used = toI32(items.length);
+  let to: i32 = 0;
+  for (let from: i32 = 0; from < used && from < toI32(hashes.length); from++) {
+    if (hashes[from] !== 0 && to >= 0 && to < used && from < toI32(items.length)) {
+      items[to] = items[from];
+      to++;
+    }
+  }
+  while (toI32(items.length) > to) {
+    items.pop();
+  }
+};
+
+/** The stored hashes compacted the same way, last, since the two above read them. */
+const compactHashes = (hashes: u32[]): void => {
+  const used = toI32(hashes.length);
+  let to: i32 = 0;
+  for (let from: i32 = 0; from < used; from++) {
+    const h = hashes[from];
+    if (h !== 0 && to >= 0 && to < used) {
+      hashes[to] = h;
+      to++;
+    }
+  }
+  while (toI32(hashes.length) > to) {
+    hashes.pop();
+  }
+};
+
+/**
+ * The bucket table after a rebuild of `live` entries out of `used`. More than
+ * half dead compacts at the same size and clears the table in place — a new
+ * array would leave the old one in the arena, once per compaction, which a
+ * table that churns forever cannot afford (§6.1). Otherwise it doubles, and
+ * the table never shrinks.
+ */
+const rebuiltSlots = (slots: u32[], live: i32, used: i32): u32[] => {
+  const n = toI32(slots.length);
+  if (live * 2 < used) {
+    clearSlots(slots);
+    return slots;
+  }
+  return new Array<u32>(n * 2);
+};
+
+/**
+ * Re-file every live entry from its stored hash. After a compaction none is
+ * dead; after a rebuild during a walk, which does not compact, a dead entry
+ * keeps its place and takes no bucket, since no probe can find it.
+ */
+const refile = (slots: u32[], hashes: u32[]): void => {
+  const mask = toI32(slots.length) - 1;
+  for (let i: i32 = 0; i < toI32(hashes.length); i++) {
+    const h = hashes[i];
+    if (h !== 0) {
+      fileEntry(slots, mask, h, i);
+    }
+  }
+};
+
+/**
+ * `delete`'s write through a found probe result: the bucket becomes a
+ * tombstone and the entry's stored hash 0. The key and value stay in the entry
+ * until a rebuild compacts them away (§6.1).
+ */
+const killEntry = (slots: u32[], hashes: u32[], found: i64): void => {
+  const at = toI32(found);
+  const bucket = toI32(found >> 32);
+  if (bucket >= 0 && bucket < toI32(slots.length)) {
+    slots[bucket] = 16777216;
+  }
+  if (at >= 0 && at < toI32(hashes.length)) {
+    hashes[at] = 0;
+  }
+};
+
+/**
+ * Zero every element in place: the buckets, which emptying a table and
+ * compacting one both start with, and under a walk the stored hashes, which
+ * is how `clear` marks every entry dead without moving one (§6.1).
+ */
+const clearSlots = (slots: u32[]): void => {
+  for (let i: i32 = 0; i < toI32(slots.length); i++) {
+    slots[i] = 0;
+  }
+};
+
+/**
+ * The index of the first live entry at `from` or after it, or -1 when there is
+ * none: a `for...of` walk's step. It reads the entry count on every call, so
+ * an entry appended during the walk is reached, and it skips a dead entry,
+ * whose stored hash is 0, so a key deleted before the walk reaches it is not
+ * visited (docs/wp32-map.md §6.2).
+ */
+const nextLive = (hashes: u32[], from: i32): i32 => {
+  for (let i: i32 = from; i >= 0 && i < toI32(hashes.length); i++) {
+    if (hashes[i] !== 0) {
+      return i;
+    }
+  }
+  return -1;
+};
+
+/** Drop every element of `items`, keeping its capacity. */
+const truncate = <T>(items: T[]): void => {
+  while (toI32(items.length) > 0) {
+    items.pop();
+  }
+};
+
+/**
+ * Point bucket `bucket`, the empty one an absent probe stopped at, at the entry
+ * just appended as index `used - 1`; or, when a rebuild made room first and
+ * moved the buckets (`bucket` is -1), file it from its hash.
+ */
+const fileAppended = (slots: u32[], mask: i32, bucket: i32, h: u32, used: i32): void => {
+  if (bucket >= 0 && bucket < toI32(slots.length)) {
+    slots[bucket] = slotWord(h, used - 1);
+  } else {
+    fileEntry(slots, mask, h, used - 1);
+  }
+};
+
+/**
+ * A key-value table in insertion order, with JavaScript's semantics: keys are
+ * compared by SameValueZero, a key set again keeps its place, and a deleted key
+ * set again goes to the end.
+ */
+// biome-ignore lint/suspicious/noShadowRestrictedNames: this is the global `Map`, which the compiler loads for a program that names it
+export class Map<K, V> {
+  /** How many entries are live. The one field a program may read, and it may not write it. */
+  size: number = 0;
+  /** Bucket -> fingerprint and entry index plus one; see the header. */
+  slots: u32[];
+  /** `slots.length - 1`: the table is a power of two. */
+  mask: i32 = 7;
+  /** Live entries, as an `i32` for the load and compaction arithmetic. */
+  live: i32 = 0;
+  entryKeys: K[];
+  entryValues: V[];
+  /** The full hash of each entry; 0 once the entry is deleted. */
+  entryHashes: u32[];
+  /**
+   * How many `for...of` loops are walking the table now. While it is above 0
+   * a rebuild doubles rather than compacts, and `clear` marks entries dead
+   * rather than truncating, so no entry moves under a walk's cursor (§6.2).
+   */
+  walks: i32 = 0;
+
+  constructor() {
+    this.slots = new Array<u32>(INITIAL_SLOTS);
+    this.entryKeys = [];
+    this.entryValues = [];
+    this.entryHashes = [];
+  }
+
+  /** The packed probe result for `key`: see `probeTable`, `foundAt` and `absentAt`. */
+  probe(key: K): i64 {
+    return probeTable(this.slots, this.mask, this.entryHashes, this.entryKeys, key);
+  }
+
+  has(key: K): boolean {
+    return this.probe(key) >= 0;
+  }
+
+  /** Set `key` to `value`, in place when it is there and at the end when it is not: one probe. */
+  set(key: K, value: V): Map<K, V> {
+    const found = this.probe(key);
+    if (found >= 0) {
+      this.setValueAt(toI32(found), value);
+    } else {
+      this.insertAt(found, key, value);
+    }
+    return this;
+  }
+
+  delete(key: K): boolean {
+    const found = this.probe(key);
+    if (found < 0) {
+      return false;
+    }
+    killEntry(this.slots, this.entryHashes, found);
+    this.live = this.live - 1;
+    this.size = this.size - 1;
+    return true;
+  }
+
+  /**
+   * Empty the table in place: the buckets are zeroed and the entries
+   * truncated, or, while a loop walks the table, marked dead and kept (§6.1).
+   */
+  clear(): void {
+    clearSlots(this.slots);
+    if (this.walks > 0) {
+      clearSlots(this.entryHashes); // every entry dead, and the count kept
+    } else {
+      truncate(this.entryKeys);
+      truncate(this.entryValues);
+      truncate(this.entryHashes);
+    }
+    this.live = 0;
+    this.size = 0;
+  }
+
+  /**
+   * The four pieces a `for...of` over `keys()` or `values()` is lowered to
+   * (`emitForOf`, docs/wp32-map.md §6.2): `walkOpen` where the loop is
+   * entered, `walkNext` for the first live entry and after each pass,
+   * `keyAt` or `valueAt` for the loop variable, and `walkClose` on every edge
+   * that leaves the loop. Two stores a loop, and none per entry.
+   */
+  walkOpen(): void {
+    this.walks = this.walks + 1;
+  }
+
+  walkNext(from: i32): i32 {
+    return nextLive(this.entryHashes, from);
+  }
+
+  walkClose(): void {
+    this.walks = this.walks - 1;
+  }
+
+  /** The key of entry `index`, which `walkNext` answered. */
+  keyAt(index: i32): K {
+    if (index < 0 || index >= toI32(this.entryKeys.length)) {
+      panic("Map: no entry at this index");
+    }
+    return this.entryKeys[index];
+  }
+
+  /** The value of the entry a probe found, or a walk reached. */
+  valueAt(index: i32): V {
+    if (index < 0 || index >= toI32(this.entryValues.length)) {
+      panic("Map: no entry at this index");
+    }
+    return this.entryValues[index];
+  }
+
+  /** Overwrite the value of the entry a probe found; it keeps its place. */
+  setValueAt(index: i32, value: V): void {
+    if (index >= 0 && index < toI32(this.entryValues.length)) {
+      this.entryValues[index] = value;
+    }
+  }
+
+  /** Append an entry for `key` at the empty bucket an absent probe result names, reusing its hash. */
+  insertAt(absent: i64, key: K, value: V): void {
+    const packed = -1 - absent;
+    let bucket = toI32(packed >> 32);
+    const h = toU32(packed);
+    if (toI32(this.entryKeys.length) >= INDEX_CAP) {
+      // Dead entries hold the cap: compact them away, then find the bucket
+      // again. A walk defers compaction, so under one the cap is full.
+      if (this.live >= INDEX_CAP || this.walks > 0) {
+        panic("Map maximum size exceeded");
+      }
+      this.rebuild();
+      bucket = -1;
+    }
+    this.entryKeys.push(key);
+    this.entryValues.push(value);
+    this.entryHashes.push(h);
+    this.live = this.live + 1;
+    this.size = this.size + 1;
+    // Every entry takes a bucket, live or dead, until a rebuild, which files
+    // the new entry with the rest; otherwise it takes the bucket the probe found.
+    const used = toI32(this.entryKeys.length);
+    if (used * 4 > toI32(this.slots.length) * 3) {
+      this.rebuild();
+    } else {
+      fileAppended(this.slots, this.mask, bucket, h, used);
+    }
+  }
+
+  /**
+   * Compact or double, then re-file the buckets from the stored hashes (§6.1).
+   * While a loop walks the table it always doubles and moves no entry, and the
+   * first rebuild after the walk compacts (§6.2).
+   */
+  rebuild(): void {
+    const used = toI32(this.entryKeys.length);
+    const walking = this.walks > 0;
+    const slots = rebuiltSlots(this.slots, walking ? used : this.live, used);
+    if (!walking && this.live < used) {
+      compactEntries(this.entryKeys, this.entryHashes);
+      compactEntries(this.entryValues, this.entryHashes);
+      compactHashes(this.entryHashes);
+    }
+    this.slots = slots;
+    this.mask = toI32(slots.length) - 1;
+    refile(slots, this.entryHashes);
+  }
+}
+
+/** A set of keys in insertion order: `Map`'s table with no values, and the same probe. */
+// biome-ignore lint/suspicious/noShadowRestrictedNames: this is the global `Set`, which the compiler loads for a program that names it
+export class Set<T> {
+  /** How many elements are live. The one field a program may read, and it may not write it. */
+  size: number = 0;
+  slots: u32[];
+  mask: i32 = 7;
+  live: i32 = 0;
+  entryKeys: T[];
+  entryHashes: u32[];
+  /** `Map`'s walk count: how many `for...of` loops are walking the table now. */
+  walks: i32 = 0;
+
+  constructor() {
+    this.slots = new Array<u32>(INITIAL_SLOTS);
+    this.entryKeys = [];
+    this.entryHashes = [];
+  }
+
+  probe(key: T): i64 {
+    return probeTable(this.slots, this.mask, this.entryHashes, this.entryKeys, key);
+  }
+
+  has(key: T): boolean {
+    return this.probe(key) >= 0;
+  }
+
+  /** Add `key` at the end when it is not there already: one probe. */
+  add(key: T): Set<T> {
+    const found = this.probe(key);
+    if (found < 0) {
+      this.insertAt(found, key);
+    }
+    return this;
+  }
+
+  delete(key: T): boolean {
+    const found = this.probe(key);
+    if (found < 0) {
+      return false;
+    }
+    killEntry(this.slots, this.entryHashes, found);
+    this.live = this.live - 1;
+    this.size = this.size - 1;
+    return true;
+  }
+
+  clear(): void {
+    clearSlots(this.slots);
+    if (this.walks > 0) {
+      clearSlots(this.entryHashes); // every entry dead, and the count kept
+    } else {
+      truncate(this.entryKeys);
+      truncate(this.entryHashes);
+    }
+    this.live = 0;
+    this.size = 0;
+  }
+
+  /** `Map`'s walk: `for (const x of s)`, `s.keys()` and `s.values()` are all this one. */
+  walkOpen(): void {
+    this.walks = this.walks + 1;
+  }
+
+  walkNext(from: i32): i32 {
+    return nextLive(this.entryHashes, from);
+  }
+
+  walkClose(): void {
+    this.walks = this.walks - 1;
+  }
+
+  keyAt(index: i32): T {
+    if (index < 0 || index >= toI32(this.entryKeys.length)) {
+      panic("Set: no entry at this index");
+    }
+    return this.entryKeys[index];
+  }
+
+  insertAt(absent: i64, key: T): void {
+    const packed = -1 - absent;
+    let bucket = toI32(packed >> 32);
+    const h = toU32(packed);
+    if (toI32(this.entryKeys.length) >= INDEX_CAP) {
+      if (this.live >= INDEX_CAP || this.walks > 0) {
+        panic("Set maximum size exceeded");
+      }
+      this.rebuild();
+      bucket = -1;
+    }
+    this.entryKeys.push(key);
+    this.entryHashes.push(h);
+    this.live = this.live + 1;
+    this.size = this.size + 1;
+    // Every entry takes a bucket, live or dead, until a rebuild, which files
+    // the new entry with the rest; otherwise it takes the bucket the probe found.
+    const used = toI32(this.entryKeys.length);
+    if (used * 4 > toI32(this.slots.length) * 3) {
+      this.rebuild();
+    } else {
+      fileAppended(this.slots, this.mask, bucket, h, used);
+    }
+  }
+
+  rebuild(): void {
+    const used = toI32(this.entryKeys.length);
+    const walking = this.walks > 0;
+    const slots = rebuiltSlots(this.slots, walking ? used : this.live, used);
+    if (!walking && this.live < used) {
+      compactEntries(this.entryKeys, this.entryHashes);
+      compactHashes(this.entryHashes);
+    }
+    this.slots = slots;
+    this.mask = toI32(slots.length) - 1;
+    refile(slots, this.entryHashes);
+  }
+}

package/std/threads.ts

@@ -0,0 +1,150 @@
+/**
+ * `std/threads` — data parallelism, and nothing else (docs/wp29-thread-surface.md §4.1).
+ *
+ *     import { parallelMapInto, parallelReduce } from "nish/threads";
+ *
+ *     parallelMapInto(src, dst, (x) => x * 3);
+ *     const total = parallelReduce(src, (a, b) => a + b, 0);
+ *
+ * **What is written here is the meaning, not the implementation.** Each body
+ * below is the sequential program, and it is what runs under Node, what
+ * `npm run check` type-checks, and what the compiler checks the call against.
+ * The compiler then recognises the two exported templates by module and name
+ * and lowers an instance of either onto `nish_parallel_range`
+ * (runtime/runtime_parallel.c): it replaces the one call that walks the whole
+ * range — `mapRange` for a map, `reduceBlocks` for a reduce — with a region that
+ * hands each thread a contiguous piece of it, and emits the rest of the body as
+ * written. So the length check, its message and the order a reduce combines in
+ * are this file's, whichever way the program is compiled.
+ *
+ * What makes the region safe is checked at the call, not trusted
+ * (docs/LANGUAGE.md, "Data parallelism"): the function passed as `f` may write
+ * nothing its caller could observe, may allocate only temporaries it drops
+ * before it returns — they are given back after every element — `dst` may not
+ * be reachable from an element of `src`, and the result type is a number or a
+ * `boolean`. Importing this module compiles the program with `--threads`,
+ * because every worker needs an arena of its own.
+ *
+ * A reduce is deterministic. `src` is split into `min(64, ceil(n / BLOCK))`
+ * blocks, each block is folded from `identity`, and the block results are
+ * combined left to right — here, on one thread, and by the compiled program on
+ * any number of them — so an `f64` sum is the same bits on one core or sixty
+ * four. That needs `f` to be associative and `identity` to be its identity,
+ * which the checker enforces for an arrow whose body is one operator on its two
+ * parameters and cannot see through a named function.
+ */
+
+/**
+ * Elements per block of a reduce: 2^20, about a millisecond of simple work
+ * (docs/wp20-threads.md §8e). It decides the blocking, and so the answer's
+ * bits: an array this short is one block, folded as the loop it would have
+ * been. It is independent of the map's grain (`mapGrain` in
+ * `self/parallel.ts`), which decides only how a map is divided and may
+ * change without changing any result; this one may not.
+ */
+const BLOCK: i32 = 1048576;
+
+/** The most blocks a reduce is split into: the partitioner's own ceiling on threads. */
+const MAX_BLOCKS: i32 = 64;
+
+/**
+ * Writes `f(src[i])` into `dst[i]` for every `i` in `[lo, hi)`: one thread's
+ * share of a map. Each length is read in the loop condition and `dst`'s again
+ * after the call, because a call ends every length fact the bounds proof holds
+ * (docs/LANGUAGE.md, "Arrays") and this is what keeps both accesses unchecked.
+ * The caller has already checked that the range is inside both arrays, so
+ * neither test is ever the one that stops the loop.
+ */
+const mapRange = <T, U>(src: T[], dst: U[], f: (x: T) => U, lo: i32, hi: i32): void => {
+  for (let i: i32 = lo; i >= 0 && i < hi && i < toI32(src.length); i++) {
+    const y = f(src[i]);
+    if (i < toI32(dst.length)) {
+      dst[i] = y;
+    }
+  }
+};
+
+/** `f` folded over `src[lo..hi)` from `identity`: one block of a reduce. */
+const reduceRange = <T>(src: T[], f: (acc: T, x: T) => T, identity: T, lo: i32, hi: i32): T => {
+  let acc = identity;
+  for (let i: i32 = lo; i >= 0 && i < hi && i < toI32(src.length); i++) {
+    acc = f(acc, src[i]);
+  }
+  return acc;
+};
+
+/** How many blocks a reduce over `n` elements is split into: `min(MAX_BLOCKS, ceil(n / BLOCK))`. */
+const reduceBlockCount = (n: i32): i32 => {
+  const wanted: i32 = toI32((toI64(n) + toI64(BLOCK) - 1) / toI64(BLOCK));
+  return wanted < MAX_BLOCKS ? wanted : MAX_BLOCKS;
+};
+
+/** Where block `k` of `blocks` over `n` elements starts; block `blocks` starts at `n`. */
+const reduceBlockStart = (n: i32, blocks: i32, k: i32): i32 => toI32((toI64(n) * toI64(k)) / toI64(blocks));
+
+/** Folds blocks `[lo, hi)` of `src` into `partials`, one result per block: one thread's share of a reduce. */
+const reduceBlocks = <T>(
+  src: T[],
+  f: (acc: T, x: T) => T,
+  identity: T,
+  partials: T[],
+  lo: i32,
+  hi: i32
+): void => {
+  const n: i32 = toI32(src.length);
+  const blocks: i32 = toI32(partials.length);
+  for (let k: i32 = lo; k >= 0 && k < hi && k < blocks; k++) {
+    const partial = reduceRange(
+      src,
+      f,
+      identity,
+      reduceBlockStart(n, blocks, k),
+      reduceBlockStart(n, blocks, k + 1)
+    );
+    if (k < toI32(partials.length)) {
+      partials[k] = partial;
+    }
+  }
+};
+
+/**
+ * The panic of a map whose `dst` is shorter than its `src`. A function of its
+ * own so that the message it builds is its allocation and not the map's: an
+ * allocation anywhere in `parallelMapInto` would give every call an arena mark
+ * and release, which is most of what a map over a few elements costs.
+ */
+const dstTooShort = (have: i32, want: i32): void => {
+  panic(`parallelMapInto: dst has ${have} elements and src has ${want}`);
+};
+
+/**
+ * `dst[i] = f(src[i])` for every index of `src`, on as many threads as the
+ * machine has and the length is worth. `dst` must be at least as long as
+ * `src`, which is checked once, before any element is written.
+ */
+export const parallelMapInto = <T, U>(src: T[], dst: U[], f: (x: T) => U): void => {
+  const n: i32 = toI32(src.length);
+  if (toI32(dst.length) < n) {
+    dstTooShort(toI32(dst.length), n);
+  }
+  mapRange(src, dst, f, 0, n);
+};
+
+/**
+ * `f` folded over `src`, blockwise from `identity` and then left to right over
+ * the blocks, so the answer does not depend on how many threads computed it.
+ * An empty `src` answers `identity`.
+ */
+export const parallelReduce = <T>(src: T[], f: (acc: T, x: T) => T, identity: T): T => {
+  const blocks: i32 = reduceBlockCount(toI32(src.length));
+  if (blocks === 0) {
+    return identity;
+  }
+  const partials = new Array<T>(blocks);
+  reduceBlocks(src, f, identity, partials, 0, blocks);
+  let acc = partials[0];
+  for (let k: i32 = 1; k < toI32(partials.length); k++) {
+    acc = f(acc, partials[k]);
+  }
+  return acc;
+};