@amritk/nish-x86_64-linux 0.10.0 → 0.11.0

package/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-x86_64-linux",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The @amritk/nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

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/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;
+};