@amritk/nish 0.12.0 → 0.14.0

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;
@@ -243,6 +243,12 @@ bool nish_is_dir(const nish_str *path);
  * under WASI: `fd_readdir` lists a preopened directory rather than a path, so
  * porting this there is a different contract and not a translation. */
 nish_array *nish_readdir(const nish_str *path);
+/* `readFileBytesSync(path)` (WP34 N2): the file's bytes as a `u8[]` with
+ * `len == cap`, zero bytes and bytes of 0x80 and above kept as they are, or
+ * NULL for every path `nish_read_file_or_null` answers NULL for. The header
+ * and the bytes live in the arena, so copy what you keep before the next reset
+ * or release. */
+nish_array *nish_read_file_bytes(const nish_str *path);
 /* `spawnSync(argv)`: run element 0 of `argv` (searched on `PATH`) with `argv`
  * as its argument vector, wait for it, and answer its exit status, or
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
@@ -260,7 +266,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);
 
@@ -306,6 +312,31 @@ const nish_str *nish_arch(void);
  * region into one and measure zero. */
 int64_t nish_monotonic_nanos(void);
 
+/* ---- The host (WP34 N3), runtime/runtime-host.c --------------------------
+ * `Date.now()`: the wall clock, `CLOCK_REALTIME`, in whole milliseconds since
+ * the epoch, as JavaScript answers it. Unlike `nish_monotonic_nanos` it can go
+ * backwards when the clock is corrected; it is for a time a person or a
+ * certificate means, not for measuring an interval. */
+double nish_date_now(void);
+/* `crypto.getRandomValues(bytes)`: fills `bytes->len` bytes from the kernel's
+ * CSPRNG (`getrandom` on Linux, `getentropy` elsewhere). More than 65,536
+ * bytes, the Web API's limit for one call, and a failing entropy source both
+ * print a message and exit 1; nothing weaker is ever substituted. */
+void nish_random_fill(nish_array *bytes);
+/* `statMtimeSync(path)`: the modification time in milliseconds with its
+ * sub-millisecond fraction, computed as Node's `mtimeMs` is, or NaN when
+ * `stat` fails. Follows a symbolic link. */
+double nish_stat_mtime(const nish_str *path);
+/* `signalFd()`: a descriptor that becomes readable when SIGTERM or SIGINT
+ * arrives: the read end of a pipe that a `sigaction` handler writes each
+ * signal's number to, whichever thread the signal lands on. Nothing is
+ * blocked. Made once; every call answers the same descriptor, and -1 when it
+ * could not be made. `readSignal(fd)`: block until one arrives and
+ * answer its number (15 or 2), or -1 for any `fd` that is not that descriptor
+ * or a read that fails. */
+int32_t nish_signal_fd(void);
+int32_t nish_read_signal(int32_t fd);
+
 /* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
  * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`
  * (the whole string, trimmed; blank is 0; `0x` hex accepted, as in JS),
@@ -316,7 +347,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 +372,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`/
@@ -84,6 +84,7 @@ provide("writeError", shim.writeError);
 provide("panic", shim.panic);
 provide("readFileSync", shim.readFileSync);
 provide("readFileSyncOrNull", shim.readFileSyncOrNull);
+provide("readFileBytesSync", shim.readFileBytesSync);
 provide("writeFileSync", shim.writeFileSync);
 provide("appendFileSync", shim.appendFileSync);
 provide("mkdirSync", shim.mkdirSync);
@@ -93,6 +94,35 @@ provide("realpathSync", shim.realpathSync);
 provide("spawnSync", shim.spawnSync);
 provide("spawnSyncTo", shim.spawnSyncTo);
 provide("getenv", shim.getenv);
+provide("statMtimeSync", shim.statMtimeSync);
+provide("signalFd", shim.signalFd);
+provide("readSignal", shim.readSignal);
+
+// `crypto.getRandomValues(bytes)` (WP34 N3). Node has the global, but it
+// takes only a typed array and a `u8[]` is a plain `Array` here, so the one
+// method is replaced on Node's own `crypto` object by one that fills a plain
+// array too (and hands a typed array to the original).
+Object.defineProperty(globalThis.crypto, "getRandomValues", {
+  value: shim.getRandomValues,
+  writable: true,
+  configurable: true,
+});
+
+// `dst.set(src, offset)` (WP34 N2). A `u8[]` is a plain `Array` here, which
+// has `fill` with the typed array's meaning already but no `set`, so the one
+// method is added to `Array.prototype` — non-enumerable, as a builtin method is,
+// so no `for...in` sees it — unless something got there first. It copies the
+// source before writing, as the native `memmove` does, and fails a range past
+// the end with the native panic.
+if (!("set" in Array.prototype)) {
+  Object.defineProperty(Array.prototype, "set", {
+    value: function set(source, offset) {
+      shim.arraySet(this, source, offset);
+    },
+    writable: true,
+    configurable: true,
+  });
+}
 
 // The clock. `monotonicNanos()` answers an `i64`, so the value is a BigInt here
 // as it is in the rewritten runner — and unusually for the i64 surface that is
@@ -117,6 +147,11 @@ provide("toU64", (x) => shim.convert(x, "f64", "u64"));
 provide("f64ToBits", shim.f64ToBits);
 provide("bitsToF64", shim.bitsToF64);
 
+// Constant time (WP34 N6). Pure functions of their operands, so the answers
+// agree with a native run; the timing does not, and is not claimed here.
+provide("ctSelect", shim.ctSelect);
+provide("ctEq", shim.ctEq);
+
 // `Result`. Everything works but `orReturn`, which needs the caller's control
 // flow and therefore the rewriter; see the header.
 provide("Ok", shim.Ok);

package/runtime/runtime-host.c

@@ -0,0 +1,178 @@
+/* Nish runtime, the host half: the wall clock, entropy, a file's modification
+ * time and a descriptor that becomes readable when SIGTERM or SIGINT arrives
+ * (WP34 N3) — the four facts a program that runs for days asks of the machine
+ * it runs on.
+ *
+ * A translation unit of its own for the reason runtime-os.c is one: each file
+ * carries its own measured `.text*` ceiling in tests/run.js. runtime-os.c had
+ * 143 bytes of its ceiling left when these arrived, the four measure more than
+ * that, and a ceiling is not raised to make room (docs/MASTER_PLAN.md §2 has
+ * the numbers). Section GC still means a program that calls none of them pays
+ * for none of them, and scripts/build.sh pairs this file with runtime.c like
+ * the other two halves, so a link line still names one runtime.
+ *
+ * Every function here is platform code, and the two platforms differ in three
+ * places: `getrandom` on Linux and `getentropy` elsewhere, `st_mtim`
+ * against Darwin's `st_mtimespec`, and `pipe2` against `pipe` for the signal
+ * descriptor. A WASI build has none of this
+ * (the checker refuses all four under a wasm target), so there the file is
+ * empty.
+ */
+#if defined(__wasi__) || defined(__wasm__)
+/* ISO C wants at least one declaration in a translation unit. */
+typedef int nish_host_unused;
+#else
+#if defined(__linux__)
+/* glibc declares `clock_gettime`, `sigaction` and `pipe2` under `-std=c11`
+   only with a feature macro, and `pipe2` only with this one. Darwin declares
+   everything by default and hides `getentropy` and the `st_mtimespec`
+   spelling behind a strict feature level, so it gets none. */
+#define _GNU_SOURCE
+#endif
+#include <errno.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/random.h>
+
+#include "nish.h"
+
+/* The spelling runtime.c and runtime-os.c use for their cold paths. */
+#define NISH_COLD __attribute__((noreturn, cold, noinline))
+
+/* `Date.now()`: `CLOCK_REALTIME` in whole milliseconds since the epoch, as
+   JavaScript answers it — the milliseconds are counted in integers and then
+   converted, so the answer is exact until the year 287,396 and a negative
+   time floors the way `Date.now` does rather than rounding towards zero. */
+double nish_date_now(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_REALTIME, &ts);
+  return (double)((int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000);
+}
+
+static NISH_COLD void nish_entropy_fail(uint64_t asked) {
+  if (asked > 65536) {
+    dprintf(2, "crypto.getRandomValues: %llu bytes asked for, and one call fills at most 65536\n",
+            (unsigned long long)asked);
+  } else {
+    dprintf(2, "crypto.getRandomValues: the system's entropy source failed\n");
+  }
+  _exit(1);
+}
+
+/* `crypto.getRandomValues(bytes)`: every byte of `bytes` from the kernel's
+   CSPRNG, or a panic. There is no fallback to a weaker source, because a
+   program handed predictable bytes for a key or a nonce cannot tell. The Web
+   API's limit of 65,536 bytes a call is kept, so a program behaves the same
+   under Node. `getrandom` without flags blocks only until the pool is first
+   initialised at boot and can return short or be interrupted, so it loops;
+   `getentropy` fills at most 256 bytes a call and retries nothing itself. */
+void nish_random_fill(nish_array *bytes) {
+  uint64_t n = bytes->len;
+  char *p = bytes->data;
+  if (n > 65536) nish_entropy_fail(n);
+  while (n > 0) {
+#if defined(__linux__)
+    ssize_t got = getrandom(p, n, 0);
+    if (got < 0) {
+      if (errno == EINTR) continue;
+      nish_entropy_fail(0);
+    }
+#else
+    size_t got = n < 256 ? n : 256;
+    if (getentropy(p, got) != 0) nish_entropy_fail(0);
+#endif
+    p += got;
+    n -= (uint64_t)got;
+  }
+}
+
+/* `statMtimeSync(path)`: the modification time in milliseconds, with the
+   sub-millisecond part the file system keeps, or NaN when `stat` fails. The
+   arithmetic is Node's `mtimeMs` operation for operation — seconds times 1e3
+   plus nanoseconds over 1e6, in doubles — so the two readings print the same
+   digits. `stat` follows a symbolic link, as `fs.statSync` does. */
+double nish_stat_mtime(const nish_str *path) {
+  struct stat st;
+  if (stat(path->data, &st) != 0) return __builtin_nan("");
+#if defined(__APPLE__)
+  struct timespec t = st.st_mtimespec;
+#else
+  struct timespec t = st.st_mtim;
+#endif
+  return (double)t.tv_sec * 1e3 + (double)t.tv_nsec / 1e6;
+}
+
+/* ---- Signals: `signalFd()` and `readSignal(fd)`
+ *
+ * A descriptor rather than a handler in the language, because a handler would
+ * be a function value the language does not have, and because a descriptor is
+ * what a loop waiting in `epoll` or `poll` can wait on beside its sockets.
+ *
+ * Underneath it is a C handler writing each signal's number, one byte, to a
+ * pipe. It is not a `signalfd` on Linux, deliberately: a `signalfd` only
+ * hears a signal that is blocked in **every** thread, and a mask reaches only
+ * the calling thread, so a `scope()` task or a parallel worker already
+ * running when `signalFd()` was called would take the signal at its default
+ * action and end the process. A handler runs in whichever thread the kernel
+ * picks, so no thread's mask matters, and nothing is blocked for a child
+ * `spawnSync` starts to inherit: `exec` resets a caught signal to its
+ * default. Installing the handler also overrides a disposition the process
+ * was started with, so a signal its parent ignored is heard, as
+ * `process.on('SIGTERM')` hears it under Node.
+ *
+ * The handler is the whole of what runs in signal context, and `write` is
+ * async-signal-safe. The write end is non-blocking, so a thousand unread
+ * signals lose the newest rather than wedge the handler, and `errno` is put
+ * back for the code the signal interrupted. The descriptor is made once and
+ * every later `signalFd()` answers the same one. */
+static int nish_signal_read_end = -1;
+static int nish_signal_write_end = -1;
+
+static void nish_on_signal(int sig) {
+  int saved = errno;
+  unsigned char b = (unsigned char)sig;
+  (void)!write(nish_signal_write_end, &b, 1);
+  errno = saved;
+}
+
+int32_t nish_signal_fd(void) {
+  if (nish_signal_read_end >= 0) return nish_signal_read_end;
+  int p[2];
+#if defined(__linux__)
+  /* Both ends close-on-exec from the moment they exist, so a child a sibling
+     thread spawns meanwhile cannot inherit either. */
+  if (pipe2(p, O_CLOEXEC) != 0) return -1;
+#else
+  /* Darwin has no `pipe2`, so there is a window between `pipe` and the two
+     `fcntl`s in which a child spawned by another thread inherits the ends. */
+  if (pipe(p) != 0) return -1;
+  fcntl(p[0], F_SETFD, FD_CLOEXEC);
+  fcntl(p[1], F_SETFD, FD_CLOEXEC);
+#endif
+  fcntl(p[1], F_SETFL, O_NONBLOCK);
+  nish_signal_write_end = p[1];
+  struct sigaction sa;
+  sa.sa_handler = nish_on_signal;
+  sa.sa_flags = SA_RESTART;
+  sigemptyset(&sa.sa_mask);
+  sigaction(SIGINT, &sa, 0);
+  sigaction(SIGTERM, &sa, 0);
+  return nish_signal_read_end = p[0];
+}
+
+/* Block until a signal's byte arrives and answer it: 15 or 2, or -1 for any
+   `fd` that is not the signal descriptor and for a read that fails. */
+int32_t nish_read_signal(int32_t fd) {
+  if (fd != nish_signal_read_end) return -1;
+  unsigned char b;
+  ssize_t n;
+  do n = read(fd, &b, 1);
+  while (n < 0 && errno == EINTR);
+  return n == 1 ? (int32_t)b : -1;
+}
+#endif

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

