@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/runtime/nish.h

@@ -8,11 +8,15 @@
  * `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), runtime-aes.c (AES-GCM on the CPU's AES instructions) and
+ * runtime-term.c (stdin and the terminal, `nish:term`) 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
@@ -151,10 +155,45 @@ int64_t nish_str_index_of_from(const nish_str *s, const nish_str *sub, int64_t f
    set outside 1..16 bytes is answered by the scalar path rather than refused,
    but only 1..16 is the contract. Variable-time: never call it on a secret. */
 int64_t nish_str_index_of_any(const nish_str *s, const nish_str *set, int64_t from);
+/* WP38 S6a, the byte-class runs of `nish/bytes`: the first index i in
+   [from, to) whose byte p[i] is outside the class, or `to`. `p` is an array's
+   data and the caller has clamped 0 <= from <= to <= its length, so no byte at
+   or past `to` is read. `skip_blank` steps over JSON's four blanks (space, tab,
+   newline, carriage return) and `skip_digits` over 0-9. `skip_json_text` steps
+   over printable ASCII other than `"` and `\`, and over every well-formed
+   UTF-8 sequence (RFC 3629) that ends at or before `to`; a malformed or cut-off
+   sequence stops the run at its lead byte. `skip_json_plain` steps over every
+   byte from 0x20 up other than `"` and `\` -- what a JSON writer copies without
+   an escape -- with no UTF-8 check. They live in runtime/runtime-bytes.c and
+   choose their path as `nish_str_index_of_any` does. Variable-time: never call
+   them on a secret. */
+int64_t nish_bytes_skip_blank(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_digits(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_json_text(const uint8_t *p, int64_t from, int64_t to);
+int64_t nish_bytes_skip_json_plain(const uint8_t *p, int64_t from, int64_t to);
 /* `console.log(s)`: one write(2) of the bytes plus a newline to stdout. */
 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
+/* How a panic that skips atexit ends: `_exit(1)`, after `nish_fatal_hook`
+   when it is set (runtime.c). The hook is the terminal's restore while
+   `setRawMode(true)` holds or `setTerminalRestore` bytes wait
+   (runtime-term.c), and null otherwise. Under `-DNISH_FUZZ_ABORT`
+   (scripts/fuzz.sh) it and `nish_panic` call `abort()`. */
+__attribute__((noreturn)) void nish_fatal_exit(void);
+extern void (*nish_fatal_hook)(void);
 /* 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 +203,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
@@ -228,17 +268,73 @@ typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array
  * `elem_size` is `sizeof` one element, so for a record element type it is
  * `sizeof(struct Point)` and the block is a C array of them. */
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
+/* `nish/regex`'s match-start search: the first i >= from with i + depth <=
+   len where every s[i + j], j < depth, is in position j's byte set, or -1.
+   Position j's set is written twice: as the 32 bytes of masks from 32 * j,
+   where byte b is in it when bit (b >> 4) & 7 of byte (b & 15) | (b >> 7) << 4
+   is set, and as the 256 bytes from 32 * depth + 256 * j, where it is in it
+   when byte b of them is not 0; the two must agree. The vector paths look for
+   the width positions from off first, in the first form, and test the others
+   in the second; the answer does not depend on them. from is already in
+   [0, len], depth is 1..8, width is 1..4, off + width <= depth and masks
+   holds at least 288 * depth bytes. It lives
+   in runtime/runtime-simd.c and picks its path as nish_str_index_of_any does.
+   Variable-time: never call it on a secret. */
+int64_t nish_regex_scan(const nish_str *s, const nish_array *masks, int64_t depth, int64_t off, int64_t width,
+                        int64_t from);
 /* No array grows past 2^31 - 1 elements and no string past 2^31 - 1 bytes:
  * `nish_array_grow`, `nish_alloc_array` and `nish_str_concat` fail as an
  * allocation does (`nish: out of memory`, exit 1; a trap on wasm) rather than
  * make one, because under --number-mode i32 its `length` would read back
- * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2). */
+ * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2).
+ * A host that hands an array in keeps the same bound: the N-API shim refuses a
+ * longer typed array, and a C host must not pass a `len` past it
+ * (docs/security/bytes.md, BYTES-1). */
 /* The cold paths compiled code calls: `push` when len == cap, a failed bounds
  * check. `nish_array_grow` moves `cap * elem_size` bytes into a fresh arena
  * block and writes `data`/`cap`, so for a record element type it relocates the
  * 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
@@ -260,6 +356,13 @@ void nish_panic_slice(int64_t start, int64_t end, int64_t len);
 extern nish_array *nish_argv;
 void nish_argv_init(int32_t argc, char **argv);
 
+/* The 128-bit SipHash-1-3 key of every `Map` and `Set` string hash
+ * (docs/security/json.md, JSON-13). A constructor the compiled module
+ * registers fills it from `getentropy` before `main`, once per process, and
+ * sets bit 0 of word 0 so a filled key is never all zero; nothing writes it
+ * afterwards. A host must not change it while any table exists. */
+extern uint64_t nish_hash_key[2];
+
 /* ---- Directories and subprocesses (WP14 D4) -----------------------------
  * The calls a self-hosted driver needs to find its inputs and link its own
  * output. Every one of them answers a value instead of exiting, exactly as
@@ -313,6 +416,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 +535,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 +570,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);
@@ -461,6 +589,31 @@ int32_t nish_poll_modify(int32_t loop, int32_t fd, int32_t events, int32_t token
 int32_t nish_poll_remove(int32_t loop, int32_t fd);
 int32_t nish_poll_wait(int32_t loop, nish_array *ready, int32_t timeout_ms);
 
+/* ---- The terminal, runtime/runtime-term.c, `nish:term` -------------------
+ *
+ * `nish_read_stdin(buf, off, len)`: at most `len` bytes of stdin into `buf`
+ * from `off`, without blocking: the count, 0 at the end of the stream, -11
+ * when nothing is waiting, or another `-errno`. `nish_wait_stdin(timeout_ms)`:
+ * whether stdin became readable before `timeout_ms` passed (negative waits
+ * for ever). `nish_is_terminal(fd)`: `isatty`. `nish_terminal_size()`: a fresh
+ * `i32[]` of `[columns, rows]`, or `[-errno, 0]`, -25 for "not a terminal".
+ * `nish_set_raw_mode(on)`: 0, -25 when stdin is not a terminal, or `-errno`;
+ * the saved termios comes back on `false`, at exit, on a panic and on every
+ * signal left at its default that ends the program, SIGKILL aside (the list is
+ * runtime-term.c's). -11 and -25 are those
+ * numbers on WASI too, where the three TTY calls answer "not a terminal".
+ * `nish_set_terminal_restore(bytes)`: keeps up to `NISH_TERM_RESTORE_MAX`
+ * bytes to write to stdout, once, at exit, on a panic and on each of those
+ * signals, before the termios comes back; "" keeps none. 0, -7 past the cap,
+ * -25 when stdout is not a terminal (always, for bytes, on WASI). */
+#define NISH_TERM_RESTORE_MAX 4096
+int32_t nish_read_stdin(nish_array *buf, int64_t off, int64_t len);
+bool nish_wait_stdin(int32_t timeout_ms);
+bool nish_is_terminal(int32_t fd);
+nish_array *nish_terminal_size(void);
+int32_t nish_set_raw_mode(bool on);
+int32_t nish_set_terminal_restore(const nish_str *bytes);
+
 /* 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),
@@ -480,12 +633,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 +654,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 +686,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 +701,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

@@ -52,7 +52,10 @@
  *
  * Everything here delegates to `runtime/shim.mjs`, the module the differential
  * harness already uses, so the two cannot drift apart: a semantic fixed there
- * is fixed here in the same commit.
+ * is fixed here in the same commit. The shim is itself two layers: the
+ * host-agnostic core (`runtime/core.mjs`) and the Node host
+ * (`runtime/node.mjs`) it installs, so this module adds only what is Node's to
+ * add — the globals, the module hooks and `process.argv`.
  */
 import { registerHooks } from "node:module";
 import * as shim from "./shim.mjs";
@@ -93,6 +96,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 +114,7 @@ for (const name of [
   "netAddress",
   "netLocalPort",
   "tcpListen",
+  "tcpListenFlags",
   "tcpAccept",
   "netRead",
   "netWrite",
@@ -123,6 +134,17 @@ for (const name of [
   provide(name, () => shim.noNetReading(name));
 }
 
+// `nish:term`. Whether a descriptor is a terminal and how big stdout's is have
+// Node's answers; reading stdin, waiting for it and raw mode throw, each naming
+// itself, for the net functions' reason, and restore bytes throw for their own
+// (core/host.mjs).
+provide("isTerminal", shim.isTerminal);
+provide("terminalSize", shim.terminalSize);
+for (const name of ["readStdin", "waitStdin", "setRawMode"]) {
+  provide(name, () => shim.noTermReading(name));
+}
+provide("setTerminalRestore", shim.setTerminalRestore);
+
 // `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
