@amritk/nish 0.11.0 → 0.13.0

package/docs/AI.md

@@ -37,6 +37,7 @@ and it is the only authority.
 nish program.ts --json            # one JSON object per diagnostic, on stdout
 nish program.ts -o out.ll         # emit LLVM IR
 nish program.ts --link prog       # build a native binary (needs clang)
+nish run program.ts a b           # build into a cache, then run it with `a b`
 nish --help                       # the full flag list, stdout, exit 0
 ```
 
@@ -58,7 +59,9 @@ exclusive:
   `NL0000` a diagnostic with no rule yet.
 - **Exit codes**: `0` ok, `1` the program was rejected, `2` usage, `3` the C
   toolchain is unusable, `70` an internal compiler error — that last one is a
-  bug in `nish`, not in your program, and is worth reporting.
+  bug in `nish`, not in your program, and is worth reporting. `nish run`
+  answers the same codes until the program starts, and the program's own
+  status after that.
 - Every failure is a `--json` object, toolchain and internal errors included,
   so you never have to parse stderr to find out why a run failed.
 
@@ -195,16 +198,42 @@ const good = (a: i32, b: i64): i64 => {
 };
 ```
 
-**`integer` is reserved, not a type.** It is held for ranged integers
-(`integer<Lo, Hi>`), which the compiler does not build yet, so writing it as a
-type is refused. Declaring a type alias, enum, class, interface or function
-named `integer` is refused too. Use `i32`. A value named `integer` (a local
-or a module constant) is fine.
+**`integer<Lo, Hi>` is an `i32` that stays in `[Lo, Hi]`.** The bounds are two
+integer literals (a sign allowed) inside `i32`, and it is an `i32` everywhere
+the machine can see. Putting a value *into* one is checked: an `i32` or
+another range is compared once and the program panics (exit 1) outside the
+range, a literal outside it is a compile error, and a literal inside it or a
+narrower range costs nothing. So does a value a loop condition or a guard
+already bounds (`b` below), and `toI32` of a `u8`; a check left inside a loop
+is a performance warning (NL9013) naming the guard that removes it. A range
+bounds an index too: `integer<0, 255>`, like `u8`, needs only a length guard of
+256. Taking one *out* is free: every operator reads
+it as `i32`, a `const` keeps the range and a `let` widens to `i32`. A `u8` is
+not an `integer<0, 255>` (convert with `toI32`), and a `declare function` may
+not mention a range. Put the range on the value you use, not on a loop
+counter, which has to leave the range to end the loop.
 