@@ -102,6 +102,21 @@ nish_str *nish_read_file_or_null(const nish_str *path) {
   return s;
 }
 
+/* `readFileBytesSync(path)` (WP34 N2): the same read, handed to the language as
+   a `u8[]`. The bytes are not copied a second time: `nish_read_file_or_null`
+   has already put them in the arena behind their 8-byte length, 8-aligned, so
+   the header points `data` there with `len == cap`, and the NUL written after
+   them is simply never indexed. Nothing on the way assumes UTF-8, so a zero
+   byte and a byte of 0x80 or above come back as they are on disk. A `push`
+   onto the result grows it into a fresh block, as it would any full array. */
+nish_array *nish_read_file_bytes(const nish_str *path) {
+  nish_str *s = nish_read_file_or_null(path);
+  if (!s) return 0;
+  nish_array *a = nish_alloc_struct(sizeof *a);
+  *a = (nish_array){ s->len, s->len, s->data };
+  return a;
+}
+
 nish_str *nish_read_file(const nish_str *path) {
   nish_str *s = nish_read_file_or_null(path);
   if (!s) nish_io_fail("read ", path);
@@ -319,7 +334,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.

package/runtime/{runtime_parallel.c → runtime-parallel.c}

@@ -1,9 +1,9 @@
 /* Nish runtime, the parallel half: how one range of work becomes several
  * threads, and nothing else.
  *
- * A third translation unit rather than a third of `runtime_os.c`, for the
+ * A third translation unit rather than a third of `runtime-os.c`, for the
  * reason that file's header gives for being a second one: a budget should mean
- * one thing. `runtime_os.c` is the syscall wrappers and it had 29 bytes of its
+ * one thing. `runtime-os.c` is the syscall wrappers and it had 29 bytes of its
  * ceiling left; `pthread_create` plus a partitioner does not fit in 29 bytes,
  * and raising the syscall half's ceiling to make room would move the number a
  * reader sees for "the operating-system surface" for a reason that has nothing
@@ -21,11 +21,16 @@
  * function exists. The thread-local arena the divided case needs is WP20 T0 and
  * arrives with the same macro.
  *
- * There is no language surface here and nothing in the language calls this yet:
- * docs/wp29-thread-surface.md is the surface, and this is the stage under it.
+ * docs/wp29-thread-surface.md is the surface this is the stage under: P1's
+ * `parallelMapInto` and `parallelReduce` divide a range here, and P2's scopes
+ * run their tasks here (`nish_scope_spawn`, `nish_scope_join`).
  */
 #include "nish.h"
 
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
 #if defined(NISH_THREADS) && !defined(__wasi__) && !defined(__wasm__)
 #define NISH_PAR_REAL 1
 #include <pthread.h>
@@ -154,3 +159,106 @@ void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t gra
   body(0, len, ctx);
 #endif
 }