@@ -171,6 +193,7 @@ provide("toU32", (x) => shim.convert(x, "f64", "u32"));
 provide("toU64", (x) => shim.convert(x, "f64", "u64"));
 provide("f64ToBits", shim.f64ToBits);
 provide("bitsToF64", shim.bitsToF64);
+provide("f32ToBits", shim.f32ToBits);
 
 // 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.
@@ -225,6 +248,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;
@@ -258,11 +289,13 @@ provide("arena", shim.arena);
 // `nish:secret` is answered here as well, because the standard library imports
 // it (`std/crypto/p256.ts` and its neighbours): its names are
 // `runtime/shim.mjs`'s, where a `Secret` is a plain wrapper and `wipe`
-// zero-fills it. `nish:unsafe` is answered by a module that hands back the
-// globals installed above: its functions are globals of this module either
+// zero-fills it. `nish:unsafe` and `nish:term` are each answered by a module
+// that hands back the globals installed above: its functions are globals of this module either
 // way, and the import is what the compiler requires a program to write.
 const UNSAFE_EXPORTS = ["uncheckedGet", "uncheckedSet", "wrappingAdd", "wrappingSub", "wrappingMul"];
 const unsafeSource = UNSAFE_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
+const TERM_EXPORTS = ["readStdin", "waitStdin", "isTerminal", "terminalSize", "setRawMode", "setTerminalRestore"];
+const termSource = TERM_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
 registerHooks({
   resolve: (specifier, context, next) => {
     if (specifier === "nish:secret") {
@@ -271,6 +304,9 @@ registerHooks({
     if (specifier === "nish:unsafe") {
       return { url: `data:text/javascript,${encodeURIComponent(unsafeSource)}`, shortCircuit: true };
     }
+    if (specifier === "nish:term") {
+      return { url: `data:text/javascript,${encodeURIComponent(termSource)}`, shortCircuit: true };
+    }
     return specifier.startsWith("nish/")
       ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
       : next(specifier, context);