@amritk/nish-x86_64-linux 0.18.0 → 0.20.0

package/INSTALL.md

@@ -109,7 +109,7 @@ Through npm, which is also how an Nish *program* resolves its dependencies
 the compiler pinned per project in a `package.json`:
 
 ```bash
-npm install -g @amritk/nish
+npm install -g nish
 nish --version
 ```
 
@@ -171,13 +171,12 @@ never fails over it.
 > underlying defect is [wp19 §5a](wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
 > item 4.
 
-**Do not install `nish`.** That name on the public registry has belonged to
-`stdarg`'s "A Node.js Interactive shell" since February 2014 — versions 0.0.0
-and 0.0.1, both deprecated by their author, nothing published since. **This
-compiler is `@amritk/nish`** (decided 2026-09-19,
-[docs/wp12-release.md](wp12-release.md#the-npm-name)), and the command it
-installs is still `nish` — the package name and the command are two different
-strings, and that is the one thing the scope costs.
+**The package is `nish` from 0.20.0.** Releases up to 0.18.0 were published
+as `@amritk/nish` (0.19.0's publish to npm failed), which is deprecated and
+points here; `npm install -g nish`
+replaces it ([docs/wp12-release.md](wp12-release.md#the-npm-name)). Versions
+0.0.0 and 0.0.1 of `nish` are an unrelated 2014 project that held the name
+before it, so pin `nish@^0.20.0` or later rather than an older range.
 
 **On a platform this project attaches no binary for, `npm install` gets you a
 command that refuses.** The table below is the whole list, so musl, FreeBSD and
@@ -224,7 +223,8 @@ routes are
   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 runtime/runtime-parallel.c \
-    runtime/runtime-host.c runtime/runtime-net.c -lm -o app
+    runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
+    runtime/runtime-simd.c runtime/runtime-aes.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -240,18 +240,20 @@ 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.
 
-**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
+**On the registry from 0.10.0** — as `@amritk/nish` through 0.18.0, and as
+`nish` from 0.20.0; 0.19.0 is on GitHub only, because its npm publish
+failed. 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
+`npm install -g 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` 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
-and `nish-<version>.tgz` for the releases cut before the scope was taken — the
-example below is one of those:
+after `package.json#name`, so it is `nish-<version>.tgz` before 0.4.0 and
+from 0.20.0 on, and `amritk-nish-<version>.tgz` from 0.4.0 to 0.19.0, while the
+package was scoped — the example below is one of the early ones:
 
 ```bash
 curl -LO https://github.com/amritk/nish/releases/download/v0.2.0/nish-0.2.0.tgz
@@ -358,7 +360,7 @@ it into `build/seed/`; `NISH_BOOTSTRAP=<path>` names one you already have and
 skips the download. §2a has what the build does with it.
 
 The published package ships `bin/` (the `nish` command, which is a launcher),
-`runtime/` (the C runtime — five translation units and their header),
+`runtime/` (the C runtime — eight translation units, the wasm subset and their header),
 `scripts/build.sh` (the link pipeline) and `std/` (the standard library). The
 compiler itself is not in it: it arrives as one prebuilt
 `@amritk/nish-<asset>` package per platform, and `bin/nish` hands over to
@@ -368,11 +370,12 @@ working directory — and the binary runs from inside its own platform package
 for exactly that reason.
 
 Building the IR yourself rather than through `--link` means naming the runtime
-on the `clang` line, and it is five files:
+on the `clang` line, and it is eight files:
 
 ```bash
 clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
-  runtime/runtime-host.c runtime/runtime-net.c -lm -o app
+  runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
+  runtime/runtime-simd.c runtime/runtime-aes.c -lm -o app
 ```
 
 `runtime.c` is the part every program touches — the arena, strings, arrays,
@@ -380,13 +383,16 @@ number formatting, the panics — and `runtime-os.c` wraps the system calls:
 files, directories, subprocesses, `getenv`, the monotonic clock.
 `runtime-parallel.c` divides work across threads for `nish/threads` (a
 program built with `--threads`, as every importer of `nish/threads` is, also
-needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-host.c` holds the
-wall clock, entropy, file times and signals, and `runtime-net.c` the sockets
-of `nish:net`. 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 others, so a line that names only
-`runtime.c` and `runtime-os.c` still links a program that uses none of the
-other three. `scripts/build.sh` compiles the other four beside any
+needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-cross.c` copies
+the strings and arrays a task answers, a channel sends or a `Mutex` keeps out
+of the arena they were made in, `runtime-host.c` holds the wall clock,
+entropy, file times and signals, `runtime-net.c` the sockets of `nish:net`,
+and `runtime-simd.c` and `runtime-aes.c` the vector text search and AES-GCM.
+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
+others, so a line that names only `runtime.c` and `runtime-os.c` still links a
+program that uses none of the other six. `scripts/build.sh` compiles the other
+seven 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.
 
@@ -479,6 +485,18 @@ refuses the run without one rather than keep a binary in a shared directory.
 The first run that builds into the cache makes its root `0700`, so no other
 user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
 
+Every link with the debug, speed or size profile, `nish run`'s and `--link`'s
+alike, keeps the compiled C runtime in `$XDG_CACHE_HOME/nish/runtime` (or
+`~/.cache/nish/runtime`), one entry per profile, `-g`, `--threads`, `CC` and
+the version that compiler reports, made `0700` the same way. The first link
+compiles the runtime's six files at once into it, and every later link
+compiles only the program's modules, also at once, and links against the
+entry: a `hello.ts` debug link goes from about half a second to about a
+tenth. `--link` with no absolute `HOME` or `XDG_CACHE_HOME`, or with a root
+it cannot make private, compiles the runtime itself as it always did; the
+wasi profile and `scripts/build.sh` called directly never use the cache.
+Removing the directory is always safe.
+
 ## 4. Exit codes
 
 | Code | Meaning |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.18.0",
-  "description": "The @amritk/nish native compiler for Linux on x86_64",
+  "version": "0.20.0",
+  "description": "The nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [
     "linux"

package/runtime/nish.d.ts

@@ -112,10 +112,10 @@ declare function Err<T, E>(error: E): Result<T, E>;
 
 /**
  * The disposable protocol `using` reads (WP29 P2, docs/wp29-thread-surface.md
- * §5): declared here so that a program using `nish/threads`'s scope or
- * `arena()` needs no `"ESNext.Disposable"` in its `lib`. `nish` itself takes
- * `using` only for a `scope()` or an `arena()`, and `[Symbol.dispose]` only in
- * `nish/threads`.
+ * §5): declared here so that a program using `nish/threads`'s scope, a
+ * `Mutex`'s lock or `arena()` needs no `"ESNext.Disposable"` in its `lib`.
+ * `nish` itself takes `using` only for a `scope()`, a `lock()` or an
+ * `arena()`, and `[Symbol.dispose]` only in `nish/threads`.
  */
 interface SymbolConstructor {
   readonly dispose: unique symbol;
@@ -124,6 +124,16 @@ interface Disposable {
   [Symbol.dispose](): void;
 }
 
+/**
+ * `String.fromBytes` is Nish's, not JavaScript's, so it merges into the
+ * `StringConstructor` `lib.es2022` declares. Under `runtime/nish.mjs` each byte
+ * becomes one UTF-16 unit, as `String.fromCharCode`'s does.
+ */
+interface StringConstructor {
+  /** The bytes of `bytes[start..end)` as one string; panics unless `0 <= start <= end <= bytes.length`. */
+  fromBytes(bytes: readonly u8[], start: number, end: number): string;
+}
+
 interface Console {
   /** `x` and a newline to stdout. Statement position; exactly one argument. */
   log(x: string | number | boolean): void;
@@ -193,7 +203,7 @@ declare function isExecutableSync(path: string): boolean;
 // ---- Unsafe (`nish:unsafe`) --------------------------------------------------
 //
 // Declared as globals so `tsc` reads a program that imports them, as every
-// `nish:` export is, but `nish` refuses a call to any of the five that is not
+// `nish:` export is, but `nish` refuses a call to any of the six that is not
 // imported from `nish:unsafe`: the import is the module's visible opt-in.
 
 /** `xs[i]` with no bounds check: undefined behaviour when `i` is out of range. */
@@ -206,6 +216,8 @@ declare function wrappingAdd<T extends i32 | i64>(a: T, b: T): T;
 declare function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
 /** `a * b` wrapped to the operands' width. */
 declare function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
+/** The `NUL`-terminated bytes at `p`, copied into a string: undefined behaviour unless `p` is a live C string. */
+declare function readCString(p: CPtr): string;
 
 // ---- Streams and files (globals: Nish has no package resolution) ---------
 
@@ -266,6 +278,28 @@ declare function spawnSync(argv: string[]): number;
  * either path is refused, as `writeFileSync` refuses one, and the answer is -1.
  */
 declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+/**
+ * Start `argv[0]` through `PATH` without waiting: the child's pid, or a
+ * negative errno. The child is the program's until `waitPid` reaps it. No
+ * reading under Node, which throws.
+ */
+declare function spawn(argv: string[]): i32;
+/**
+ * Send `sig` to `pid`: 0, or a negative errno (-3 when no such process). `sig`
+ * is 0, 2, 9 or 15, and anything else, like a `pid` of 0 or below, is -22.
+ */
+declare function kill(pid: i32, sig: i32): i32;
+/**
+ * Wait for the child `pid`, or any child for -1: `[pid, status]`, the status
+ * as `spawnSync` answers it. Flag 1 is WNOHANG, under which `[0, 0]` means a
+ * child remains and none has exited; a failure is `[-errno, 0]`, `[-10, 0]`
+ * with no child to wait for. No reading under Node, which throws.
+ */
+declare function waitPid(pid: i32, flags: i32): i32[];
+/** How many CPUs the program may use: at least 1, with or without `--threads`. */
+declare function availableParallelism(): i32;
+/** Bytes of physical memory, or -1 when the host does not say. */
+declare function totalMemory(): i64;
 /** One environment variable, or `null` when it is unset (an empty value is a set variable). */
 declare function getenv(name: string): string | null;
 /**
@@ -305,6 +339,8 @@ declare function netAddress(out: u8[], host: string, port: i32): i32;
 declare function netLocalPort(fd: i32): i32;
 /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
 declare function tcpListen(host: string, port: i32, backlog: i32): i32;
+/** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+declare function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
 /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
 declare function tcpAccept(fd: i32, peer: u8[]): i32;
 /** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
@@ -400,6 +436,16 @@ declare module "nish:process" {
    * at either path is refused, and the answer is -1.
    */
   export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+  /** Start a child without waiting: its pid, or a negative errno. */
+  export function spawn(argv: string[]): i32;
+  /** Send 0, 2, 9 or 15 to `pid`: 0, or a negative errno; any other signal is -22. */
+  export function kill(pid: i32, sig: i32): i32;
+  /** `[pid, status]` for a child that exited, `[0, 0]` under WNOHANG (flag 1) with none, or `[-errno, 0]`. */
+  export function waitPid(pid: i32, flags: i32): i32[];
+  /** How many CPUs the program may use, at least 1. */
+  export function availableParallelism(): i32;
+  /** Bytes of physical memory, or -1. */
+  export function totalMemory(): i64;
   /**
    * A monotonic clock in nanoseconds. The origin is arbitrary, so only the
    * difference between two reads is meaningful.
@@ -424,6 +470,8 @@ declare module "nish:net" {
   export function netLocalPort(fd: i32): i32;
   /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
   export function tcpListen(host: string, port: i32, backlog: i32): i32;
+  /** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+  export function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
   /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
   export function tcpAccept(fd: i32, peer: u8[]): i32;
   /** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
@@ -474,6 +522,8 @@ declare module "nish:unsafe" {
   export function wrappingSub<T extends i32 | i64>(a: T, b: T): T;
   /** `a * b` wrapped to the operands' width. */
   export function wrappingMul<T extends i32 | i64>(a: T, b: T): T;
+  /** The `NUL`-terminated bytes at `p`, copied into a string: undefined behaviour unless `p` is a live C string. */
+  export function readCString(p: CPtr): string;
 }
 
 declare module "nish:io" {

package/runtime/nish.h

@@ -8,11 +8,14 @@
  * `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` — and runtime-parallel.c, runtime-host.c,
- * runtime-net.c and runtime-simd.c (the byte searches that read a vector at a
- * time) split off the same way since. They are separate so that each carries
- * its own measured code-size ceiling (docs/wp7-runtime.md, "Runtime additions
- * and budget"); a host links all of them, which `scripts/build.sh` does for
- * you when handed runtime.c. `tests/run.js` checks that every runtime function
+ * runtime-net.c, runtime-simd.c (the byte searches that read a vector at a
+ * time) and runtime-aes.c (AES-GCM on the CPU's AES instructions) split off
+ * the same way since. They are separate so that each carries its own measured
+ * code-size ceiling (docs/wp7-runtime.md, "Runtime additions and budget"); a
+ * host links all of them, which `scripts/build.sh` does for you when handed
+ * runtime.c, runtime-aes.c included: the compiler calls its kernels from
+ * std/crypto/aes.ts, so `scripts/build.sh` pairs it and `src/run-cache.ts`
+ * caches it like the others. `tests/run.js` checks that every runtime function
  * declared in runtime.ts has a prototype in this file.
  *
  * Headers generated by `nish --emit-header` include this one, so keep
@@ -155,6 +158,18 @@ int64_t nish_str_index_of_any(const nish_str *s, const nish_str *set, int64_t fr
 void nish_print(const nish_str *s);
 /* `console.error` and the newline-free `write` / `writeError`: fd 1 or 2. */
 void nish_write(const nish_str *s, int32_t fd, bool newline);
+/* `panic(message)`, `expect` and a failed range entry: the message and a
+   newline on stderr, then `exit(1)`. Only the first panic of a process prints;
+   a thread that panics after it parks until that exit (`nish_panic_claim`). */
+__attribute__((noreturn)) void nish_panic(const nish_str *s);
+/* Called by every panic path before it prints: answers for the first caller
+   and parks every later one forever. Without threads no second caller can
+   exist, so it is empty there. */
+#ifdef NISH_THREADS
+void nish_panic_claim(void);
+#else
+#define nish_panic_claim() ((void)0)
+#endif
 /* Number to string, as `${n}` does: decimal for integers, shortest round-trip (JS Number#toString) for f64. */
 nish_str *nish_str_from_i32(int32_t v);
 nish_str *nish_str_from_f64(double v);
@@ -164,7 +179,8 @@ nish_str *nish_str_from_i64(int64_t v);
 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.
+ * print a message to stderr and `_exit(1)` on a fatal error, the first panic
+ * of a process only (`nish_panic_claim`).
  *
  * Every function here that takes a path, a name or an argument vector refuses
  * one holding a NUL, answering as it answers a path that does not exist: the
@@ -239,6 +255,45 @@ nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
  * elements themselves — which is why the checker refuses to let a program hold
  * a pointer to one across a `push` (WP15 section 2a). */
 void nish_array_grow(nish_array *a, uint64_t elem_size);
+/* ---- AES-GCM on the CPU's AES instructions (WP38 S5) ----------------------
+ * runtime/runtime-aes.c: AES-NI and PCLMULQDQ on x86-64, the ARMv8 AES and
+ * PMULL instructions on AArch64. The compiler calls each kernel in place of one
+ * private function of std/crypto/aes.ts, behind `nish_aes_hw`, and calls the
+ * bitsliced Nish function itself when that answers 0. The caller has checked
+ * every precondition: a kernel checks no bound, and reads and writes only
+ * what is listed. Every kernel is constant time in its key, its data and H.
+ *
+ * `rk` is a `u64[]` of `8 * (rounds + 1)` words, the length the bitsliced
+ * schedule has. On this path it holds, in bytes: the FIPS 197 schedule in
+ * [0, 16 * (rounds + 1)), round key r at 16 * r; H = E(K, 0^128), H^2, H^3 and
+ * H^4 at [240, 304), each as two u64s, low then high, of the block read
+ * big-endian; at [304, 368) each power's halves XORed together, twice over;
+ * and zero everywhere else. A process makes and uses every key under one
+ * answer of `nish_aes_hw`, so one array never meets both layouts. */
+/* 1 when this process runs the kernels, 0 when it runs the bitsliced Nish
+   code. Resolved on the first call and fixed from then on: `NISH_AES=soft`
+   pins 0; unset, `hw` or any other value is the best this machine has, read
+   on that call from CPUID leaf 1 (AES, PCLMULQDQ, SSSE3) or AArch64's
+   AT_HWCAP (AES, PMULL). Always 0 on other targets, wasm32 among them. */
+int32_t nish_aes_hw(void);
+/* `key` (u8[]) is 16 or 32 bytes and `rounds` 10 or 14 to match. Writes the
+   kernel layout above into all of `rk`. */
+void nish_aes_schedule(const nish_array *key, int32_t rounds, nish_array *rk);
+/* `src` and `dst` (u8[]) each hold at least 16 bytes: dst[0..16) = E(K, src[0..16)). */
+void nish_aes_block(const nish_array *rk, int32_t rounds, const nish_array *src, nish_array *dst);
+/* GCTR (SP 800-38D §6.5) from inc32(J0): dst[i] = src[i] ^ keystream[i] for
+   i < length, the counter J0's last four bytes read big-endian and wrapping
+   mod 2^32. `j0` (u8[]) is 16 bytes, 0 <= length <= min(src.len, dst.len),
+   and `dst` may be `src`. */
+void nish_aes_ctr(const nish_array *rk, int32_t rounds, const nish_array *j0, const nish_array *src,
+                  nish_array *dst, int32_t length);
+/* Absorbs data[0..length) (u8[]) into the GHASH state `y` (u64[2], the high
+   word first, each read big-endian), zero-padding the last block. `hHi:hLo` is
+   H, which the bitsliced walker reads; the kernel reads H and its powers from
+   `rk` instead, and they are the same H. 0 <= length <= data.len. */
+void nish_aes_ghash(nish_array *y, uint64_t hHi, uint64_t hLo, const nish_array *rk, const nish_array *data,
+                    int32_t length);
+
 /* `secureZero(bytes)` (#385): sets every byte of `bytes` to zero through
  * `volatile` stores, out of line, so that neither `-O2` nor `-flto` can drop
  * them as dead when the buffer's life ends straight after the call. For
@@ -313,6 +368,28 @@ int32_t nish_spawn(const nish_array *argv);
  * 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);
+/* `spawn(argv)` (WP34 N12): start element 0 of `argv` as `nish_spawn` does and
+ * answer the child's pid at once, without waiting, or a negative errno:
+ * -EINVAL for an empty `argv` or an argument holding a NUL, `posix_spawnp`'s
+ * own error otherwise, and -ENOSYS under WASI. The child is reaped by
+ * `nish_wait_pid`. */
+int32_t nish_spawn_child(const nish_array *argv);
+/* `kill(pid, sig)`: send `sig` to `pid` and answer 0, or a negative errno. Only
+ * 0, 2 (SIGINT), 9 (SIGKILL) and 15 (SIGTERM) are sent; any other signal, and
+ * a pid of 0 or below, is -EINVAL. -ESRCH when no process has the pid, -EPERM
+ * when it is another user's. Any process of this uid may be signalled, not
+ * only a child. */
+int32_t nish_kill(int32_t pid, int32_t sig);
+/* `waitPid(pid, flags)`: a fresh `i32[]` of two, `[pid, status]`. `pid` is a
+ * child's or -1 for any; flag 1 is WNOHANG and any other bit is -EINVAL, as is
+ * a pid that is neither -1 nor positive. The status is `nish_spawn`'s: the exit
+ * code, or `128 + n` for signal `n`. `[0, 0]` is a WNOHANG wait with a child
+ * left and none exited; a failure is `[-errno, 0]` (-ECHILD: no child; -EINTR:
+ * a signal interrupted the wait). In the arena. */
+nish_array *nish_wait_pid(int32_t pid, int32_t flags);
+/* `totalMemory()`: bytes of physical memory (Linux: `_SC_PHYS_PAGES` times the
+ * page size; Darwin: `hw.memsize`), or -1 where the host does not say. */
+int64_t nish_total_memory(void);
 
 /* ---- The environment (WP19 R1) ------------------------------------------
  * `getenv(name)`: the value of environment variable `name`, copied into the
@@ -410,6 +487,8 @@ bool nish_is_executable(const nish_str *path);
  * `nish_net_local_port(fd)`: the port a socket is bound to.
  * `nish_tcp_listen(host, port, backlog)`: `SO_REUSEADDR`, and `::` hears
  * both families, or IPv4 alone on a kernel without IPv6.
+ * `nish_tcp_listen_flags(host, port, backlog, flags)`: the same listener,
+ * with `SO_REUSEPORT` for flag 1 (any other bit is -22).
  * `nish_tcp_accept(fd, peer)`: a new descriptor and the peer's address.
  * `nish_net_read` / `nish_net_write(fd, buf, off, len)`: bytes `[off, off +
  * len)` of `buf`, which the compiled call has range-checked; a write to a
@@ -443,6 +522,7 @@ bool nish_is_executable(const nish_str *path);
 int32_t nish_net_address(nish_array *out, const nish_str *host, int32_t port);
 int32_t nish_net_local_port(int32_t fd);
 int32_t nish_tcp_listen(const nish_str *host, int32_t port, int32_t backlog);
+int32_t nish_tcp_listen_flags(const nish_str *host, int32_t port, int32_t backlog, int32_t flags);
 int32_t nish_tcp_accept(int32_t fd, nish_array *peer);
 int32_t nish_net_read(int32_t fd, nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t len);
@@ -480,12 +560,18 @@ void nish_panic_overflow(uint32_t op);
  *
  * 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
- * element apart in size, at most `nish_cpu_count()` of them and never more than
- * `len / grain`, with chunk 0 running on the calling thread. It returns when
- * every chunk has run.
+ * element apart in size, at most `NISH_PAR_PIECES` per thread over at most
+ * `nish_cpu_count()` threads and never more than `len / grain` rounded up, with
+ * chunk 0 running on the calling thread. Each thread takes the next chunk not
+ * yet started when it finishes one, so a thread that runs slower takes fewer.
+ * It returns when every chunk has run.
  *
- * Under `-DNISH_THREADS` the other chunks run on their own threads, each with
- * its own arena, which it frees before exiting. Without the macro -- and on
+ * Under `-DNISH_THREADS` the other chunks run on the worker pool: threads
+ * started on the first region or join that divides, one per CPU but the
+ * caller's, which park between calls. Each has its own arena, rewound after
+ * every chunk or task it runs. The caller takes chunks off the pool's queue too
+ * while it waits, so a chunk the caller took runs in the caller's arena, as
+ * chunk 0 does. Without the macro -- and on
  * WASI, which has no threads -- the whole range runs on the calling thread, so
  * the entry point exists either way and the flag decides only whether the work
  * is divided. A body that itself calls this runs its range on one thread: the
@@ -495,11 +581,31 @@ void nish_panic_overflow(uint32_t op);
  * the language surface above it will:
  *   - chunks run concurrently, so a body may read what the caller owns and may
  *     write only through storage the caller lent it and no two chunks share;
- *   - a body's result may not point into the arena, because a worker's arena is
- *     freed when its thread exits while chunk 0's is the caller's own. */
+ *   - nothing a body leaves in the arena outlives its chunk, because a worker's
+ *     arena is rewound after each chunk while chunk 0's is the caller's own: a
+ *     string or an array of scalars a chunk answers is moved to a transfer block
+ *     first (`nish_cross_keep`, below), and the compiler rewinds the caller's
+ *     arena after its chunks as the pool rewinds a worker's. */
 typedef void (*nish_par_body)(int64_t lo, int64_t hi, void *ctx);
+/* The CPUs a region may divide over: `nish_cpu_online()` under `--threads`,
+ * read once, and 1 in a sequential build. */
 int64_t nish_cpu_count(void);
+/* `availableParallelism()` (WP34 N12), in every build: the fewest of the CPUs
+ * online, those the affinity mask allows, the cgroup v2 `cpu.max` quota
+ * rounded up, and `NISH_NUM_THREADS` when it is set to a positive number. At
+ * least 1; 1 under WASI. Read each call (runtime-os.c). */
+int64_t nish_cpu_online(void);
 void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t grain);
+/* Keeps every later region and join on threads created and joined per call,
+ * as before the pool existed, so no parked worker outlives the code it would
+ * run: for a host that can unload the runtime. Call it before the first region
+ * or join; a pool already started stays. A Node addon calls it from the
+ * constructor below, because its shim includes <node_api.h> before this
+ * header, and Node can unload an addon while a pool's workers are parked. */
+void nish_pool_disable(void);
+#if defined(NAPI_VERSION) && defined(NISH_THREADS)
+__attribute__((constructor)) static void nish_napi_unpooled(void) { nish_pool_disable(); }
+#endif
 
 /* ---- A scope's tasks (wp29 stage P2), runtime/runtime-parallel.c ----
  *
@@ -507,11 +613,12 @@ void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t gra
  * 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.
+ * thread and the others on the worker pool, oldest first, with the calling
+ * thread taking any no worker is free for, in that order -- 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` every 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
@@ -521,6 +628,96 @@ 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);
 
+/* ---- A lock that owns its data (wp29 stage P3), runtime/runtime-parallel.c ----
+ *
+ * A `Mutex`'s lock is one `int32_t` word inside its guard: 0 free, 1 held. The
+ * compiler takes it inline, with an acquire compare-and-swap of 0 to 1, and
+ * gives it back inline, with a release store of 0 (src/emit-parallel.ts). Only
+ * a swap that finds the word held calls `nish_mutex_wait`, which returns once
+ * it has taken the lock itself: it spins briefly, then yields the processor
+ * between tries. The word lives in the arena with the rest of the `Mutex`, so
+ * there is nothing to create and nothing to destroy.
+ *
+ * The language holds one lock at a time and waits for nothing while it is
+ * held (docs/LANGUAGE.md, "A lock that owns its data"), so a holder always
+ * gives the word back and a waiter here always returns. Without real threads
+ * -- no `-DNISH_THREADS`, or WASI -- nothing else can hold the word, and the
+ * first try takes it. */
+void nish_mutex_wait(int32_t *word);
+
+/* ---- A channel of scalars or strings (wp29 stage P3), runtime/runtime-parallel.c ----
+ *
+ * A `Channel` object holds one `int64_t` word, `state`, and each function here
+ * takes its address: 0 before first use, then the address of a buffer, a lock
+ * and a count this file keeps outside every arena, then 1 once the receiver
+ * has drained it closed and it has been given back. A value is one 8-byte
+ * slot; the compiler widens a scalar into it and narrows it back, and a
+ * string travels as the block `nish_cross_send` copied it into, which the
+ * receiver's `nish_cross_in` frees. A string still in the buffer when the
+ * receiver stops early (a `break`) is given back with the buffer unread, so
+ * its block leaks.
+ *
+ * `nish_channel_send` appends and never waits: the channel is unbounded.
+ * `nish_channel_count` moves the count that keeps it open, which starts at 1:
+ * +1 at the spawn of each task that may send on it, -1 when that task returns,
+ * and -1 just before its scope joins. At zero the channel is closed.
+ * `nish_channel_receive` takes the next value into `*out` and answers 1,
+ * waiting while the channel is empty and open, or answers 0 once it is closed
+ * and empty, giving the buffer back the first time.
+ *
+ * The preconditions are the language's (docs/LANGUAGE.md, "Channels"): one
+ * receiver, every sender spawned before it, and no send once the scope's
+ * block has begun except by its tasks, so nothing touches a channel after its
+ * receiver has drained it. */
+void nish_channel_send(int64_t *state, int64_t value);
+void nish_channel_count(int64_t *state, int64_t delta);
+int32_t nish_channel_receive(int64_t *state, int64_t *out);
+
+/* ---- Copy at join: a string or a scalar array crosses threads ----
+ * runtime/runtime-cross.c
+ *
+ * A task's or a chunk's arena is rewound once its job is done, so a string or
+ * an array of scalars it answers or sends is copied out of it.
+ * `nish_cross_out(v, esize, mark)` runs on the thread that made `v`: when `v`
+ * was bumped in that thread's arena since `mark` (0: at any time) it answers a
+ * copy in a block of its own, outside every arena, with its low bit set; any
+ * other value, a literal or one an outer frame made, is answered as it is.
+ * `nish_cross_send(s)` is a channel send's: it copies every string `s`, so a
+ * send costs the string's length and not a walk of the sender's arena.
+ * `nish_cross_keep(v, esize, mark)` is a map element's: it moves `v` to the
+ * end of the chunk's transfer block and rewinds the arena to `mark`, the
+ * position before the body was called, so a chunk keeps one element's
+ * temporaries at a time. `nish_cross_begin(state, list)` pushes the chunk's
+ * transfer state, a `{ void *, void *, uint64_t, void * }` the caller holds,
+ * whose filled blocks go on `*list`, and `nish_cross_end(state)` pops it; with
+ * no list (a map's sequential path), or none pushed, keep copies `v` out and
+ * back in below `mark`. `nish_cross_adopt(list, dst, esize)` runs once every
+ * chunk is done, with `dst` the array the region wrote: 64 KB or more of
+ * blocks on a list become the newest chunks of the calling thread's arena,
+ * and less is copied into it, each element of `dst` in a block moved, and the
+ * blocks freed.
+ * `nish_cross_in(p, esize)` runs on the thread that takes the value: a tagged
+ * `p` of 64 KB or more that does not fit the arena's current chunk becomes a
+ * chunk of that arena; a smaller one is copied in and its block freed. Either
+ * way the block lives exactly as long as a copy would have. `esize` is 0 for a
+ * string and the element size of an array whose elements hold no pointer.
+ *
+ * `nish_guard_keep(old, s)` is a guard's string store (`g.value = s`): it
+ * answers a copy of `s` that the `Mutex` owns, outside every arena, and frees
+ * `old`, the string the slot held, when it is such a copy. `old` is null for a
+ * `string | null` slot that held none, and `s` is null for a `null` stored into
+ * one: the slot's copy is freed, nothing is kept, and the store answers null.
+ * A copy still held when its `Mutex` is dropped stays until the process ends:
+ * one block per string slot, not one per store. */
+void *nish_cross_out(void *v, uint64_t esize, uint64_t mark);
+void *nish_cross_send(void *s);
+void *nish_cross_keep(void *v, uint64_t esize, uint64_t mark);
+void *nish_cross_in(void *p, uint64_t esize);
+void nish_cross_begin(void *state, void **list);
+void nish_cross_end(void *state);
+void nish_cross_adopt(void *list, void *dst, uint64_t esize);
+void *nish_guard_keep(void *old, const void *s);
+
 #ifdef __cplusplus
 }
 #endif

package/runtime/nish.mjs

@@ -93,6 +93,13 @@ provide("readdirSync", shim.readdirSync);
 provide("realpathSync", shim.realpathSync);
 provide("spawnSync", shim.spawnSync);
 provide("spawnSyncTo", shim.spawnSyncTo);
+// WP34 N12. `spawn` and `waitPid` throw, naming themselves: a child is reaped
+// by Node's event loop. `kill`, `availableParallelism` and `totalMemory` answer.
+provide("spawn", shim.spawn);
+provide("kill", shim.kill);
+provide("waitPid", shim.waitPid);
+provide("availableParallelism", shim.availableParallelism);
+provide("totalMemory", shim.totalMemory);
 provide("getenv", shim.getenv);
 provide("statMtimeSync", shim.statMtimeSync);
 provide("signalFd", shim.signalFd);
@@ -104,6 +111,7 @@ for (const name of [
   "netAddress",
   "netLocalPort",
   "tcpListen",
+  "tcpListenFlags",
   "tcpAccept",
   "netRead",
   "netWrite",
@@ -225,6 +233,14 @@ provide("wrappingMul", (a, b) =>
 provide("Ok", shim.Ok);
 provide("Err", shim.Err);
 
+// `String.fromBytes` is Nish's own static on `String`, so it is added to
+// Node's `String` rather than installed as a global. Each byte is one UTF-16
+// unit, as `String.fromCharCode` makes it: ASCII agrees with a native run,
+// and a byte above 127 is the same divergence `fromCharCode`'s is.
+if (!("fromBytes" in String)) {
+  String.fromBytes = shim.fromBytes;
+}
+
 // The string parsers, whose deviations from JavaScript are documented rules
 // (base-10 `parseInt` that saturates, `parseFloat` that reads a `0x` prefix).
 globalThis.parseInt = shim.parseInt;