+
+/* ---- A scope's tasks (wp29 P2) ----
+ *
+ * A task is filed when it is spawned and run when its scope joins, which is
+ * what keeps a scope race-free without a borrow checker: while the tasks run,
+ * the thread that opened the scope is inside the join and runs nothing else,
+ * the tasks write nothing but their own payloads (the language's rule), and
+ * every store into the caller's memory is a `finish` made on the caller's
+ * thread after the last task has finished.
+ *
+ * The filed tasks are one list per thread, newest first, and each carries the
+ * scope it belongs to. Only the thread that opened a scope files into it or
+ * joins it, so the list needs no lock, and scopes may nest: a join takes its
+ * own scope's tasks out of the list and leaves the rest. */
+typedef struct nish_task {
+  struct nish_task *next;
+  void *scope;
+  nish_task_fn run;
+  nish_task_fn finish;
+#ifdef NISH_PAR_REAL
+  pthread_t th;
+  int started;
+#endif
+  /* The copied payload, aligned for any field it holds. */
+  uint64_t payload[];
+} nish_task;
+
+static NISH_TLS nish_task *nish_tasks = 0;
+
+void nish_scope_spawn(void *scope, nish_task_fn run, nish_task_fn finish, const void *payload, int64_t size) {
+  nish_task *t = (nish_task *)malloc(sizeof(nish_task) + (size_t)size);
+  /* Out of memory is the end of the program, as it is for every other
+   * allocation the runtime makes: running the task here instead would store
+   * its answer ahead of tasks filed before it, and a later spawn into the same
+   * slot has to be the one that stays. */
+  if (!t) {
+    (void)!write(2, "nish: out of memory\n", 20);
+    _exit(1);
+  }
+  t->scope = scope;
+  t->run = run;
+  t->finish = finish;
+  memcpy(t->payload, payload, (size_t)size);
+  t->next = nish_tasks;
+  nish_tasks = t;
+}
+
+#ifdef NISH_PAR_REAL
+static void *nish_task_worker(void *p) {
+  nish_task *t = (nish_task *)p;
+  /* A task is one thread's work, as a chunk is, so a region inside it runs on
+   * this thread rather than multiplying the threads. */
+  nish_par_depth = 1;
+  t->run(t->payload);
+  nish_free_arena(); /* as `nish_par_worker`: this thread's arena, and only it */
+  return 0;
+}
+#endif
+
+void nish_scope_join(void *scope) {
+  /* This scope's tasks, oldest first: the list is newest first, and moving each
+   * one to the front of `mine` reverses it. */
+  nish_task *mine = 0;
+  nish_task **link = &nish_tasks;
+  while (*link) {
+    nish_task *t = *link;
+    if (t->scope == scope) {
+      *link = t->next;
+      t->next = mine;
+      mine = t;
+    } else {
+      link = &t->next;
+    }
+  }
+  if (!mine) return;
+#ifdef NISH_PAR_REAL
+  /* Every task but the first on a thread of its own, and the first on this
+   * one, so N tasks cost N-1 spawns and this thread is not idle. A task inside
+   * a region or another task's thread runs here, as a nested region does. */
+  for (nish_task *t = mine->next; t; t = t->next) {
+    t->started = nish_par_depth == 0 && pthread_create(&t->th, 0, nish_task_worker, t) == 0;
+  }
+  nish_par_depth++;
+  mine->run(mine->payload);
+  for (nish_task *t = mine->next; t; t = t->next) {
+    if (!t->started) t->run(t->payload);
+  }
+  nish_par_depth--;
+  for (nish_task *t = mine->next; t; t = t->next) {
+    if (t->started) pthread_join(t->th, 0);
+  }
+#else
+  for (nish_task *t = mine; t; t = t->next) t->run(t->payload);
+#endif
+  /* The stores, in the order the tasks were spawned, so two tasks with one
+   * destination leave the later one's answer there, as they would in sequence. */
+  while (mine) {
+    nish_task *t = mine;
+    mine = t->next;
+    t->finish(t->payload);
+    free(t);
+  }
+}