-```ts nish:err NL2333
-const clamp = (x: integer): i32 => x;
+```ts nish:ok
+const getByte = (buf: u8[], i: integer<0, 255>): u8 => buf[i];
+
+const sumAll = (buf: u8[]): i32 => {
+  let sum = 0;
+  for (let i = 0; i < 256 && i < buf.length; i++) {
+    const b: integer<0, 255> = i;
+    sum = sum + toI32(getByte(buf, b));
+  }
+  return sum;
+};
+```
+
+```ts nish:err-body NL2384
+const digit: integer<0, 9> = 12;
 ```
 
+Declaring a type alias, enum, class, interface or function named `integer` is
+refused, because the name is the type. A value named `integer` (a local or a
+module constant) is fine.
+
 ```ts nish:err NL2332
 class integer {
   value: i32 = 0;
@@ -314,6 +343,8 @@ Narrowing follows the same engine as `T | null` below: it applies to a
 **variable**, never a property path; it ends at any assignment to that
 variable; and it is dropped before a loop that assigns it. `if (r.isOk()) A
 else B` narrows in `A`, and after the `if` when `B` cannot fall through.
+The proof stays with `r`: `const y = r`, `c ? r : q` and `[r]` are plain
+`Result`s, so test `y` itself before `y.value`.
 
 `panic(message)` is the other ending: message to stderr, exit 1. It is for an
 invariant that cannot hold, not for a failure a caller should handle. It
@@ -357,8 +388,9 @@ export const main = (): i32 => {
   `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
-  loop whose body, condition or update assigns it.
+- A narrowing ends at any assignment to the variable, including one in an
+  earlier operand of the same `&&` / `||` chain, and is dropped before a loop
+  whose body, condition or update assigns it.
 - Two nullables cannot be compared with each other; compare each with `null`.
 - `new Array<T | null>(n)` is allowed: the zero fill *is* `null`.
 
@@ -675,7 +707,7 @@ export const main = (): i32 => {
 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
+importing `nish/threads` writes two `.ll` files, so this one is compiled by
 `tests/link/par_map` and `tests/link/par_reduce` instead.)
 
 ```ts
@@ -720,6 +752,62 @@ import { parallelReduce } from "nish/threads";
 export const main = (): i32 => parallelReduce([1, 2, 3], (a, b) => a + b, 1);   // `+` folds from 0
 ```
 
+### Scoped tasks: `using s = scope()`
+
+Different functions at once, one thread each: open a scope with `using`, give
+it tasks with `spawn(entry, arg, dst, at)`, and every task has run and stored
+`entry(arg)` into `dst[at]` when the block ends. (A plain block, for the same
+reason as the one above: `tests/link/thread_scope_basic` compiles it.)
+
+```ts
+import { scope } from "nish/threads";
+
+const sumOf = (xs: f64[]): f64 => xs[0] + xs[1];
+const square = (n: i32): i32 => n * n;
+
+export const main = (): i32 => {
+  const xs: f64[] = [1.5, 2.5];
+  const sums: f64[] = [0.0];
+  const squares: i32[] = [0];
+  {
+    using s = scope();
+    s.spawn(sumOf, xs, sums, 0);
+    s.spawn(square, 12, squares, 0);
+  }                                          // joined here, on every exit
+  console.log(`${sums[0]} ${squares[0]}`);   // 4 144
+  return 0;
+};
+```
+
+- **The tasks run when the block ends**, together, and each answer is stored
+  after the last one finishes. So read a destination after the block. A
+  destination is a `const` bound to a fresh array (`[0, 0]`, `new Array`) that
+  you only index; never pass it on. Between the first `spawn` and the block's
+  end, don't read a destination, and don't write memory a task could read (a
+  store into an argument, a call that writes through its argument).
+- **`using` takes only `scope()`**, and `scope()` only comes from `using`.
+  The scope is only ever the receiver of a `spawn` statement: never pass it,
+  store it or return it.
+- **The task is a named top-level function**, not an arrow, and it follows the
+  data-parallel rules: it writes nothing anybody else can see, answers a number,
+  a `boolean` or an enum, and leaves `Arena` alone. A task cannot open a scope
+  of its own or call `parallelMapInto`.
+- **Any argument will do** — an array, an object — because nothing writes
+  memory while the tasks run. There is no thread count: one task, one thread.
+
+```ts nish:err NL2388
+import { scope } from "nish/threads";
+
+const one = (n: i32): i32 => n + 1;
+
+export const main = (): i32 => {
+  const out: i32[] = [0];
+  const s = scope();   // a scope must be introduced by `using`
+  s.spawn(one, 1, out, 0);
+  return out[0];
+};
+```
+
 ### Calling C
 
 `declare function name(params): T;` declares a C function this program calls but
@@ -952,6 +1040,11 @@ export const main = (): i32 => {
   annotation must match **exactly**. `const` freezes the binding, not the
   contents: `xs[0] = 1` and `xs.push(1)` on a `const xs` are fine.
 - `var` is forbidden. Destructuring is not supported.
+- **Semicolons are optional**, where TypeScript would insert one: at a line
+  break, before `}` and at the end of the file. It is TypeScript's rule, so a
+  line starting with `(` or `[` continues the one before it, and `return`
+  followed by a line break returns nothing. Here, the value left on the next
+  line is an unreachable-code error rather than a silent bug.
 - `for (init; cond; update)` with every clause optional, and
   `for (const x of xs)` over an **array** only — `x` gets the element type and
   must not be annotated. The array's `length` is re-read each iteration, so a
@@ -1159,6 +1252,37 @@ for (const e of m) {
 }
 ```
 
+Asking about one key twice costs one probe when the second call writes
+through the first: `m.set(k, E)` whose `E` reads `m.get(k)` or `m.has(k)`
+once, and `if (m.has(k)) { m.set(k, E); … }`, `if (!m.has(k)) { m.set(k, E); … }`
+or `if (!s.has(x)) { s.add(x); … }` with the write first in the branch. The
+receiver and key must be a local, a parameter or a `this.<field>` path (the key
+may be a literal), spelled the same in both calls, and nothing in between may
+call anything, allocate (`new`, a literal array or object, a template, a
+string `+`) or assign. Anything else still compiles, as one probe per call.
+`nish/map` adds `getOrInsert(m, k, v)` — the value of `k`, or `v` after
+inserting it — and `reserve(m, n)`, which sizes the table for `n` entries; both
+are one module with the program and run unchanged under Node.
+
+```ts nish:ok
+import { getOrInsert, reserve } from "nish/map";
+
+export const main = (): i32 => {
+  const words = ["to", "be", "or", "not", "to", "be"];
+  const counts = new Map<string, i32>();
+  reserve(counts, words.length);
+  for (const w of words) {
+    counts.set(w, (counts.get(w) ?? 0) + 1);   // one probe per word
+  }
+  const first = new Map<string, i32>();
+  for (let i = 0; i < words.length; i++) {
+    getOrInsert(first, words[i], i);           // one probe; inserts only the first time
+  }
+  console.log(`${counts.get("to") ?? 0} ${first.get("be") ?? -1}`);   // 2 1
+  return 0;
+};
+```
+
 ## Memory
 
 There is **no garbage collector and no `free`**, and nothing about this changes

package/docs/INSTALL.md

@@ -2,7 +2,7 @@
 
 `nish` compiles a static subset of TypeScript to LLVM IR and, with
 `--link`, to a native binary. The compiler is itself a native binary, written
-in Nish (`self/`), and needs nothing to run; the `--link` step (and anything
+in Nish (`src/`), and needs nothing to run; the `--link` step (and anything
 else that turns `.ll` into machine code) needs an LLVM toolchain.
 
 ## 1. Prerequisites
@@ -142,7 +142,7 @@ The npm route installs the **native** compiler, and it is a download rather than
 build: nothing is compiled on your machine. The package declares one
 `nish-<os>-<arch>` package per supported platform as an `optionalDependencies`
 entry with `os` and `cpu` set, so npm fetches exactly the one that matches and
-skips the rest. Each of those carries the self-hosted compiler — `self/`
+skips the rest. Each of those carries the self-hosted compiler — `src/`
 compiled by itself — already built, `--verify`d and smoke-tested on a machine
 of its own architecture by the release workflow.
 
@@ -198,7 +198,7 @@ nish: no prebuilt compiler for freebsd/x64
 
 Until 0.6.0 it ran the TypeScript compiler that shipped in the same package
 instead — the same compiler by every test here, about eight times slower, and
-no C toolchain needed. That compiler was `src/`, which was deleted in R6
+no C toolchain needed. That compiler was stage0, which was deleted in R6
 ([wp19](wp19-stage0-retirement.md)), so there is nothing left in the package to
 fall back to. The cost is stated where the rest of that deletion's costs are,
 in [wp19 §6](wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
@@ -218,7 +218,7 @@ routes are
   # in the glibc container, where build/nish runs
   build/nish app.ts -o app.ll
   # on the musl host, with its own clang and the runtime from this repository
-  clang app.ll runtime/runtime.c runtime/runtime_os.c -lm -o app
+  clang app.ll runtime/runtime.c runtime/runtime-os.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -268,7 +268,7 @@ npm install -g ./amritk-nish-0.4.0.tgz ./amritk-nish-x86_64-linux-0.4.0.tgz
 ```
 
 As a native compiler, which needs no Node at all. A release also attaches the
-self-hosted compiler — the binary `self/` produces by compiling itself — one
+self-hosted compiler — the binary `src/` produces by compiling itself — one
 per supported platform, from the version named in the last column:
 
 | Asset | For | Attached from |
@@ -326,7 +326,7 @@ release exists, take its version from
 Unpack it and run `bin/nish` from wherever you like; put that on `PATH` if you
 want it there. Keep the directory intact rather than moving the binary out of
 it: `--link` runs `scripts/build.sh` and compiles the C runtime
-(`runtime/runtime.c` and `runtime/runtime_os.c`, the system-call half), and the
+(`runtime/runtime.c` and `runtime/runtime-os.c`, the system-call half), and the
 compiler finds all of them relative to its own location — `bin/nish` alone in a
 directory can still emit IR with `-o`, but `--link` will tell you it cannot
 find `scripts/build.sh`.
@@ -367,23 +367,23 @@ Building the IR yourself rather than through `--link` means naming the runtime
 on the `clang` line, and it is two files:
 
 ```bash
-clang app.ll runtime/runtime.c runtime/runtime_os.c -lm -o app
+clang app.ll runtime/runtime.c runtime/runtime-os.c -lm -o app
 ```
 
 `runtime.c` is the half every program touches — the arena, strings, arrays,
-number formatting, the panics — and `runtime_os.c` is the half that wraps the
+number formatting, the panics — and `runtime-os.c` is the half that wraps the
 system calls: files, directories, subprocesses, `getenv`, the monotonic clock.
 They are separate so that each carries its own measured size ceiling
 ([docs/wp7-runtime.md](wp7-runtime.md)); nothing in the core calls into the
 system-call half, so an older line that names `runtime.c` alone still links a
 program that reads no files and spawns nothing. `scripts/build.sh` compiles
-`runtime_os.c` beside any `runtime.c` it is handed, so a build that goes
+`runtime-os.c` beside any `runtime.c` it is handed, so a build that goes
 through it — every `--link`, and every `--profile` recipe in these documents —
 needs to name only the one.
 
 ## 2a. What `npm run build` does
 
-`self/` is the compiler, written in Nish, and it compiles itself
+`src/` is the compiler, written in Nish, and it compiles itself
 ([docs/wp14-selfhost.md](wp14-selfhost.md)). From a checkout, with clang on
 `PATH`, `npm run build` runs `scripts/bootstrap.sh` with the seed from §2:
 
@@ -406,11 +406,11 @@ binary itself. It looks for `scripts/build.sh` and the two `runtime/*.c` files
 one level up from wherever it was invoked, then in the working directory, so
 it wants a checkout or an installed package around it the way `nish` does.
 
-Because the seed is the last release, `self/` may only *use* in its own
+Because the seed is the last release, `src/` may only *use* in its own
 source the constructs that release compiles. A new construct is implemented
-in `self/` and becomes usable inside `self/` from the next release on; CI's
+in `src/` and becomes usable inside `src/` from the next release on; CI's
 `bootstrap` job is what checks that the released seed still builds stage1.
-Until R6 the seed was a TypeScript compiler in `src/`, run under Node; it was
+Until R6 the seed was a TypeScript compiler, stage0, run under Node; it was
 deleted once the native one answered every flag it did
 ([wp19](wp19-stage0-retirement.md)).
 
@@ -446,6 +446,21 @@ Other build profiles: `--profile size` (smallest binary), `--profile debug`
 (no optimisation, symbols kept). Run `nish --help` for every flag, and
 see the [README](../README.md) for the language subset.
 
+To use a program as a script rather than keep the binary, run it:
+
+```bash
+nish run hello.ts
+# hello from Nish
+```
+
+`nish run [options] <file.ts> [args ...]` compiles the file, links it into
+`$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
+been linked before, and starts it with the arguments after the file. The first
+run of a new edit pays for one link, and later runs start the cached binary.
+It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set,
+and refuses the run without them rather than keep a binary in a shared
+directory.
+
 ## 4. Exit codes
 
 | Code | Meaning |
@@ -454,6 +469,7 @@ see the [README](../README.md) for the language subset.
 | 1 | the program was rejected: compile error (`file:line:col: error: ...`), missing input file, or an `-o` layout that does not fit the module count |
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
+| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set it answers 3 |
 | 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Nish: an ahead-of-time compiler from a static subset of TypeScript to LLVM IR",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "!scripts/arrow-verify.mjs",
     "!scripts/arrowify.mjs",
     "!scripts/fetch-seed.sh",
+    "!scripts/check-filenames.mjs",
     "!scripts/check-pr-body.mjs",
     "!scripts/check-pr-body.test.mjs",
     "!scripts/changelog-gen.test.mjs",
@@ -45,7 +46,9 @@
     "test:nish": "build/nish tests/nish/run.ts -o build/nish-runner.ir/ --link build/nish-runner && build/nish-runner",
     "test:cli": "build/nish tests/nish/cli.ts -o build/nish-cli.ir/ --link build/nish-cli && build/nish-cli",
     "test:node": "node tests/differential/unmodified.js",
-    "lint": "biome check --formatter-enabled=false .",
+    "lint": "node scripts/check-filenames.mjs && biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:dead": "knip --no-progress",
     "format": "biome format --write .",
     "prepublishOnly": "npm run check && npm test",
     "changelog": "node scripts/changelog-gen.mjs"
@@ -74,14 +77,15 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@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"
+    "@amritk/nish-x86_64-linux": "0.13.0",
+    "@amritk/nish-aarch64-linux": "0.13.0",
+    "@amritk/nish-aarch64-darwin": "0.13.0",
+    "@amritk/nish-x86_64-darwin": "0.13.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",
     "@types/node": "^22.0.0",
+    "knip": "6.38.0",
     "typescript": "^5.6.0"
   }
 }

package/runtime/nish.d.ts

@@ -34,6 +34,8 @@
  * 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`).
+ * `nish/map`'s `reserve` and `getOrInsert` are not declared here either: they
+ * are ordinary source, `std/map.ts`, which `tsconfig.json` maps `nish/*` to.
  */
 
 // ---- Numeric widths (docs/LANGUAGE.md -> Types) ------------------------------
@@ -52,6 +54,12 @@ type u64 = number;
 type f32 = number;
 type f64 = number;
 
+// ---- Ranged integers (docs/wp31-ranged-integers.md) --------------------------
+//
+// An `i32` the compiler knows lies in `[Lo, Hi]`. The bounds are numeric
+// literal types, and `tsc` checks only that; the range itself is `nish`'s.
+type integer<Lo extends number, Hi extends number> = number;
+
 // ---- Result (docs/LANGUAGE.md -> Result and error handling) ------------------
 //
 // Modelled as the tagged union TypeScript would use anyway, intersected with
@@ -102,6 +110,19 @@ declare function Err<T, E>(error: E): Result<T, E>;
 // `Process` is not that lucky, so a project that needs `@types/node` for other
 // reasons should drop this file's `process` rather than fight it.
 
+/**
+ * The disposable protocol `using` reads (WP29 P2, docs/wp29-thread-surface.md
+ * §5): declared here so that a program using `nish/threads`'s scope needs no
+ * `"ESNext.Disposable"` in its `lib`. `nish` itself takes `using` only for a
+ * `scope()`, and `[Symbol.dispose]` only in `nish/threads`.
+ */
+interface SymbolConstructor {
+  readonly dispose: unique symbol;
+}
+interface Disposable {
+  [Symbol.dispose](): void;
+}
+
 interface Console {
   /** `x` and a newline to stdout. Statement position; exactly one argument. */
   log(x: string | number | boolean): void;
@@ -150,7 +171,7 @@ declare function writeError(s: string): void;
  * `message` and a newline to stderr, then exit 1. Terminates control flow, so
  * it is `never`: that is what lets `tsc` agree that a function ending in a
  * `panic` returns, and that `x` is not null after `if (x === null) { panic(...); }`
- * — the guard-then-panic shape `self/` uses everywhere in place of an assert.
+ * — the guard-then-panic shape `src/` uses everywhere in place of an assert.
  */
 declare function panic(message: string): never;
 /**

package/runtime/nish.h

@@ -2,10 +2,10 @@
  *
  * Include this from C drivers, N-API shims, or any other host that links the C
  * runtime next to compiled Nish modules. Everything here is a contract shared
- * with `self/runtime.ts` (the IR side) and the implementation, which is
+ * with `src/runtime.ts` (the IR side) and the implementation, which is
  * two translation units: `runtime/runtime.c` holds the core every program
  * touches — the arena, strings, arrays, number formatting, the panics — and
- * `runtime/runtime_os.c` holds everything that wraps a system call: the file
+ * `runtime/runtime-os.c` holds everything that wraps a system call: the file
  * functions, the directory and subprocess calls, `nish_getenv`, the monotonic
  * clock, `nish_platform` / `nish_arch`. They are separate so that each carries
  * its own measured code-size ceiling (docs/wp7-runtime.md, "Runtime additions
@@ -41,7 +41,7 @@ extern "C" {
  * ELF refuses to link that against a non-TLS definition. `scripts/build.sh
  * --threads` passes the macro to every input, which is how `nish --threads
  * --link` keeps the two halves in step. The same definition is in
- * runtime/runtime.c and runtime/runtime_wasm.c. */
+ * runtime/runtime.c and runtime/runtime-wasm.c. */
 #ifdef NISH_THREADS
 #define NISH_TLS _Thread_local
 #else
@@ -73,7 +73,7 @@ typedef struct nish_str {
  * `off` and `cap` are `uint64_t` and not `size_t` because that `i64` is what
  * the inlined fast path bumps and compares on every target: under wasm32 a
  * `size_t` pair would put them at bytes 4 and 8 while compiled code reads 8
- * and 16. runtime.c and runtime_wasm.c static-assert these offsets. */
+ * and 16. runtime.c and runtime-wasm.c static-assert these offsets. */
 struct nish_arena {
   char *buf;
   uint64_t off;
@@ -140,7 +140,7 @@ nish_str *nish_str_from_u64(uint64_t v);
 
 /* Process and file I/O (WP7). `nish_exit` never returns; the file functions
  * print a message to stderr and exit(1) on a fatal error. Everything from here
- * to the end of the clock section below is implemented in runtime_os.c, with
+ * to the end of the clock section below is implemented in runtime-os.c, with
  * `nish_random` and `nish_argv_init` the exceptions: neither asks the operating
  * system anything (the clock only seeds the first, and the entry point hands the
  * second its arguments), so both stay with the core. `nish_random` keeps one seed
@@ -181,11 +181,11 @@ void nish_append_file(const nish_str *path, const nish_str *data);
  * A returned array lives in the arena (valid until the next reset/release):
  * copy `len` elements out of `data` before recycling.
  *
- * An array field stored inside its object (`self/inline_arrays.ts`) is this
+ * An array field stored inside its object (`src/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
+ * with `h.data == (char *)slots` and `h.cap == K`; `src/runtime.ts`'s
+ * `ARRAY_TYPE` and `src/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;
@@ -260,7 +260,7 @@ int32_t nish_spawn(const nish_array *argv);
  * paths must differ: each is opened separately with its own offset, so naming
  * one file twice makes the streams overwrite each other instead of
  * interleaving; capture them apart and concatenate to merge them. One `static`
- * implementation in runtime_os.c backs both spawn builtins, which is what keeps
+ * implementation in runtime-os.c backs both spawn builtins, which is what keeps
  * the argument vector, the wait and the signal convention written once. */
 int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_str *err);
 
@@ -316,7 +316,7 @@ double nish_parse_number(const nish_str *s, int32_t mode);
 /* Checked integer division (Rust semantics): the failed-check path. */
 void nish_panic_div(bool by_zero);
 
-/* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime_parallel.c ----
+/* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime-parallel.c ----
  *
  * One region of work, divided. `nish_parallel_range` calls `body(lo, hi, ctx)`
  * once per chunk of a partition of `[0, len)`: contiguous chunks, at most one
@@ -341,6 +341,26 @@ typedef void (*nish_par_body)(int64_t lo, int64_t hi, void *ctx);
 int64_t nish_cpu_count(void);
 void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t grain);
 
+/* ---- A scope's tasks (wp29 stage P2), runtime/runtime-parallel.c ----
+ *
+ * `nish_scope_spawn` files one task under `scope`, an address the caller keeps
+ * alive until it joins: it copies `size` bytes of `payload` and keeps them with
+ * `run` and `finish`, and runs nothing yet. `nish_scope_join` takes every task
+ * filed under `scope`, runs `run(payload)` for each -- the first on the calling
+ * thread and each other on a thread of its own, which frees its arena before it
+ * exits -- waits for all of them, and then calls `finish(payload)` for each on
+ * the calling thread, in the order they were filed. Without `-DNISH_THREADS`,
+ * or when a thread cannot be created, a task runs on the calling thread, so
+ * running short of threads costs speed and never an answer.
+ *
+ * The preconditions are the language's (docs/LANGUAGE.md, "Scoped tasks"):
+ * `run` writes nothing another task or the caller can see, its result is a
+ * scalar it writes into its own payload, and only `finish`, on the calling
+ * thread, stores into memory the caller owns. */
+typedef void (*nish_task_fn)(void *payload);
+void nish_scope_spawn(void *scope, nish_task_fn run, nish_task_fn finish, const void *payload, int64_t size);
+void nish_scope_join(void *scope);
+
 #ifdef __cplusplus
 }
 #endif

package/runtime/nish.mjs

@@ -28,9 +28,9 @@
  *     so is every string offset. ASCII agrees; nothing else does.
  *   - **`a[i]` is unchecked**: out of range is `undefined` here and an exit-1
  *     panic natively. Only a program that indexes out of range can tell.
- *   - **Method dispatch is virtual under Node** and static natively, so an
- *     override reached through a base-typed value differs (LANGUAGE.md,
- *     "Method dispatch is static").
+ *   - **A record put into an array is shared here** and copied natively, and
+ *     `slice`, `new Array<T>(n)` and the typed-array names each differ too;
+ *     the document lists them.
  *   - **`orReturn()` does not propagate.** It throws a marker the rewriter's
  *     `try`/`catch` turns into an early `return`; unmodified there is no
  *     `catch`, so it escapes. `Ok`/`Err`/`isOk`/`isErr`/`value`/`error`/
@@ -54,6 +54,7 @@
  * harness already uses, so the two cannot drift apart: a semantic fixed there
  * is fixed here in the same commit.
  */
+import { registerHooks } from "node:module";
 import * as shim from "./shim.mjs";
 
 /** Install `value` as a global unless the program declared its own. */
@@ -141,3 +142,15 @@ provide("Arena", {
   reset: shim.arenaReset,
   used: shim.arenaUsed,
 });
+
+// The standard library. A program imports it as `nish/<module>`, which the
+// compiler resolves to `std/<module>.ts` beside itself; this does the same for
+// Node, relative to this file rather than to the program, so the same
+// specifier works from any directory. Only the `nish/` package is answered
+// here, and every other specifier goes to Node as it was written.
+registerHooks({
+  resolve: (specifier, context, next) =>
+    specifier.startsWith("nish/")
+      ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
+      : next(specifier, context),
+});

package/runtime/{runtime_os.c → runtime-os.c}

@@ -319,7 +319,7 @@ nish_str *nish_realpath(const nish_str *path) {
    this file is compiled — a cross build compiles the runtime for the target,
    so the answer is the target's — which is why each is a string in constant
    data handed back by address: no allocation and no load, and `readnone` on
-   the declaration (self/runtime.ts) is a fact rather than a hope. The
+   the declaration (src/runtime.ts) is a fact rather than a hope. The
    spellings are Node's, so a program reads the same answer from this runtime
    and from `runtime/shim.mjs`; anything neither branch names is "unknown",
    which is what `--target host` then refuses. Contracts: nish.h.