package/runtime/{runtime_wasm.c → runtime-wasm.c}

@@ -1,7 +1,7 @@
 /* Nish runtime for the freestanding wasm profile (WP8): the arena and the
  * array cold paths, without libc. Link it next to the module when a function
  * takes or returns an array:
- *   scripts/build.sh x.ll runtime/runtime_wasm.c -o x.wasm --profile wasm
+ *   scripts/build.sh x.ll runtime/runtime-wasm.c -o x.wasm --profile wasm
  *
  * Linear memory past `__heap_base` (the linker's end-of-data symbol) is one
  * arena chunk that grows with `memory.grow`; there is no chunk list because
@@ -97,3 +97,8 @@ void nish_panic_index(uint64_t idx, uint64_t len) { (void)idx; (void)len; __buil
 void nish_panic_slice(int64_t s, int64_t e, int64_t len) { (void)s; (void)e; (void)len; __builtin_trap(); }
 void nish_panic_div(_Bool by_zero) { (void)by_zero; __builtin_trap(); }
 void nish_exit(int32_t code) { (void)code; __builtin_trap(); }
+/* A panic's message (`panic`, `expect`, a failed range entry) has no stderr to
+ * go to here; the `nish_exit` that follows it is the trap. An exported function
+ * with a ranged parameter checks it on entry (WP31 §9), so this is what lets
+ * such a module link; the loader throws a RangeError before the call reaches it. */
+void nish_write(const void *s, int32_t fd, _Bool newline) { (void)s; (void)fd; (void)newline; }

package/runtime/runtime.c

@@ -4,13 +4,13 @@
  * it is also the half with the tighter size budget: the arena, strings, number
  * formatting, the array cold paths, `process.argv`, `Math.random`, and the two
  * panics. Files, directories, subprocesses, the environment and the clock are
- * in runtime_os.c — every one of those wraps a system call, so that surface
+ * in runtime-os.c — every one of those wraps a system call, so that surface
  * grows as the language reaches further into the operating system, and a
  * program that reaches nowhere should not pay for it or be measured with it.
- * runtime_os.c's header comment has the reasoning; tests/run.js gates the two
+ * runtime-os.c's header comment has the reasoning; tests/run.js gates the two
  * `.text*` budgets separately and docs/wp7-runtime.md records both.
  *
- * Nothing here calls into runtime_os.c, which is why an old link line that
+ * Nothing here calls into runtime-os.c, which is why an old link line that
  * names runtime.c alone still builds a program that uses none of that surface.
  * The other direction does happen: `nish_readdir` allocates through
  * `nish_alloc_struct` and `nish_str_new`, so those calls no longer inline into
@@ -50,7 +50,7 @@ int __main_argc_argv(int argc, char **argv) { return nish_c_main(argc, argv); }
    definition. Off by default so the ordinary build pays nothing.
 
    The same definition is in runtime/nish.h (for a host that includes it) and
-   runtime/runtime_wasm.c; they are one contract and move together. */
+   runtime/runtime-wasm.c; they are one contract and move together. */
 #ifdef NISH_THREADS
 #define NISH_TLS _Thread_local
 #else
@@ -59,7 +59,7 @@ int __main_argc_argv(int argc, char **argv) { return nish_c_main(argc, argv); }
 
 /* ---- Arena: %struct.nish_arena = type { i8*, i64, i64, i8* }
 
-   The widths are fixed rather than `size_t` for the reason runtime_wasm.c
+   The widths are fixed rather than `size_t` for the reason runtime-wasm.c
    gives for its own copy: every compiled function inlines the bump allocator
    and reads these fields directly, so the IR's `i64` is what `off` and `cap`
    have to be on every target, not just the 64-bit ones. With `size_t` they